Locale resolution

Understand which saved configuration applies to a requested language, region, or script, and how instructions, voice, models, and terminology use it.

A request uses configuration saved for its own locale, for a broader locale that contains it, and for *. Configuration saved for a more specific locale or for another region of the same language does not apply. What happens to the applicable configuration depends on the resource: instructions accumulate, one voice variation wins, models form an ordered attempt chain, and a custom translation must also use the request's script.

For choosing language tags in the first place, read Languages. This reference explains what happens after those tags reach the localization engine.

Which configuration applies #

Locale handling uses CLDR data to treat equivalent spellings as one locale: zh, zh-CN, zh-Hans, and zh-Hans-CN all name Simplified Chinese as used in China. A locale without a region stands for its default region. A request for es is a request for Spanish as used in Spain (es-ES), pt stands for pt-BR, and de stands for de-DE.

Configuration applies to a request when its locale is one of these:

  • *, which applies to every locale.
  • The requested locale, in any equivalent spelling.
  • A broader locale that contains the requested one. de applies to de-CH, and zh-Hant applies to zh-TW.

Any other locale is left out. That includes a more specific region, such as de-CH for a de request, and another region of the same language, such as de-DE for a de-CH request.

RequestAppliesDoes not apply
es*, es, es-ESes-MX, es-419
es-MX*, es, es-MXes-ES, es-419
de-CH*, de, de-CHde-DE, de-AT
zh-TW*, zh, zh-Hant, zh-TWzh-Hans, zh-CN
sr*, sr, sr-Cyrlsr-Latn

A region group such as es-419 is a locale of its own. It applies to es-419 requests only, so requests for es-MX or es-AR do not receive it.

The same rule applies to source locales where a resource has one, which is the case for model configurations and glossary terms. A term saved for source en-GB does not apply to content whose source locale is en, because en stands for en-US.

To share guidance across every region of a language, save it for the bare language, such as es. Save it for a region only when it belongs to that region's audience.

Match tiers order the applicable configuration #

The localization engine sorts applicable configuration into match tiers: the requested locale first, then a broader locale, then *. Within a tier, the more specific spelling comes first, so for a de request a de-DE variation ranks ahead of a de variation.

Use an explicit regional locale when it is part of the requirement. Also keep distinct language identifiers distinct: no and nb are different codes, and configuration saved for one does not apply to the other.

Each resource uses the applicable configuration differently #

ResourceResult
RulesApplicable predefined and custom instructions accumulate in locale-relevance order. Specific rules do not erase broad ones.
Brand voiceThe best-matching variation wins. Creation time, then ID, stabilizes a remaining tie.
ModelsTarget match tier, source match tier, target specificity, source specificity, and configured rank determine the attempt order.
GlossaryCustom translations in another script are left out. The remaining candidates are deduplicated by source text after locale ranking. Retrieval then selects applicable context.
Human reviewA request is reviewed when one of the review policy's languages applies to it, or when the policy names none.

Model rank cannot move a wildcard configuration ahead of a closer locale match. Glossary attachment order does not establish precedence. Keep these distinctions in mind when the saved configuration contains the expected material but a request chooses something else.

Diagnose a regional or script mismatch #

Guidance saved for one region is missing from another #

Suppose a glossary's Spanish terms are saved for es-419, and requests target es or es-MX. Neither request receives the terms: es stands for Spain, and es-419 applies only to es-419 requests. Save terms shared by every Spanish audience for es, or save them for each region you request. Portuguese works the same way: pt stands for Brazil, so terms saved for pt-PT reach only pt-PT requests.

The voice is regional but the request is bare #

Suppose a voice has de-DE and de-CH variations, and the request targets de. The request receives the de-DE variation, because de stands for German as used in Germany. The de-CH variation applies only to de-CH requests. For content intended for Switzerland, request de-CH instead of expecting the localization engine to infer the audience from the source.

A regional rule contradicts a broad rule #

A wildcard rule requiring formal address and an applicable regional rule requesting informal address can both enter the prompt. Adding specificity does not cancel the broad requirement. Remove or narrow the contradiction so the selected instructions express one intended behavior.

The preferred term uses a different script #

A custom translation applies only when its locales imply the same scripts as the request's, for both the source and the target. Each locale implies a script through CLDR defaults: zh, zh-CN, and zh-SG imply Simplified, zh-TW and zh-HK imply Traditional, sr implies Cyrillic, and sr-ME implies Latin.

So a term saved for zh reaches zh, zh-CN, and zh-SG requests but never a zh-TW request, even though rules and voice saved for zh apply to zh-TW. A term saved for zh-Hans reaches a zh request, and a term saved for zh-TW reaches a zh-Hant request. Save a Traditional term shared by Taiwan and Hong Kong for zh-Hant. A non-translatable name is exempt because it stays unchanged.

The custom translation targets every language #

A custom translation with target * cannot contain target text different from its source. Use a concrete target locale for a preferred translation, or a non-translatable entry for text that must remain the same everywhere.

Check each part when adding a locale #

Language configuration does not implement right-to-left layout or locale-aware application formatting. Check the rendered interface alongside the translation. A useful sample establishes behavior for that case, not general quality across the new locale.