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:
enidentifies English without choosing a region.en-USidentifies English as used in the United States.zh-Hant-TWidentifies Chinese written with Traditional Han script in Taiwan.de-DE-u-co-phonebkidentifies 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
| Component | Example | Purpose | Practical guidance |
|---|---|---|---|
| Language | en, de, zh | Identifies the primary language. | Usually required. Use a valid language subtag rather than a country code. |
| Script | Latn, Hant, Cyrl | Identifies the writing system. | Include it when a language is commonly written in multiple scripts or script affects content selection. |
| Region | US, GB, TW | Identifies a geographic or regional convention. | Use it for spelling, dates, currency, measurement, or regional content differences. |
| Variant | fonipa | Describes a registered variation of language use. | Use registered variants only, and avoid adding one merely to encode an application state. |
| Unicode extension | u-ca-gregory | Requests locale-sensitive behavior such as calendar, numbering, hour cycle, or collation. | Place the u extension after language, script, region, and variants. |
| Private use | x-example | Carries 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-japaneserequests a Japanese calendar.u-nu-arabrequests an Arabic numbering system where supported.u-hc-h23requests a particular hour-cycle preference.u-co-phonebkrequests 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-TWis reduced to a base language: check whether the translation catalog and fallback table preserve the script and region. Do not assume thatzhalone 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 ascalendarornumberingSystem, 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:
- List every locale accepted from the browser, URL, account profile, or API.
- Canonicalize the list and reject structurally invalid values before they reach formatting or translation code.
- Record the supported translation locales and define explicit fallbacks.
- Test representative tags such as
en-US,zh-Hant-TW, and one tag with auextension. - Inspect
Intl.Localefields and formatterresolvedOptions()rather than inferring behavior from the input string. - 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.