Locale mapping

A locale identifier tells software which language, region, and sometimes script to use. The catch is that there is no single universal format. BCP 47 uses pt-BR. POSIX uses pt_BR.UTF-8. Java has historically used pt_BR. Android resource folders use values-pt-rBR. Apple platforms accept pt-BR but sometimes surface it as pt_BR in older APIs. When a product is localized across several of these, someone has to decide how a translation labeled one way lines up with a locale expected another way. That decision is locale mapping.

Mapping also covers ambiguity inside a single standard. Norwegian can appear as no, nb (Bokmål), or nn (Nynorsk). Chinese is often written as zh-CN or zh-TW, but modern practice prefers script tags like zh-Hans and zh-Hant. Portuguese may be split into pt-BR and pt-PT, or collapsed to pt. None of these are wrong on their own. They just need to agree with each other for the right file to reach the right user.

🌍 Locale mapping in localization #️⃣

Localization teams meet this problem whenever the source of truth for translations does not match the runtime code that requests them. Common situations:

• Multiplatform projects. The same strings are shipped to iOS, Android, and web, each of which expects a slightly different locale format on disk or in the API request.
• Format conversion. Exporting a project from one file format to another may require rewriting the locale in the filename, the folder, or the file header.
• Fallbacks. When a user’s exact locale is not available, the system needs to fall back predictably. A visitor set to es-MX should usually see es before defaulting to the source language.
• Legacy identifiers. Older systems may still use codes like iw for Hebrew or in for Indonesian, which were replaced by he and id in modern standards.
• Regional splits. A project translated for en may need to serve both en-US and en-GB users, with or without a variant that differs by spelling.

Getting the mapping wrong shows up as missing translations, wrong-language fallbacks, or content that reaches production in a locale the app never intended to support.

🧩 What locale mapping usually handles #️⃣

• Standard-to-standard conversion. Translating between BCP 47, POSIX, ISO 639, and platform-specific formats.
• Script disambiguation. Deciding whether zh-CN should be treated as zh-Hans and how to handle Serbian in Latin and Cyrillic scripts.
• Region collapsing or splitting. Deciding whether pt-BR and pt-PT share a translation or need separate ones.
• Fallback chains. Defining the order in which the system tries alternative locales before giving up.
• Legacy code translation. Rewriting deprecated codes to their modern equivalents.
• File and folder naming. Producing the exact identifier each target platform expects in its build output.

💡 On Localazy #️⃣

Localazy’s language reference is built on Unicode CLDR data and supports BCP 47 identifiers, and platform-specific output is handled through its format conversions and multiplatform export options, so the same source translation reaches iOS, Android, and web in the format each one expects.