# bcp-47
[![Build][build-badge]][build]
[![Coverage][coverage-badge]][coverage]
[![Downloads][downloads-badge]][downloads]
[![Size][size-badge]][size]
Parse and stringify [BCP 47][spec] language tags.
## Contents
* [What is this?](#what-is-this)
* [When should I use this?](#when-should-i-use-this)
* [Install](#install)
* [Use](#use)
* [API](#api)
* [`parse(tag[, options])`](#parsetag-options)
* [`stringify(schema)`](#stringifyschema)
* [`Schema`](#schema)
* [`function warning(reason, code, offset)`](#function-warningreason-code-offset)
* [Types](#types)
* [Compatibility](#compatibility)
* [Security](#security)
* [Related](#related)
* [Contribute](#contribute)
* [License](#license)
## What is this?
This is a package that can parse BCP 47 language tags to an object representing
them, and serialize those objects back into language tags.
It supports a forgiving mode to handle incorrect BCP 47 tags and can emit
warnings about problems in incorrect tags.
## When should I use this?
You can use this package if you need to access the data stored in BCP 47
language tags.
You can also use this package if you want to check (lint) or manipulate tags.
## Install
This package is [ESM only][esm].
In Node.js (version 12.20+, 14.14+, or 16.0+), install with [npm][]:
```sh
npm install bcp-47
```
In Deno with [Skypack][]:
```js
import * as bcp47 from 'https://cdn.skypack.dev/bcp-47@2?dts'
```
In browsers with [Skypack][]:
```html
```
## Use
```js
import {parse, stringify} from 'bcp-47'
const schema = parse('hy-Latn-IT-arevela')
console.log(schema)
console.log(stringify(schema))
```
Yields:
```js
{ language: 'hy',
extendedLanguageSubtags: [],
script: 'Latn',
region: 'IT',
variants: ['arevela'],
extensions: [],
privateuse: [],
irregular: null,
regular: null }
'hy-Latn-IT-arevela'
```
## API
This package exports the following identifiers: `parse` and `stringify`.
There is no default export.
### `parse(tag[, options])`
Parse a BCP 47 tag into a language schema.
Note that the algorithm is case insensitive.
###### `options.normalize`
Whether to normalize legacy tags when possible (`boolean`, default:
`true`).
For example, `i-klingon` does not match the BCP 47 language algorithm but is
considered valid by BCP 47 nonetheless.
It is suggested to use `tlh` instead (the ISO 639-3 code for Klingon).
When `normalize` is `true`, passing `i-klingon` or other deprecated tags, is
handled as if their suggested valid tag was given instead.
###### `options.forgiving`
By default, when an error is encountered, an empty object is returned.
When in forgiving mode, all found values up to the point of the error
are included (`boolean`, default: `false`).
So, for example, where by default `en-GB-abcdefghi` an empty object is returned
(as the language variant is too long), in `forgiving` mode the `language` of
`schema` is populated with `en` and the `region` is populated with `GB`.
###### `options.warning`
When given, `warning` is called when an error is encountered
([`Function`][warning]).
###### Returns
Parsed BCP 47 language tag ([`Schema`][schema]).
###### Throws
When `tag` is `null` or `undefined`.
### `stringify(schema)`
Compile a [`schema`][schema] to a BCP 47 language tag.
###### Returns
BCP 47 language tag (`string`).
### `Schema`
A schema represents a language tag.
A schema is deemed empty when it has neither `language`, `irregular`, `regular`,
nor `privateuse` (where an empty `privateuse` array is handled as no
`privateuse` as well).
###### `schema.language`
Two or three character [ISO 639][iso-639] language code, four character reserved
language code, or 5 to 8 (inclusive) characters registered language subtag
(`string`).
For example, `en` (English) or `cmn` (Mandarin Chinese).
###### `schema.extendedLanguageSubtags`
Selected three-character [ISO 639][iso-639] codes(`Array`), such as
`yue` in `zh-yue-HK` (Chinese, Cantonese, as used in Hong Kong SAR).
###### `schema.script`
Four character [ISO 15924][iso-15924] script code (`string`), such as `Latn` in
`hy-Latn-IT-arevela` (Eastern Armenian written in Latin script, as used in
Italy).
###### `schema.region`
Two alphabetical character [ISO 3166-1][iso-3166-1] code or three digit
[UN M49][un-m49] code (`string`).
For example, `CN` in `cmn-Hans-CN` (Mandarin Chinese, Simplified script, as used
in China) or `419` in `es-419` (Spanish as used in Latin America and the
Caribbean).
###### `schema.variants`
5 to 8 (inclusive) character language variants (`Array`), such as
`rozaj` and `biske` in `sl-rozaj-biske` (San Giorgio dialect of Resian dialect
of Slovenian).
###### `schema.extensions`
List of extensions (`Array