Chrome extension locale codes: all 55

Rule 1: underscores, not hyphens

BCP‑47 — the standard behind Accept-Language headers, HTML lang attributes, Intl locales, i18next, Rails, iOS and virtually every translation platform — writes language-region tags with a hyphen: pt-BR, zh-CN, en-US.

Chrome extension _locales folder names use an underscore: pt_BR, zh_CN, en_US. The language subtag is lowercase and the region subtag is uppercase, exactly as spelled in the table below.

Wrong — BCP‑47 hyphens. These four folders are dead weight in the ZIP:

_locales/
├── en/
│   └── messages.json
├── pt-BR/          ← ignored
│   └── messages.json
├── zh-CN/          ← ignored
│   └── messages.json
├── es-419/         ← ignored
│   └── messages.json
└── en-GB/          ← ignored
    └── messages.json

Right — underscores, uppercase region:

_locales/
├── en/
│   └── messages.json
├── pt_BR/
│   └── messages.json
├── zh_CN/
│   └── messages.json
├── es_419/
│   └── messages.json
└── en_GB/
    └── messages.json

Casing matters too. Chrome matches the folder name against its list literally:

Why this bites in CI, not on your laptop

Almost nothing upstream of your build emits underscores. Translation platforms export pt-BR.json. Your i18n library’s locale directory is named zh-CN. Your CI script copies the directory tree as-is into dist/. So a rename step is usually required, and it belongs in the build — not in a manual checklist someone forgets before a release:

# Rename BCP-47 directories to Chrome _locales names
for dir in dist/_locales/*-*/; do
  name=$(basename "$dir")
  # pt-BR -> pt_BR, zh-CN -> zh_CN, es-419 -> es_419
  mv "$dir" "dist/_locales/${name//-/_}"
done

That naive rename handles the common cases because Chrome’s region subtags are already uppercase in BCP‑47 form. It does not fix zh-Hans or pt, which have no direct Chrome equivalent — see the mapping notes below the table. The only reliable check is to compare your output folder names against the supported list and fail the build on a mismatch.

All 55 supported _locales codes

Every code below is valid as a folder name under _locales/ and as a value for default_locale in manifest.json. The last column marks the 52 locales LocalePack translates into.

55 codes total. LocalePack ships 52 of them; the 3 it does not are the English regional variants, which are a copywriting decision rather than a translation job — see below.

Notes on the list

• •There is no bare zh and no bare pt. Chinese exists only as zh_CN and zh_TW; Portuguese only as pt_BR and pt_PT. If your source files are named zh or pt, you must decide which variant they represent before shipping.
• •es_419 uses a numeric UN M.49 region code, not a country code. 419 is Latin America. It sits alongside es, which in practice serves European Spanish.
• •fil (Filipino) is a three-letter code. It is not tl, and tl is not on the list.
• •no is the only Norwegian code. Neither nb nor nn appears.
• •ar, fa and he are right-to-left. Shipping the catalog is the easy half; your popup and options page need RTL layout handling to match.
• •Several widely requested languages are simply absent — among them Urdu, Punjabi, Icelandic, Macedonian, Georgian, Armenian, Azerbaijani, Nepali, Sinhala, Khmer, Burmese and Lao. There is no way to add them: an unlisted folder name is ignored.

Copy-paste list of all 55 codes

Grab this for a build script, a validation config, or a spreadsheet:

ar am bg bn ca
cs da de el en
en_AU en_GB en_US es es_419
et fa fi fil fr
gu he hi hr hu
id it ja kn ko
lt lv ml mr ms
nl no pl pt_BR pt_PT
ro ru sk sl sr
sv sw ta te th
tr uk vi zh_CN zh_TW

As a shell array, so you can scaffold folders or validate an existing tree:

CHROME_LOCALES=(
  ar am bg bn ca
  cs da de el en
  en_AU en_GB en_US es es_419
  et fa fi fil fr
  gu he hi hr hu
  id it ja kn ko
  lt lv ml mr ms
  nl no pl pt_BR pt_PT
  ro ru sk sl sr
  sv sw ta te th
  tr uk vi zh_CN zh_TW
)

# Scaffold every folder you intend to ship
for code in "${CHROME_LOCALES[@]}"; do
  mkdir -p "_locales/$code"
done

# Or: fail the build if any existing folder is not on the list
for dir in _locales/*/; do
  code=$(basename "$dir")
  case " ${CHROME_LOCALES[*]} " in
    *" $code "*) ;;
    *) echo "Unsupported locale folder: $code" && exit 1 ;;
  esac
done

How Chrome picks a locale at runtime

The locale Chrome resolves for your extension follows the browser’s UI language, not the language of the page the user is looking at and not the operating system on its own. You can read the value your extension is running under:

// Synchronous, returns a string like "en-US" or "pt-BR"
const uiLanguage = chrome.i18n.getUILanguage();

// Asynchronous, returns the user's accept-languages list
const accepted = await chrome.i18n.getAcceptLanguages();

From there, Chrome selects a catalog by narrowing from the most specific match toward your default_locale. The practical model:

Browser UI language: pt-BR

  1. _locales/pt_BR/messages.json   ← exact match, if you shipped it
  2. _locales/pt/…                  ← base language — but "pt" is not a
                                       supported Chrome code, so for
                                       Portuguese this step cannot exist
  3. _locales/en/messages.json      ← default_locale, always the last resort

Result: getMessage() always returns a string, never throws.

Rather than lean on the exact intermediate steps, design so the outcome is the same either way. Two rules make the fallback question moot:

• •Ship the base language alongside any regional variant. If you ship en_GB, also ship en. A user in Canada or Ireland then lands on real English regardless of how the narrowing works, instead of possibly dropping all the way through to default_locale. The same applies to es next to es_419.
• •Keep default_locale complete. It is the floor of the chain and the one catalog that must contain every key. See default_locale rules and errors.
• •Fallback works per key, not per file. A key present in pt_BR with an empty message value returns an empty string — it does not fall back. Omit untranslated keys instead of shipping empty ones.

The English variants: en, en_AU, en_GB, en_US

English is the only language on the list with regional variants that are not about translation at all — nobody is translating English into English. They exist for spelling and vocabulary: colour vs color, organise vs organize, autumn vs fall, and formatting conventions your copy might hard code.

When en alone is enough

• •Your UI is short — buttons, labels, a handful of tooltips. The spelling delta across variants is usually zero or one word.
• •You have no dedicated copywriter. Three near-identical catalogs that drift apart are worse than one that is right.
• •You are optimising for effort. Every extra variant is another file to keep in sync on every string change, forever.

When regional English earns its place

• •Your extension has substantial prose — onboarding, an options page with explanations, error messages written in full sentences. Spelling differences become visible at that volume.
• •You are selling to a specific market where the wrong spelling reads as careless, or where terminology genuinely differs (billing, legal, education, healthcare).
• •You already maintain a US and a UK voice for a website or marketing site, so the copy exists and only needs porting.

This is why LocalePack ships 52 locales rather than 55: the three English variants are an editorial call about your own source copy, not something a translation step should invent for you.

Store listing languages are a different surface

The codes on this page govern strings inside your extension: the popup, the options page, context menu items, and the __MSG_key__ substitutions in manifest.json.

Your Chrome Web Store listing — the title, summary, detailed description and screenshots a user reads before installing — is localised separately, in the Developer Dashboard, with its own language set. Translating one does not translate the other, and the two lists are not identical. It is entirely possible to have a fully localised extension with an English-only store listing, which is the worse half to leave undone: the listing is what decides whether the install happens at all.

• •_locales/ — in-product strings, shipped in the ZIP, codes from the table above.
• •Store listing — marketing copy, entered per language in the Developer Dashboard, not part of your build.

The differences are covered in detail in store listing vs in-extension i18n.

Pre-release checklist

• •Every folder under _locales/ is on the 55-code list — spelled with an underscore and an uppercase region subtag.
• •default_locale is set, is on the list, and has a matching folder containing every key.
• •Base language folders exist next to any regional variants (en with en_GB, es with es_419).
• •No empty "message": "" values left behind by a partial translation pass.
• •Each messages.json is valid JSON with no trailing commas and no comments.
• •The ZIP you upload preserves the folder names — some archive tools normalise case. Unzip your own artifact and look before you submit.

Frequently asked questions

Related guides

• •Chrome extension i18n: the _locales folder structure — where the folders live and what goes inside them.
• •default_locale: rules and common errors — the exact Chrome load errors and how to fix each one.
• •Store listing vs in-extension i18n — the two localisation surfaces and why both matter.