Zero-dependency BCP 47 / RFC 5646 language tag toolkit for JavaScript and TypeScript

Built with AI, end to end. Every line in this repo — source, tests, docs, release scripts — is generated, reviewed, and verified through Claude Code.

• Strict conventions enforced by the agent. .claude/rules/ pin TypeScript strict mode, Array<T>, readonly by default, no any, semantic naming (no data / result / item), and 18 testing rules — applied on every change without manual review.
• Bundled Claude Code skills (commit, verify, review, release, testing) that drive the full lifecycle: lint → build → test → conventional commit → tag-triggered release with SLSA provenance via OIDC trusted publishing — powered by npm-trust (the /solo-npm:release skill itself comes from the solo-npm marketplace plugin).
• Co-located Vitest specs for every operator (parse, canonicalize, filter, lookup, extensionU / extensionT, acceptLanguage). The agent writes the failing test first, then makes it pass — pnpm test is the regression net, not a checkbox.
• PRs disabled by design. Contributors can't push code directly; the maintainer takes issues and discussions through Claude Code. See CONTRIBUTING.md for the full process.

• Parse any BCP 47 language tag into a structured, typed object
• Stringify a tag object back into a well-formed language tag string
• Canonicalize with case normalization and IANA registry data (deprecated subtags, suppress-script, extlang)
• Match language tags with filter and lookup per RFC 4647
• Extension U/T extraction for Unicode locales (RFC 6067) and transformed content (RFC 6497)
• Accept-Language header parsing per RFC 9110
• WCAG-ready — use parse() to validate lang attributes per WCAG 2.x SC 3.1.1 and SC 3.1.2
• TypeScript-first with full type inference and strict types out of the box
• Zero dependencies, tree-shakeable, works in Node.js and browsers

npm install rfc-bcp47

Tree-shakeable operators — import only what you need.

import { parse, stringify } from 'rfc-bcp47';

const tag = parse('en-Latn-US');

if (tag?.type === 'langtag') {
  tag.langtag.language  // 'en'
  tag.langtag.script    // 'Latn'
  tag.langtag.region    // 'US'
}

stringify(tag!);  // 'en-Latn-US'

parse('invalid!');  // null

parse returns one of three tag types or null for invalid input:

Build a tag from known parts without parsing a string. Validates subtags and throws RangeError on invalid input:

import { langtag, stringify } from 'rfc-bcp47';

const tag = langtag('en', { region: 'US' });
stringify(tag);  // 'en-US'

langtag('!!!');  // RangeError — invalid language

Reduce equivalent tags to a single canonical form — handles case normalization, deprecated subtags, suppress-script, extlang promotion, and extension ordering using IANA registry data:

import { canonicalize } from 'rfc-bcp47';

canonicalize('iw');          // 'he'       (deprecated language)
canonicalize('zh-cmn');      // 'cmn'      (extlang to preferred)
canonicalize('en-Latn');     // 'en'       (suppress-script)
canonicalize('de-DD');       // 'de-DE'    (deprecated region)

Find all matching tags with subtag-aware filtering per RFC 4647 §3.3.2:

import { filter } from 'rfc-bcp47';

const tags = ['de', 'de-DE', 'de-Latn-DE', 'de-AT', 'en-US', 'fr-FR'];

filter(tags, 'de-DE');   // ['de-DE', 'de-Latn-DE']  (skips Latn to match DE)
filter(tags, 'de');      // ['de', 'de-DE', 'de-Latn-DE', 'de-AT']  (all German)
filter(tags, '*-DE');    // ['de-DE', 'de-Latn-DE']  (* wildcard = any language)

Find the single best match via progressive truncation per RFC 4647 §3.4:

import { lookup } from 'rfc-bcp47';

const tags = ['en', 'en-US', 'fr', 'de'];

lookup(tags, 'en-US-x-custom');  // 'en-US' (truncates to match)
lookup(tags, 'fr-CA');           // 'fr'    (truncates to match)
lookup(tags, 'ja', 'en');        // 'en'    (default fallback)

Pair with acceptLanguage for HTTP content negotiation:

import { acceptLanguage, lookup } from 'rfc-bcp47';

const prefs = acceptLanguage('fr-CA, en-US;q=0.8, en;q=0.5');
const best = lookup(['en', 'en-US', 'fr', 'fr-CA'], prefs.map((p) => p.tag));
// 'fr-CA'

Extract Unicode locale and transformed content extensions:

import { parse, extensionU, extensionT } from 'rfc-bcp47';

extensionU(parse('de-DE-u-co-phonebk-ca-buddhist')!);
// { attributes: [], keywords: { co: 'phonebk', ca: 'buddhist' } }

extensionT(parse('und-t-it-m0-ungegn')!);
// { source: 'it', fields: { m0: 'ungegn' } }

Parse HTTP Accept-Language headers:

import { acceptLanguage } from 'rfc-bcp47';

acceptLanguage('fr-CA, en-US;q=0.8, en;q=0.5, *;q=0.1');
// [
//   { tag: 'fr-CA', quality: 1.0 },
//   { tag: 'en-US', quality: 0.8 },
//   { tag: 'en',    quality: 0.5 },
//   { tag: '*',     quality: 0.1 }
// ]

Try the interactive demo or see the examples/ folder for more usage patterns.

Typed constants mapping extension keys to human-readable descriptions, sourced from the CLDR BCP 47 data. Zero runtime cost — tree-shaken if unused.

Note: canonicalize and acceptLanguage take strings. extensionU and extensionT take a pre-parsed BCP47Tag from parse(). This avoids re-parsing when you need multiple operations on the same tag.

See CHANGELOG.md for breaking changes and release history.