BCP-47 Locale Identifiers and Fallback

Two jobs that framework tutorials assume you already know: name a locale correctly, and decide which translation to serve when the exact one is missing. The base model knows the form of a language tag but does not default to the right one — it invents subtags (zh-Simplified, en-UK), guesses the script/region axis, and when a translation is missing it grabs any file that shares the language — which can hand a Hong Kong reader Simplified text or show a raw string key. This skill forces well-formed tags and a deterministic fallback.

Tag structure

A tag is language, then an optional Script, then an optional REGION, in that order, joined by hyphens. Casing is conventional (case-insensitive to parsers, but write it the canonical way):

| Subtag | Length / form | Case | Examples | |---|---|---|---| | language | 2–3 letters | lower | zh, sr, pt, en, fr | | Script | exactly 4 letters | Title | Hans, Hant, Latn, Cyrl | | REGION | 2 letters, or 3 digits (UN M.49) | UPPER | CN, HK, BR, GB, 419 |

So zh-Hant-HK = Chinese, Traditional script, Hong Kong region.

Script and region are different axes — do not confuse them. zh-Hans says which writing system (Simplified Han); zh-CN says which country (mainland China, Simplified by convention). Pick the script subtag when the writing system is the thing that differs; pick the region when a country's conventions differ. When both matter, use both (zh-Hant-HK).

Canonical pairs (memorize these)

• Chinese script: zh-Hans (Simplified) vs zh-Hant (Traditional). Regions: zh-CN, zh-SG

are Simplified-writing; zh-TW, zh-HK, zh-MO are Traditional-writing.

• Serbian script: sr-Latn (Latin) vs sr-Cyrl (Cyrillic). Bare sr is ambiguous — mark the

script.

• Portuguese region: pt-BR (Brazil) vs pt-PT (Portugal).
• Latin-American Spanish: es-419 — the region is the M.49 numeric code 419, not a country.
• English: UK is en-GB, not en-UK. US is en-US.

Never invent subtags

Emit only real registered subtags. Wrong, and what it should be:

• zh-Simplified, zh-simplified, zh-CHS → zh-Hans
• zh-Traditional, zh-CHT → zh-Hant
• pt-Brazil → pt-BR · en-UK → en-GB · es-LatinAmerica → es-419
• Do not glue subtags (zh-HantHK); separate them: zh-Hant-HK.

Fallback: which translation to serve

Given a requested locale and the set of locales you actually have, resolve by prefix truncation (the RFC 4647 "lookup" rule):

1. Try an exact match.
2. Drop the right-most subtag and try again. Repeat: zh-Hant-HK → zh-Hant → zh.
3. Take the first available tag in that chain.
4. If the chain runs out (down to the bare language) with no match, serve the ultimate default

(usually en, or whatever your app declares).

Three rules that make this correct rather than naive:

• Fall back by prefix, not by "same language." The danger is grabbing any file that shares

the language. zh-Hant and zh-Hans share the language zh but are mutually unreadable — Traditional and Simplified. Truncation never turns zh-Hant-* into zh-Hans, because zh-Hans is not a prefix of zh-Hant-HK. Do not add sideways matching that would.

• Do not sideways-match regions either. Requested pt-BR with only pt-PT and en available

resolves to en, not pt-PT — pt-PT is not in the chain pt-BR → pt → default.

• Never surface the raw key or tag to the user. If nothing resolves, the user sees a real

string in the default language, never the literal message key or the tag zh-Hant-HK.

Worked chain

Requested zh-Hant-HK; available {zh-Hant, zh-Hans, en}:

zh-Hant-HK   → miss
zh-Hant      → HIT  ✅  serve this

Never zh-Hans (would be Simplified text for a Traditional reader). If instead only {zh-Hans, en} were available, the chain zh-Hant-HK → zh-Hant → zh all miss, so serve en — not zh-Hans.

When to activate

Use when choosing the identifier for a resource file, translation column, or language switcher, or when deciding which existing translation to show a user whose exact locale you don't have.

Do NOT use for: formatting dates/numbers/currency to a locale (that is a formatting skill), plural category selection, or translating the actual prose.

For the extended language → script/region catalog, region-code gotchas, and the full lookup steps, see references/bcp47-catalog.md.