BCP 47 Language Tags and Unicode Locale Extensions: A Practical Web Developer Guide
UnicodeBCP 47JavaScriptInternationalizationLocalizationWeb APIs

BCP 47 Language Tags and Unicode Locale Extensions: A Practical Web Developer Guide

UUnicode Live Editorial Team
2026-11-19
7 min read

Learn to construct, validate, negotiate, and maintain BCP 47 tags such as en-US, zh-Hant-TW, and Unicode locale extensions in JavaScript.

BCP 47 language tags are the compact identifiers behind multilingual web interfaces, HTTP language preferences, translation catalogs, and JavaScript internationalization APIs. This guide explains how to construct tags such as en-US, zh-Hant-TW, and de-DE-u-co-phonebk, how to inspect them with Intl.Locale, and what to check when locale data or browser behavior changes.

Overview

A language tag describes a language and, when useful, the script, region, variant, or formatting preferences associated with it. BCP 47 tags are conventionally written with hyphens and are case-insensitive for matching, although canonical casing makes them easier to read: language subtags usually use lowercase, script subtags use title case, and region subtags use uppercase.

For example:

  • en identifies English without choosing a region.
  • en-US identifies English as used in the United States.
  • zh-Hant-TW identifies Chinese written with Traditional Han script in Taiwan.
  • de-DE-u-co-phonebk identifies German for Germany with a Unicode locale extension requesting phonebook-style collation where that preference is supported.

A tag is not the same thing as a translation file name, a country code, or a guarantee that a browser has matching resources. It is an input to locale selection and formatting. The runtime, its ICU data, and the application determine what can actually be displayed or formatted.

The broad structure is:

language[-script][-region][-variant...][-extension...][-privateuse]

Not every tag needs every component. Start with the least specific value that correctly describes the content or user preference. Add a script when two writing systems matter, a region when regional conventions matter, and an extension when a formatting or collation preference is part of the requirement.

What to track

Subtag types and their purpose

ComponentExamplePurposePractical guidance
Languageen, de, zhIdentifies the primary language.Usually required. Use a valid language subtag rather than a country code.
ScriptLatn, Hant, CyrlIdentifies the writing system.Include it when a language is commonly written in multiple scripts or script affects content selection.
RegionUS, GB, TWIdentifies a geographic or regional convention.Use it for spelling, dates, currency, measurement, or regional content differences.
VariantfonipaDescribes a registered variation of language use.Use registered variants only, and avoid adding one merely to encode an application state.
Unicode extensionu-ca-gregoryRequests locale-sensitive behavior such as calendar, numbering, hour cycle, or collation.Place the u extension after language, script, region, and variants.
Private usex-exampleCarries private, non-interoperable information.Do not use it when a registered language or Unicode extension can express the requirement.

Unicode locale extensions

The Unicode u extension is especially useful with JavaScript internationalization. Common examples include:

  • u-ca-japanese requests a Japanese calendar.
  • u-nu-arab requests an Arabic numbering system where supported.
  • u-hc-h23 requests a particular hour-cycle preference.
  • u-co-phonebk requests a collation preference.

These are preferences, not promises. A formatter may resolve a different value if the requested option is unavailable or if an explicit constructor option takes precedence. For user-facing formatting, inspect the resolved options rather than assuming that the tag was honored.

Parse and canonicalize tags in JavaScript

Intl.Locale provides a structured view of a language tag. The following example separates parsing from validation and shows useful locale operations:

const locale = new Intl.Locale('zh-Hant-TW-u-nu-hanidec');

console.log(locale.language); // 'zh'
console.log(locale.script);   // 'Hant'
console.log(locale.region);   // 'TW'
console.log(locale.baseName); // 'zh-Hant-TW'
console.log(locale.toString());

console.log(locale.calendar);
console.log(locale.numberingSystem);
console.log(locale.maximize().toString());
console.log(locale.minimize().toString());

The constructor rejects structurally malformed tags, while Intl.getCanonicalLocales() is useful when you want canonicalized output and duplicate removal:

const canonical = Intl.getCanonicalLocales(['EN-us', 'zh-hant-tw']);
console.log(canonical); // ['en-US', 'zh-Hant-TW']

Keep this distinction clear: syntactic validity means a tag has an acceptable structure; support means your application, browser, translation catalog, or server has useful data for that tag. A valid tag can still be unsupported by a particular resource set.

Negotiate supported locales

When a browser or user supplies a list of preferences, do not select the first string by simple equality. Use the negotiation behavior provided by the relevant Intl API, and keep a deliberate application fallback:

const requested = ['fr-CA', 'fr-FR', 'en-US'];
const supported = ['en-US', 'fr-FR'];

const match = Intl.DateTimeFormat.supportedLocalesOf(
  requested,
  { localeMatcher: 'best fit' }
);

const active = match[0] ?? 'en-US';
const formatter = new Intl.DateTimeFormat(active, {
  dateStyle: 'medium'
});

For translation catalogs, maintain your own mapping of supported tags and decide whether a regional request may fall back to its base language. For example, an application may map fr-CA to fr-FR, but that is a product decision rather than a universal BCP 47 rule.

Cadence and checkpoints

Review locale behavior on a monthly or quarterly engineering cadence, and again whenever an internationalization dependency changes. The goal is not to rewrite every tag regularly; it is to detect changes in the data and assumptions surrounding those tags.

  • At each scheduled review: test the locale list used by the application, check that translation resources still map to the intended tags, and run representative date, number, time, and collation cases.
  • When browser or runtime versions change: rerun tests for Intl.Locale, Intl.DateTimeFormat, Intl.NumberFormat, Intl.Collator, and any APIs that consume locale lists.
  • When adding a language: confirm the language, script, and region choices with the localization team, then test fallback behavior for less-specific and more-specific requests.
  • When adding an extension: verify the relevant Unicode locale key and value, then inspect resolvedOptions() in the runtimes you support.
  • When translation assets change: check for casing differences, underscores in place of hyphens, deprecated aliases, accidental private-use subtags, and tags that are more specific than the available content.

Keep a small test matrix rather than testing every possible locale. Include a language with a script distinction, a language with regional variation, a right-to-left case if your product supports it, and the calendar or numbering preferences your interface actually exposes.

How to interpret changes

If a tag stops producing the expected result, first identify which layer changed. The tag may be malformed, the locale may be valid but unsupported, the runtime's locale data may differ, or an explicit formatter option may override the extension.

Common diagnostic patterns

  • zh-Hant-TW is reduced to a base language: check whether the translation catalog and fallback table preserve the script and region. Do not assume that zh alone selects Traditional Chinese.
  • A Unicode extension appears to be ignored: create the formatter with the tag, then inspect resolvedOptions(). Also check whether an explicit option, such as calendar or numberingSystem, was supplied.
  • Two equivalent-looking tags behave differently: canonicalize them and compare baseName, extensions, and resolved formatter options. Underscores, incorrect casing, and copied locale identifiers from unrelated systems are frequent sources of confusion.
  • A tag is valid but has no translation: treat validation and resource availability as separate checks. Select a documented fallback rather than silently assuming that every parent locale is interchangeable.
  • Sorting differs across environments: locale collation is data-dependent. Test the actual supported browsers or server runtimes, and document whether sorting is for display, search, or a stable technical key.

Use locale tags for presentation and language negotiation, not as a replacement for stable identifiers. Store canonical application IDs separately from user-facing locale preferences. This prevents a formatting preference such as a calendar or collation choice from accidentally changing database keys, URLs, or authorization logic.

For related Unicode behavior, see the guides to JavaScript Intl.Collator, Unicode-aware search and slug generation, and Unicode normalization. Locale selection, collation, normalization, and text rendering solve different problems and should be tested separately.

When to revisit

Revisit this guide whenever you add a language, introduce a new script, change locale negotiation, expose calendar or numbering preferences, or upgrade a browser, JavaScript runtime, ICU-backed library, or localization package. A quarterly review is a practical baseline for active multilingual products; a monthly check is appropriate when locale data or supported runtimes change frequently.

Use this short action list at each review:

  1. List every locale accepted from the browser, URL, account profile, or API.
  2. Canonicalize the list and reject structurally invalid values before they reach formatting or translation code.
  3. Record the supported translation locales and define explicit fallbacks.
  4. Test representative tags such as en-US, zh-Hant-TW, and one tag with a u extension.
  5. Inspect Intl.Locale fields and formatter resolvedOptions() rather than inferring behavior from the input string.
  6. Update the test matrix when IANA language-subtag data, CLDR-derived runtime data, Unicode extension keys, or browser support changes.

BCP 47 tags are most reliable when they remain precise but minimal. Choose the language first, add script or region only when they affect content or presentation, use Unicode extensions for explicit formatting preferences, and keep support and fallback decisions visible in application code. That workflow makes locale behavior easier to debug and easier to revisit as the web platform evolves.

Related Topics

#Unicode#BCP 47#JavaScript#Internationalization#Localization#Web APIs
U

Unicode Live Editorial Team

Technical Editor

Senior editor and content strategist. Writing about technology, design, and the future of digital media. Follow along for deep dives into the industry's moving parts.