BCP 47 Language Tag Parser

Common errors

• TypeError: Cannot read properties of null (reading 'language')

  cause Attempting to access properties of the object returned by `parse()` without checking if the tag was valid, leading to an attempt to access properties on `null`.
  fix Ensure the result of `parse()` is not `null` before attempting to access its properties. For example: `const parsed = parse(tag); if (parsed) { console.log(parsed.language); } else { console.error('Invalid BCP 47 tag'); }`

• TypeError: tag.toLowerCase is not a function

  cause Passing a non-string value (e.g., `null`, `undefined`, a number, or an object) to the `parse()` function, which expects a string.
  fix Always ensure the input to `parse()` is a string. Validate the input type before calling `parse()`: `if (typeof tag === 'string') { parse(tag); } else { /* handle invalid input type */ }`

Warnings

• gotcha The `parse` function returns `null` for any input that does not conform to the BCP 47 specification. This includes malformed tags, empty strings, or non-string inputs. Developers must explicitly check for `null` to avoid runtime errors when accessing properties of the parsed object.
  Fix: Always check the return value of `parse()`: `const result = parse(tag); if (result) { /* use result */ } else { /* handle invalid tag */ }`
• gotcha The package specifies `"engines": { "node": ">=0.10" }`, indicating compatibility with extremely old Node.js versions. While this might suggest broad compatibility, modern applications should be aware that the code may not leverage contemporary JavaScript features or optimizations. However, given recent releases (April 2026), it's more likely a legacy `package.json` entry or the project has been significantly updated recently.
  Fix: No direct fix for usage, but be mindful of the potential discrepancy between listed engine requirements and actual modern development practices. Test thoroughly on your target Node.js version.

Install

• npm install bcp47 npm
• yarn add bcp47 yarn
• pnpm add bcp47 pnpm

Imports

• parse
  wrong:

  import bcp47 from 'bcp47'; bcp47.parse(...);

  correct:

  import { parse } from 'bcp47';

  The `parse` function is a named export for ESM. It does not export a default.
• stringify
  wrong:

  const stringify = require('bcp47').stringify;

  correct:

  import { stringify } from 'bcp47';

  The `stringify` function is also a named export, complementing `parse` for reconstructing tags.
• parse (CommonJS)
  wrong:

  const bcp47 = require('bcp47'); const result = bcp47.parse('en-US');

  correct:

  const { parse } = require('bcp47');

  CommonJS users should prefer destructuring for named exports like `parse`.

Quickstart

Demonstrates parsing valid and invalid BCP 47 language tags, showing the structured output and the `null` return for invalid input. Also includes stringification.

import { parse, stringify } from 'bcp47';

// Example 1: Parsing a valid language tag
const tag1 = 'en-US-u-attr-value';
const parsedTag1 = parse(tag1);
console.log('Parsed Tag 1:', parsedTag1);
// Expected output: { language: 'en', extlangs: [], script: null, region: 'US', variants: [], extensions: [{ singleton: 'u', privateuse: 'attr-value' }], privateuse: null }

// Example 2: Parsing an invalid language tag
const tag2 = 'invalid-tag-$$';
const parsedTag2 = parse(tag2);
console.log('Parsed Tag 2 (invalid):', parsedTag2);
// Expected output: null

// Example 3: Parsing a tag with script and variant
const tag3 = 'zh-Hans-SG-pinyin';
const parsedTag3 = parse(tag3);
console.log('Parsed Tag 3:', parsedTag3);

// Example 4: Stringifying a parsed object back to a tag
if (parsedTag3) {
  const rebuiltTag = stringify(parsedTag3);
  console.log('Rebuilt Tag 3:', rebuiltTag);
}