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.
| Country | Alpha-2 | Alpha-3 | Numeric |
|---|---|---|---|
| United States | US | USA | 840 |
| United Kingdom | GB | GBR | 826 |
| Germany | DE | DEU | 276 |
| France | FR | FRA | 250 |
| Japan | JP | JPN | 392 |
| Brazil | BR | BRA | 076 |
| India | IN | IND | 356 |
| Canada | CA | CAN | 124 |
| Mexico | MX | MEX | 484 |
| Australia | AU | AUS | 036 |
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.
| Language | ISO 639-1 | ISO 639-2 |
|---|---|---|
| English | en | eng |
| Spanish | es | spa |
| French | fr | fra |
| German | de | deu |
| Japanese | ja | jpn |
| Chinese | zh | zho |
| Portuguese | pt | por |
| Arabic | ar | ara |
| Hindi | hi | hin |
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.
| Tag | Subtags | Meaning |
|---|---|---|
en-US | en + region US | English as used in the United States |
en-GB | en + region GB | English as used in the United Kingdom |
pt-BR | pt + region BR | Portuguese as used in Brazil |
fr-CA | fr + region CA | French as used in Canada |
zh-Hant-TW | zh + script Hant + region TW | Chinese in Traditional characters, as used in Taiwan |
es-419 | es + region 419 | Spanish 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.
| Code | Numeric | Currency |
|---|---|---|
| USD | 840 | US dollar |
| EUR | 978 | Euro |
| JPY | 392 | Japanese yen |
| GBP | 826 | Pound 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
UKin a field that expects an ISO country code. UseGB. - Using a country code as a language, as in
lang="jp"orlang="cn". Japanese isjaand Chinese iszh. - Putting
en_USin alangorhreflangvalue. 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-GBsays nothing about whether a price is in GBP, and a person's time zone is another separate setting; see time zones and UTC.