OnlineDocTranslatorGuides

Running your practice

Localization Codes: The Standards Translators and Agencies Use

Localization codes are ISO 639 language, ISO 3166 country, ISO 15924 script, and BCP 47 locale tags that identify what to translate for which locale.

Every localized asset — a resource bundle, a URL, an XLIFF segment, a Webflow page — carries an identifier that binds it to one locale. Localization codes are that identifier layer. They sit beneath translation work as part of How App Localization Works and What Clients Are Buying and every other multi-locale engagement, and most translator rework traces back to a mistagged code rather than a mistranslated word.

What are localization codes and which standards define them?

Localization codes are standardized identifiers that name a target locale for translation tooling. They combine ISO 639 language subtags, ISO 15924 script subtags, and ISO 3166-1 region subtags under the BCP 47 composition rules maintained by IETF.

Four standards do the work:

  • ISO 639 — language identity, in three parts (639-1 2-letter, 639-2 3-letter, 639-3 3-letter extended).
  • ISO 15924 — 4-letter script subtags (Latn, Hant, Hans, Cyrl, Arab).
  • ISO 3166-1 — 2-letter country codes used as BCP 47 region subtags (US, BR, MX, DE).
  • BCP 47 — the IETF rule set that assembles the three above into a single locale tag.
  • UN M.49 — numeric region codes (419 Latin America, 150 Europe, 005 South America) accepted by BCP 47 as region subtags.

How does the 4-layer code stack (language, script, region, extension) fit together?

A BCP 47 locale tag stacks four layers: language, script, region, and private or variant extensions. Translators read the stack left-to-right to know what to translate, in which script, for which market.

LayerStandardExample subtagWhat breaks if dropped
LanguageISO 639-1 / 639-2 / 639-3zh, en, yueNo translation target at all
ScriptISO 15924Hant, Hans, Cyrl, LatnChinese and Serbian ship in the wrong writing system
RegionISO 3166-1 or UN M.49TW, BR, 419Vocabulary, pricing, and reviewer pool get wrong assignment
Variant / extensionBCP 47 extension (u-, x-)u-ca-gregory, x-corpCalendar, collation, and private tags fail silently

Dropping the script subtag is the breakage that costs the most hours. A tag of zh with no Hans or Hant forces the engine to guess, and the guess routes Mainland copy into a Hong Kong reviewer queue.

Who maintains localization code standards and how often do they change?

ISO maintains 639, 3166, and 15924; the Library of Congress serves as the ISO 639-2 registration authority; IETF maintains BCP 47 through the IANA Language Subtag Registry. Updates publish on separate cadences, which is why translators pin a snapshot per project.

  • ISO 639-3 adds and retires codes annually through SIL International.
  • ISO 3166-1 changes when a country, territory, or alpha-2 assignment changes.
  • The IANA Language Subtag Registry is the authoritative source consolidating all three ISO lists for BCP 47.
  • Freeze a registry snapshot at project kickoff and ship it with the TM. Mid-sprint drift breaks acceptance tests.

What is the difference between ISO 639-1, ISO 639-2, and ISO 639-3?

ISO 639-1 is 2-letter (en, de, fr), ISO 639-2 is 3-letter with bibliographic and terminologic variants (fre/fra, ger/deu), and ISO 639-3 is 3-letter codes covering roughly 7,900 individual languages including minority and constructed languages.

PartFormatScopeTypical use
ISO 639-12-letter~184 mainstream languagesWeb, CAT tools, hreflang, BCP 47
ISO 639-23-letter, /B and /T~500 languagesBibliographic archives, MARC records
ISO 639-33-letter~7,900 individual languagesMinority and constructed languages, SIL cataloging

When does a translator use 2-letter versus 3-letter codes?

Use ISO 639-1 2-letter codes for mainstream i18n (web, CAT tools, hreflang, BCP 47). Use ISO 639-2 or 639-3 3-letter codes for archival systems, bibliographic metadata, and any language without a 2-letter code — Cherokee (chr), Cornish (cor, kw), or Esperanto variants.

  • Web, mobile, and CAT tooling: 2-letter.
  • Library and bibliographic systems: 3-letter /B.
  • Linguistic research, long-tail minority locales: ISO 639-3.
  • Cantonese and other spoken varieties with no 2-letter code: ISO 639-3 (yue) or BCP 47 extended (zh-yue).

What is the bibliographic vs terminologic split in ISO 639-2 (fre vs fra)?

ISO 639-2/B is bibliographic, chosen from English-language names (fre French, ger German). ISO 639-2/T is terminologic, chosen from the native name (fra, deu). Translators pick /T for linguistic tooling and /B only when the client's archive demands it.

The pairs that most often collide in client exports:

  • French — fre (/B) vs fra (/T)
  • German — ger (/B) vs deu (/T)
  • Dutch — dut (/B) vs nld (/T)
  • Greek — gre (/B) vs ell (/T)
  • Chinese — chi (/B) vs zho (/T)
  • Icelandic — ice (/B) vs isl (/T)

How do you normalize both 2-letter and 3-letter codes in one system?

Maintain a lookup table that maps every ISO 639-1 code to its ISO 639-2/T and ISO 639-3 equivalents, and canonicalize to one form at ingest. The IANA Language Subtag Registry is the authoritative source; freezing a snapshot per project prevents mid-sprint drift.

LanguageISO 639-1ISO 639-2/BISO 639-2/TISO 639-3
Englishenengengeng
Spanishesspaspaspa
Frenchfrfrefrafra
Germandegerdeudeu
Portugueseptporporpor
Italianititaitaita
Dutchnldutnldnld
Russianrurusrusrus
Polishplpolpolpol
Ukrainianukukrukrukr
Czechcsczecesces
Greekelgreellell
Turkishtrturturtur
Arabicararaaraara
Hebrewhehebhebheb
Persianfaperfasfas
Hindihihinhinhin
Urduururdurdurd
Bengalibnbenbenben
Tamiltatamtamtam
Thaiththathatha
Vietnamesevivievievie
Indonesianidindindind
Malaymsmaymsamsa
Filipinofilfilfilfil
Japanesejajpnjpnjpn
Koreankokorkorkor
Chinesezhchizhozho
Cantonese———yue
Swedishsvswesweswe
Norwegian Bokmålnbnobnobnob
Norwegian Nynorsknnnnonnonno
Danishdadandandan
Finnishfifinfinfin
Icelandicisiceislisl
Hungarianhuhunhunhun
Romanianrorumronron
Serbiansrsrpsrpsrp
Croatianhrhrvhrvhrv
Slovaksksloslkslk
Swahiliswswaswaswa

How does BCP 47 compose a full locale identifier from these codes?

BCP 47 assembles a locale as language-Script-REGION-variant-extension, with hyphens, specific case rules, and a prescribed order (zh-Hant-TW, sr-Latn-RS, en-Latn-US-u-ca-gregory). Translators who alter case or punctuation break locale resolution.

The assembly steps:

  1. Pick the primary language subtag from ISO 639-1 when it exists; fall back to ISO 639-2/T or 639-3.
  2. Add an ISO 15924 script subtag when the language can appear in more than one script.
  3. Add an ISO 3166-1 alpha-2 or UN M.49 numeric region subtag when the market matters.
  4. Append variant and extension subtags last, under the u- (Unicode) or x- (private) prefix.
  5. Join all subtags with single hyphens — no underscores, no spaces.

What are the case conventions for language, script, and region subtags?

Language subtags are lowercase (en, zh), script subtags are Title Case (Latn, Hant, Cyrl), and region subtags are UPPERCASE (US, TW, BR). BCP 47 parsers are case-insensitive, but filenames and build configs are not.

  • Correct: en-Latn-US, zh-Hant-TW, sr-Cyrl-RS.
  • Parses but risks filename mismatch: EN-LATN-US, zh-hant-tw.
  • Fails most i18n configs: en_US, es_mx (underscores belong to POSIX/Android, not BCP 47 JSON keys).

Why do locale filenames have to byte-match the BCP 47 tag?

A file named es-mx.json will not load against an i18n config expecting es-MX; the string compares byte-for-byte including hyphen case. Underscore conventions (en_US) belong to POSIX and Android resource folders — never to BCP 47 JSON keys. The deeper mechanics live on JS Localization: How Translators Fit Into a JavaScript i18n Pipeline and React i18n: How Translators Fit Into a React Localization Pipeline.

The three byte-match failures that cost translators handback cycles:

  1. Lowercase region in the filename against uppercase region in the config (es-mx.json vs es-MX).
  2. Underscore in a filename intended for a hyphenated BCP 47 key (en_US.json vs en-US).
  3. Missing script subtag when the engine was configured for the scripted form (zh.json vs zh-Hans).

What is a region subtag and how is it different from an ISO 3166 country code?

A BCP 47 region subtag can be either an ISO 3166-1 alpha-2 country code (US, BR, DE) or a UN M.49 numeric region code (419 for Latin America, 150 for Europe). Region subtags target markets, not countries — es-419 covers all Latin American Spanish.

Which localization codes appear in the files a translator actually opens?

Translators meet locale codes in resource-bundle filenames (en-US.json, fr-CA.po), hreflang attributes in HTML, Intl.Locale strings in JavaScript, Android values-xx-rYY folders, iOS .lproj directories, and XLIFF file target-language headers. The resource bundle and i18n-split details sit on Website Localization: What Translators and Agencies Actually Do on the Project.

SurfaceCode formatExampleNotes
Web hreflangBCP 47 hyphenes-MX, pt-BRSelf-reference required
JS Intl.LocaleBCP 47 full stacken-Latn-USByte-match filenames
iOS .lprojBCP 47 hyphenes-MX.lproj, zh-Hant.lprojDirectory name = tag
Android values-language + r+regionvalues-es-rMXHyphen replaced by "r" prefix
XLIFF 2.xBCP 47 in attributestarget-language="pt-BR"Validated by XLIFF toolchains
Expo LocalizationlanguageTag + regionCodeen-US + USAlso returns measurementSystem and currencyCode
POSIX / gettextunderscorees_MX.poNot BCP 47 — do not mix

How do codes differ between web (hreflang), iOS (.lproj), Android (values-), and XLIFF?

Web uses BCP 47 with hyphens (es-MX); iOS .lproj follows BCP 47 too (es-MX.lproj, zh-Hant.lproj); Android uses hyphen-less language with r+region (values-es-rMX); XLIFF 2.x requires BCP 47 in source-language and target-language attributes.

Four conversion rules keep handbacks clean:

  • Web → iOS: identical tag, append .lproj.
  • Web → Android: split es-MX into values-es-rMX.
  • Web → POSIX: replace hyphen with underscore (es_MX), add .UTF-8 if required.
  • XLIFF → Web: copy the target-language attribute verbatim.

What does an hreflang pair look like with correct ISO 639-1 and ISO 3166-1 codes?

Each page references all its alternates — including itself — using ISO 639-1 language codes plus optional ISO 3166-1 country codes, written as hreflang="es-MX", hreflang="pt-BR", hreflang="fr-CA". A missing self-reference drops the whole cluster. The ranking consequences live on Localization SEO: How Translators Make Localized Pages Rank, and the CMS-side configuration sits on How Webflow Localization Works and What Translators Need to Know.

Which localization codes trip up real projects the most?

Five locale pairs cause most rework: Serbian Latin vs Cyrillic (sr-Latn vs sr-Cyrl), Chinese Traditional vs Simplified (zh-Hant vs zh-Hans), Norwegian Bokmål vs Nynorsk (nb/nn/no), Cantonese (yue/zh-yue), and Filipino vs Tagalog (fil/tl). Each triggers LQA rework at $40–$90 per 1,000 words on top of the base $0.10–$0.25 per word rate.

How are regional variants of Spanish, Portuguese, and French encoded?

Spanish variants ship as es-ES (Castilian), es-MX (Mexican), es-AR, es-CO, or the regional macro es-419 for Latin America. Portuguese splits pt-BR and pt-PT; French splits fr-FR, fr-CA, fr-BE, fr-CH. Each is a separate deliverable with its own TM, reviewer pool, and price, as covered on Localization in Marketing: What Translators and Agencies Deliver.

How is Chinese encoded across script and region (zh-Hant-TW, zh-Hans-CN, zh-HK)?

Chinese requires a script subtag because the language alone is ambiguous. Use zh-Hans-CN for Simplified Mainland, zh-Hant-TW for Traditional Taiwan, and zh-Hant-HK for Traditional Hong Kong — the latter two share a script but diverge in vocabulary.

Why is Cantonese hard to represent in standard code systems?

Cantonese has an ISO 639-3 code (yue) and a BCP 47 extended tag (zh-yue), but many legacy systems only accept zh with no spoken-variant subtag. Agencies submit yue, fall back to zh-Hant-HK by convention, or document the mismatch in the handoff.

Which other common codes get mis-tagged (nb vs no, fil vs tl, iw vs he, in vs id)?

Norwegian Bokmål is nb; the macrolanguage no is deprecated for new projects. Filipino is fil, not tl. Hebrew is he (iw is a legacy Java code). Indonesian is id (in is a legacy Java code). Yiddish is yi (ji is legacy). Modern builds reject legacy tags silently.

Legacy tagReplacementLanguage
iwheHebrew
inidIndonesian
jiyiYiddish
nonb or nnNorwegian
tlfilFilipino

How should localization codes appear in URLs for multilingual SEO?

The standard pattern is www.example.com/{lang-code}/page, using subdirectories like /en/, /es-MX/, /pt-BR/. Each URL emits an hreflang pair matching its directory, with ISO 639-1 language codes and optional ISO 3166-1 country codes.

When should URLs use /en/ versus /en-US/?

Use /en/ when a single English edition serves every market and /en-US/ only when a separate en-GB or en-AU edition exists on the same site. Adding a region subtag you cannot staff with distinct content fragments ranking signals.

Subdirectory, subdomain, or query parameter — which structure holds hreflang signals best?

Subdirectories (/es-MX/) are easiest for crawlers and simplest for translators to QA. Subdomains (es.example.com) require separate crawl budgets. Query parameters (?lang=es-MX) are discouraged because many crawlers treat them as duplicates.

StructureExampleCrawl costQA load
Subdirectoryexample.com/es-MX/LowLow
Subdomaines-mx.example.comMediumMedium
Country TLDexample.mxHighHigh
Query parameterexample.com/?lang=es-MXHigh (duplicates risk)High

How does a translator deliver endonyms instead of English language names?

Build a code-to-endonym lookup (en → English, de → Deutsch, ja → 日本語, ru → Русский, zh-Hans → 简体中文) because engines like Godot, older Xcode projects, and legacy Android ship English language names only. Deliver it as a CSV or JSON keyed by BCP 47 tag.

BCP 47 tagEnglish exonymNative endonym
enEnglishEnglish
deGermanDeutsch
esSpanishEspañol
frFrenchFrançais
itItalianItaliano
jaJapanese日本語
koKorean한국어
ruRussianРусский
zh-HansChinese (Simplified)简体中文
zh-HantChinese (Traditional)繁體中文
arArabicالعربية
heHebrewעברית

How should an agency prioritize which localization codes to ship first?

Score candidate locales on ISO 639-3 code availability, in-market speaker count, ISO 3166-1 region reach, client revenue coverage, and TM leverage. A mid-size 5-language, 50,000-word program budgets $25,000–$75,000 — code triage decides which five.

A defensible scoring sheet weights:

  1. Code availability — does ISO 639-3 cover the language with a stable tag? (0 or 10)
  2. Speaker count in the target region (0–20).
  3. Region reach — single country or macro region like es-419 (0–10).
  4. Client revenue share tied to that locale (0–30).
  5. TM leverage from prior projects (0–20).
  6. Reviewer pool depth — enough qualified reviewers to run LQA (0–10).

What does a localization-code QA checklist look like at handback?

Verify seven items before handback: BCP 47 tag spelling, filename byte-match, script subtag present where ambiguous, hreflang self-reference, region subtag matches reviewer pool, no deprecated tags (iw, in, no, ji), and endonym map delivered if the engine needs it.

  1. Spell every BCP 47 tag against the frozen IANA Language Subtag Registry snapshot.
  2. Compare each filename byte-for-byte against the config key — hyphen case included.
  3. Confirm a script subtag on every Chinese, Serbian, and Uzbek deliverable.
  4. Audit hreflang blocks for the self-reference line and matching reciprocal pairs.
  5. Match region subtags to the reviewer pool contracted for that market.
  6. Replace any legacy tag (iw, in, ji, no) with its modern replacement.
  7. Attach the endonym CSV when the client's engine ships English-only language names.

Translators and agency PMs most often ask about mixing 2-letter and 3-letter codes, representing dialects, choosing codes vs full names in UI, and why Cantonese and some minority languages remain hard to tag.

Frequently asked questions

What's the difference between ISO 639-1, ISO 639-2, and ISO 639-3?

ISO 639-1 uses 2-letter codes (e.g., 'fr' for French), ISO 639-2 uses 3-letter codes covering ~490 languages, and ISO 639-3 expands to 3-letter codes for over 7,000 living, extinct, and constructed languages. ISO 639-1 is the most widely used in web and software localization (BCP 47 tags, HTTP headers, HTML lang attributes). ISO 639-2 is common in library cataloguing and some government standards. ISO 639-3, maintained by SIL International, is the go-to for linguistic research and for languages that lack an ISO 639-1 code — essential when certifying translations for less-resourced languages.

How do I support both 2-letter (ISO 639-1) and 3-letter (ISO 639-2) language codes in the same system?

The standard approach is to store codes internally in one canonical format — typically ISO 639-1 where available — and maintain a lookup table that maps 3-letter ISO 639-2/639-3 codes to their 2-letter equivalents. SIL's public ISO 639-3 tables include a column explicitly linking each 3-letter code to its ISO 639-1 counterpart when one exists. For languages with no ISO 639-1 code (e.g., 'haw' for Hawaiian), fall back to the 3-letter form. This hybrid approach is used by major localization platforms and keeps BCP 47 language tags valid across both translation management systems and certified document metadata.

How do I represent Spanish dialects or regional variants in ISO 639-3?

ISO 639-3 treats Spanish as a single macro-language ('spa'), so regional variants are represented using BCP 47 language tags that combine the ISO 639-1 code with an ISO 3166-1 region subtag — for example, 'es-MX' for Mexican Spanish or 'es-419' for Latin American Spanish broadly. ISO 639-3 does not assign separate codes to dialect-level variants of major world languages like Spanish. For certified translation workflows, the region subtag is the practical mechanism agencies use to specify target locale, since a certificate for 'es-MX' and 'es-ES' may carry different legal standing depending on the target jurisdiction.

What are region subtags and how are they different from country codes in language tags?

Region subtags in BCP 47 language tags are drawn from ISO 3166-1 alpha-2 country codes (e.g., 'US', 'BR') or UN M.49 numeric codes (e.g., '419' for Latin America), and they specify the regional variety of a language rather than identifying a country per se. The distinction matters because a region subtag describes linguistic conventions — spelling, date formats, legal terminology — not citizenship or geography. For example, 'fr-CA' signals Canadian French conventions (distinct vocabulary, some legal terms) versus 'fr-FR'. In certified translation production, using the correct region subtag ensures the right locale-specific glossaries, style guides, and legal terminology are applied.

Why is Cantonese hard to represent in standard language code systems?

Cantonese lacks its own ISO 639-1 code and sits under the Chinese macro-language umbrella in many systems, making unambiguous tagging difficult. ISO 639-3 does assign it the code 'yue', which is the most precise identifier available. In BCP 47, Cantonese is best tagged as 'zh-yue' or simply 'yue', but many platforms still collapse it under 'zh' (Chinese), causing it to be treated as interchangeable with Mandarin. For certified translation agencies handling Hong Kong or Macau documents, this ambiguity is significant — a document certified in Cantonese written form (Traditional script, 'zh-Hant-HK') is legally distinct from Simplified Chinese Mandarin.

Should I use language codes (EN/DE/ES) or full language names in my UI/localization files?

Use language codes (BCP 47 tags like 'en', 'de', 'es-MX') internally in localization files and configuration, and display full language names — ideally endonyms — to end users. Codes are machine-readable, collision-free, and standard across translation management systems, CAT tools, and certified document metadata. Full names are human-readable but ambiguous (is 'Chinese' Simplified or Traditional? Mandarin or Cantonese?). The industry best practice is to store the BCP 47 tag as the canonical key and derive the display name from it programmatically, using a library like ICU or the Unicode CLDR data set.

What are language codes?

Language codes are standardized short identifiers assigned to human languages so that software, databases, and documents can reference a language unambiguously. The most widely used standards are ISO 639-1 (2-letter, e.g., 'en' for English), ISO 639-3 (3-letter, covering 7,000+ languages), and BCP 47 tags that combine a language code with optional script and region subtags (e.g., 'zh-Hant-TW'). In certified translation workflows, language codes appear in document metadata, translation memory systems, CAT tool project settings, and on certificates of accuracy to identify the source and target languages precisely.

What is an example of localization?

A clear example of localization is adapting a certified immigration document translation not just linguistically but also for the conventions of the target country — converting dates from MM/DD/YYYY to DD/MM/YYYY, replacing US state abbreviations with the target country's administrative divisions, and adjusting legal terminology to match the receiving jurisdiction's official usage. Localization goes beyond word-for-word translation to ensure the document is functionally and legally appropriate in its destination context. For translation agencies, this distinction between translation and localization directly affects which style guides, glossaries, and region subtags (e.g., 'pt-BR' vs. 'pt-PT') are applied to a project.

Can I certify my own translation?

In most jurisdictions, you cannot certify your own translation if you are the person who needs the document — but a bilingual individual who is not the document's subject can self-certify in some countries, including the United States. In the US, USCIS accepts a signed statement from the translator attesting to their competence and the accuracy of the translation, with no requirement for a notary or third-party credential. However, countries like Germany, France, and many others require a sworn or court-certified translator (Beeidigter Übersetzer). Agencies producing certified translations should verify the destination jurisdiction's requirements before issuing any certificate.

Related