Country, Language and Locale Codes

Software names countries, languages and currencies with short standard codes. They look alike, but each list follows its own rules, and mixing them up is a common source of bugs.

Three ways to write a country

ISO 3166-1 gives each country, and a number of territories, three codes: a two-letter alpha-2 code, a three-letter alpha-3 code, and a three-digit numeric code. Alpha-2 is the one you meet most in software. It appears in locale tags, address forms and most country-code top-level domains. Alpha-3 is easier for people to recognise and is common in data sets. The numeric code does not depend on Latin letters and lines up with the UN M.49 statistical codes.

CountryAlpha-2Alpha-3Numeric
United StatesUSUSA840
United KingdomGBGBR826
GermanyDEDEU276
FranceFRFRA250
JapanJPJPN392
BrazilBRBRA076
IndiaININD356
CanadaCACAN124
MexicoMXMEX484
AustraliaAUAUS036

The numeric code is a three-character string, not a number. Brazil is 076 and Australia is 036, so keep the column as text or the leading zero disappears.

GB, not UK

The ISO alpha-2 code for the United Kingdom is GB, and the alpha-3 code is GBR. UK is not the assigned code, even though the country's top-level domain is .uk. ISO keeps UK reserved so that no other country receives it. Any form or database that validates against ISO 3166-1 should therefore expect GB.

Language codes: ISO 639

ISO 639-1 gives widely used languages a two-letter lowercase code. ISO 639-2 and ISO 639-3 add three-letter codes and cover many more languages. When a language has a two-letter code, that is the one to use in tags.

LanguageISO 639-1ISO 639-2
Englisheneng
Spanishesspa
Frenchfrfra
Germandedeu
Japanesejajpn
Chinesezhzho
Portugueseptpor
Arabicarara
Hindihihin

Several of these differ from the country code a beginner would guess. Japanese is ja while Japan is JP. Chinese is zh, from the language's own name, and German is de, from Deutsch. Languages and countries are separate lists for a reason: Spanish is spoken in many countries, and India uses many languages.

BCP 47 language tags

When a language alone is not precise enough, use a BCP 47 tag. This IETF standard defines the values used in the HTML lang attribute, the HTTP Accept-Language header and most locale libraries. A tag joins subtags with hyphens in a fixed order: language first, then an optional script, then an optional region.

TagSubtagsMeaning
en-USen + region USEnglish as used in the United States
en-GBen + region GBEnglish as used in the United Kingdom
pt-BRpt + region BRPortuguese as used in Brazil
fr-CAfr + region CAFrench as used in Canada
zh-Hant-TWzh + script Hant + region TWChinese in Traditional characters, as used in Taiwan
es-419es + region 419Spanish for Latin America

The script subtag comes from ISO 15924 and has four letters, such as Hant (Traditional Han), Hans (Simplified Han) and Latn (Latin). A region subtag is either an ISO 3166-1 alpha-2 code or a three-digit UN M.49 code. M.49 codes can name areas larger than one country. 419 stands for Latin America and the Caribbean, so es-419 lets one Spanish text serve that whole region.

Keep tags short. Plain en is fine unless the regional difference matters, and en-Latn adds nothing.

Case conventions

BCP 47 tags are case-insensitive, so EN-us and en-US mean the same thing. The conventional style is still worth following: language in lowercase, script in title case, region in uppercase. That gives zh-Hant-TW, not ZH-hant-tw. POSIX locale names and some libraries write locales with an underscore, as in en_US. Convert the underscore to a hyphen before the value goes into HTML or an HTTP header.

Tags in HTML: lang and hreflang

The lang attribute on the html element declares the main language of a page. Screen readers use it to choose pronunciation, and browsers use it for hyphenation and font choice. A passage in another language can carry its own attribute.

<html lang="en-US">
...
<p>The French word <span lang="fr">merci</span> means thank you.</p>

When a site has translated versions of a page, hreflang values on alternate links tell search engines which version suits which audience. The values are BCP 47 tags such as en, pt-BR or es-419, and each version should list all the others as well as itself. The special value x-default marks the fallback for visitors who match none of the listed tags. A region on its own is not valid: hreflang always starts with a language.

Declaring a page's language is a separate job from declaring its text encoding; character encoding covers the second one.

Currency codes: ISO 4217

An amount of money needs a currency code beside it, and ISO 4217 supplies three-letter codes. For most national currencies, the first two letters are the country's alpha-2 code and the third comes from the currency's name. The euro does not follow that pattern because it is shared by many countries.

CodeNumericCurrency
USD840US dollar
EUR978Euro
JPY392Japanese yen
GBP826Pound sterling

USD, JPY and GBP share their numeric code with their country (840, 392 and 826). Do not assume two decimal places for every currency: ISO 4217 lists the yen with no minor unit.

Common mistakes

  • Writing UK in a field that expects an ISO country code. Use GB.
  • Using a country code as a language, as in lang="jp" or lang="cn". Japanese is ja and Chinese is zh.
  • Putting en_US in a lang or hreflang value. HTML expects the hyphen form.
  • Storing numeric country codes as integers and losing the leading zero.
  • Assuming one language per country, or one country per language. Let people choose their language separately from their country.
  • Reading currency from a locale. en-GB says nothing about whether a price is in GBP, and a person's time zone is another separate setting; see time zones and UTC.