ISO 639 & Locale Tags Made Easy: The Developer’s Practical Guide

ISO 639 & Locale Tags Made Easy: ISO 639 standards are the international codes we use to name languages (like ‘en’), while Locale Tags (BCP 47) combine those codes with regions (like ‘en-US’). Together, they handle regional variations and formatting, making sure your software shows the right content to the right global audience.

Understanding the Foundation: ISO 639-1, 639-2, and 639-3 Explained

ISO 639 is how we classify the world’s languages in code. It has grown from simple two-letter tags for major national languages into a massive three-letter system that tracks nearly every natural language ever documented—including ancient, extinct, and even constructed ones.

The system is split into different levels of detail. ISO 639-1 uses two-letter (alpha-2) codes, like en for English or zh for Chinese. ISO 639-2 and ISO 639-3 expand this into three-letter (alpha-3) codes. While the first set covers the most common languages, ISO 639-3 aims to be exhaustive, including minority tongues and specialized linguistic sets.

Based on data from Wikipedia (2026), there are 183 two-letter codes registered in ISO 639-1, which cover the primary languages used in global trade. The three-letter system is much larger. According to SIL International (2026), there are now 7,916 entries in ISO 639-3, giving a unique ID to almost every documented language on Earth.

The 2026 Update: Moving Toward a Unified ISO 639 Standard

In a move to simplify things for developers, all parts of the ISO 639 series were brought under one roof. This update, known as ISO 639:2026, connects the different sets and uses a joint maintenance agency in Norway to manage the codes. This unification stops the fragmentation that used to frustrate developers, making sure that codes across Set 1, 2, 3, and 5 work together in one global framework.

IETF BCP 47 Language Tags: The Gold Standard for Web Content

While ISO codes identify a language, IETF BCP 47 Language Tags are what you actually use to manage content on the internet. BCP 47 isn’t just one code; it’s a “Best Current Practice” that glues various ISO standards into a single, structured tag. It is the main method used by HTTP, HTML, and XML to handle localization.

A BCP 47 tag follows a specific pattern: Language-Script-Region-Variant. For example, zh-Hant-HK tells the system the language is Chinese (zh), the script is Traditional (Hant), and the region is Hong Kong (HK). This structure lets software tell the difference between “Spanish in Spain” (es-ES) and “Spanish in Latin America” (es-419), which changes how dates, currency, and local idioms appear.

The IANA Language Subtag Registry manages these tags. It keeps the subtags valid and ensures that if an ISO code changes, the BCP 47 tag stays stable so it doesn’t break your web implementation. As the official ISO 639-3 documentation (2026) notes: “A collective language code element is an identifier that represents a group of individual languages.” BCP 47 uses these collective codes if a specific individual code isn’t available.

How to Structure a Valid BCP 47 Tag (With Examples)

When building a BCP 47 tag, use the “shortest-first” rule. If a two-letter ISO 639-1 code exists, you have to use it as the primary tag.

• Simple Language: en (English), fr (French).
• Language + Region: en-US (English, USA), pt-BR (Portuguese, Brazil).
• Language + Script: sr-Cyrl (Serbian in Cyrillic), sr-Latn (Serbian in Latin).
• Full Locale: zh-Hans-SG (Chinese, Simplified script, Singapore).

Implementation Checklist: Choosing Between ISO 639-1 and BCP 47

Choosing between a raw ISO 639-1 code and a full BCP 47 tag depends on how much precision your app needs. If you only need to know if someone wants “English” or “German,” the two-letter code is fine. But for anything involving regional formatting—like currency or date styles—BCP 47 is a must.

When you’re working on internationalization (i18n), don’t confuse language with geography. ISO 3166 (Country Codes) tell you where a user is, but ISO 639 tells you what they speak. A common mistake is using a country flag to represent a language. Instead, use BCP 47 tags so an English speaker in Canada (en-CA) sees different measurement units or date formats than someone in the US (en-US).

Developer Decision Tree: Which Code Should You Use?

1. Is it just for a simple UI toggle? Use ISO 639-1 (e.g., en, es).
2. Does the app handle dates, numbers, or currency? Use BCP 47 (e.g., en-GB).
3. Are you using a modern framework?
   • React i18next / Next.js: These usually default to BCP 47 for routing.
   • Java: The java.util.Locale class has supported BCP 47 since Java 7.
4. Are you documenting rare or extinct languages? Use ISO 639-3 three-letter codes.

How are Macrolanguages and Complex Scripts Handled?

In global software, some codes represent Macrolanguages—broad categories that cover multiple, distinct “member” languages. For example, zho (Chinese) and ara (Arabic) are macrolanguages. While you might use zh for a general site, a more precise app might need cmn (Mandarin) or yue (Cantonese).

To handle different writing systems, BCP 47 includes ISO 15924 (Script Codes). This is helpful for languages like Azerbaijani, which can be written in Latin, Cyrillic, or Arabic scripts. By adding a four-letter script tag, you make sure the right characters are rendered. A common example is zh-Hant (Traditional Chinese) versus zh-Hans (Simplified Chinese).

The B vs. T Distinction in ISO 639-2: Terminological vs. Bibliographical

ISO 639-2 has a weird historical quirk: 20 languages have two different three-letter codes. Terminology codes (T-codes) come from the native name of the language (like deu for Deutsch), while Bibliographic codes (B-codes) are based on the English name (like ger for German).

Modern systems and ISO 639-3 always use T-codes for technical work.

How Does Locale Matching Work (Filtering and Lookup)?

Locale Matching is how a system decides which of your supported languages best fits what the user asked for. When a browser sends an Accept-Language header (like da, en-gb;q=0.8, en;q=0.7), the server has to pick the best match.

There are two main ways to do this (defined in RFC 4647):

1. Filtering: This returns a list of all matching languages. If a user asks for en-US, it might return both en-US and the general en.
2. Lookup: This finds the single “best” match by starting with the most specific tag and “falling back” to more general ones. If zh-Hant-HK isn’t there, the system looks for zh-Hant, then finally zh.

Modern environments like Node.js or Java use these tools to make sure users never see a broken page. They’ll always fall back to a default “root” locale (usually en) if nothing else matches.

FAQ

What is the difference between a language code and a country code?

Language codes (ISO 639) tell you what is being spoken, like en for English. Country codes (ISO 3166) tell you where it is being spoken, like US for the United States. A locale tag (BCP 47) puts them together (like en-US) to handle regional details, ensuring currency symbols, dates, and spellings are correct for that specific place.

When should I use a three-letter ISO 639-3 code instead of a two-letter ISO 639-1 code?

Stick with ISO 639-1 (two-letter) codes for most web development and standard software, as they cover the languages most people actually speak. You only need ISO 639-3 (three-letter) codes for specialized linguistics, documenting minority or extinct languages, or if the language you’re using simply doesn’t have a two-letter version.

What are special codes like ‘und’, ‘mul’, and ‘zxx’ used for in metadata?

These help with “edge cases” in databases. und (Undetermined) is for when you don’t know the language. mul (Multiple) is used if a file contains several languages and you can only pick one tag. zxx means there is “No linguistic content”—think of instrumental music, animal sounds, or raw machine data.

Conclusion

Getting a handle on ISO 639 and BCP 47 locale tags is the first step toward building software that works everywhere. Once you understand the gap between a language and its regional variations, you can avoid the usual headaches with date formats, currency symbols, and broken characters. Moving from basic two-letter codes to structured BCP 47 tags keeps your app scalable and ready for a global audience.