ietf-language-tags, an npm package for i18n 🇺🇳

Tools for working with IETF language tags as specified by BCP 47 / RFC 5646.

• Validates given tag strings like zh-Hant-CN
• Interprets complicated (but valid) tags like zh-yue-Latn-CN-pinyin-a-extend1-x-foobar-private1
• Helps you with getting rid of redundant or deprecated tags
• Optionally checks given tags against a local copy of the central IETF language tag registry so don't let unregistered subtags slip through

Terminology

The terminology of this library follows RFC5646. To quote the specification:

• Tag refers to a complete language tag, such as sr-Latn-RS or az-Arab-IR.
• Subtag refers to a specific section of a tag, delimited by a hyphen, such as the subtags zh, Hant, and CN in the tag zh-Hant-CN.
• Code refers to values defined in external standards (and that are used as subtags in this document). For example, Hant is an ISO15924 script code that was used to define the Hant script subtag for use in a language tag.

Installation

npm install --save @sozialhelden/ietf-language-tags
#or
yarn add @sozialhelden/ietf-language-tags

Usage examples

• Parse a given IETF language tag to get access to its parts:

    const tag = parseLanguageTag(
      inputTag: 'sl-rozaj-biske',
      // Set to `true` for returning `undefined` for invalid tags,
      // outputting errors to the console.
      // Set to `false` to throw an error if a given tag is invalid.
      // The library tries to give helpful feedback for typical errors in tags.
      true,
      // Allows you to use your own logging function. Supply `null` to suppress console output.
      console.log
    )

  {
    "langtag": "sl-rozaj-biske",
    "language": "sl",
    "variants": ["rozaj", "biske"]
  }

• Get all information about a given language tag, including descriptions and registry meta infos:

  const tagMetaInfo = getTag('zh-yue-Latn-CN-pinyin-a-extend1-x-foobar-private1');

    {
      extlang: {
        Added: '2009-07-29',
        Description: ['Yue Chinese', 'Cantonese'],
        Macrolanguage: 'zh',
        'Preferred-Value': 'yue',
        Prefix: ['zh'],
        Subtag: 'yue',
        Type: 'extlang',
      },
      parts: {
        extensions: {
          a: 'extend1',
        },
        extlang: 'yue',
        langtag: 'zh-yue-Latn-CN-pinyin-a-extend1-x-foobar-private1',
        language: 'zh-yue',
        privateuse: 'x-foobar-private1',
        region: 'CN',
        script: 'Latn',
        variants: ['pinyin'],
      },
      privateuse: 'x-foobar-private1',
      region: {
        Added: '2005-10-16',
        Description: ['China'],
        Subtag: 'CN',
        Type: 'region',
      },
      script: {
        Added: '2005-10-16',
        Description: ['Latin'],
        Subtag: 'Latn',
        Type: 'script',
      },
      variants: [
        {
          Added: '2008-10-14',
          Description: ['Pinyin romanization'],
          Prefix: ['zh-Latn', 'bo-Latn'],
          Subtag: 'pinyin',
          Type: 'variant',
        },
      ],
    }

• Return a plain English description of a given tag

  describeIETFLanguageTag('zh-Hans'); // → 'Chinese, written in Han (Simplified variant) script'
  describeIETFLanguageTag('yue-HK'); // → 'Yue Chinese / Cantonese, as used in Hong Kong'
  describeIETFLanguageTag('es-419'); // → 'Spanish / Castilian, as used in Latin America and the Caribbean'

• Beautify tags to make them more readable

  normalizeLanguageTagCasing('sGn-Be-fR'); // → 'sgn-BE-FR'

• Get a language tag the IETF language tag registry prefers over the given tag

  getPreferredLanguageTag('zh-yue'); // → 'yue'
  getPreferredLanguageTag('i-klingon'); // → 'tlh'

• Get a specific, single subtag from the IETF language tag registry:

  getSubTag('extlang', 'hsn');

  {
    Type: 'language',
    Subtag: 'hsn',
    Description: ['Xiang Chinese'],
    Added: '2009-07-29',
    Macrolanguage: 'zh'
  }

• Match against a RegExp mimicking the RFC specs, without further semantic checks:

  const regexp = createRFC5646Regexp();
  const match = 'zh-yue-Latn-CN-pinyin-a-extend1-x-foobar-private1'.match(regexp);

  {
    region: "CN",
    script: "Latn",
    extlang: "yue",
    language: "zh-yue",
    variants: "-pinyin" // can contain one or more variants in one string
    extensions: "-a-extend1", // can contain one or more extensions in one string
    privateuse: "x-foobar-private1",
    privateuse2: undefined, // For tags that consist of nothing more than a private-use subtag
    langtag: "zh-yue-Latn-CN-pinyin-a-extend1-x-foobar-private1",
  }

Credits / License

Contributors to this package:

• Sebastian Felix Zappe

Thanks to @mcaruanagalizia for maintaining the language-subtag-registry NPM package, which this package relies on.

Update scripts copyright (c) 2013, Matthew Caruana Galizia and licensed under and MIT license.

The JSON database is licensed under the Open Data Commons Attribution License (ODC-BY).

Supported by

.