Every glossary item, brand voice, instruction, and model config is stored against a locale. When the engine processes a translation request, it resolves which stored entries apply to the request locale - matching exact codes, inheriting across regional variants, and falling back when no exact entry exists. The same resolution applies to all four configuration surfaces.
How it works#
Locales are normalized to a canonical form on input, then stored and returned in that form. Casing and delimiters are fixed; subtags are preserved.
| You enter | Stored as |
|---|---|
EN | en |
en_US | en-US |
sr_Latn-RS | sr-Latn-RS |
zh-cn | zh-CN |
Matching is bidirectional across the subtag boundary - a stored locale applies to a request when one is an exact match or an ancestor of the other. Two spellings of the same locale also match when neither is an ancestor of the other but a region determines the script: the region-only and script-qualified forms are equivalent (zh-CN ≡ zh-Hans-CN, zh-TW ≡ zh-Hant-TW).
| Stored | Applies to | Does not apply to |
|---|---|---|
de | de, de-DE, de-AT, de-CH | - |
de-DE | de-DE, de | de-AT, de-CH (siblings) |
zh-CN | zh-CN, zh-Hans-CN, zh | zh-TW, zh-Hant-TW (different script) |
Reverse-inheritance
A stored de-DE answering a bare de request is the dominant real-world pattern: most engines are configured against full regional codes but receive base-code requests. Both directions are supported.
Resolving between multiple matches#
When more than one stored entry applies, the engine ranks them and uses the best:
- Exact or language-default first. For a
derequest,de-DE(the CLDR default region for German) is preferred, then barede. - Most specific next, as a tiebreak.
- Any other matching region survives as a fallback - a customer whose only entry is
de-CHstill gets it for aderequest when nothing better matches, so configuration is never orphaned.
| Request | Preferred | Also applies (fallback) | Excluded |
|---|---|---|---|
de | de-DE, then de | de-CH, de-AT | - |
de-DE | de-DE, then de | - | de-AT, de-CH |
de-AT | de-AT, then de | - | de-DE, de-CH |
Script safety#
One extra rule applies only to glossary custom_translation items, whose text is bound to a specific orthography. A base language with an ambiguous script - sr (Cyrillic or Latin), zh (Simplified or Traditional) - must commit to a script on write, either as an explicit script (zh-Hans, sr-Cyrl) or a region that determines one (zh-CN → Simplified, sr-RS → Cyrillic, per CLDR). Only a truly bare code with no script and no region is rejected. On read these commit forms are equivalent - a glossary stored as zh-Hans-CN applies to a zh-CN request and vice versa - but a bare zh request, whose script is unknown, does not pick up a script-committed row, so send an explicit script or region for predictable results. Languages with a single script, like de, need no script and resolve de to de-DE normally. non_translatable items pass through regardless of script.
Example#
An engine configured with regional codes (en-US to fr-FR, de-DE, nb-NO) receiving base-code requests (fr, de, no):
- A
frtarget picks up thefr-FRglossary, brand voice, and instructions - ranked as the default forfr, not a last resort, becausefr-FRis the CLDR default region for French. - A source of
enmatchesen-USentries - matching is bidirectional. - A
notarget does not pick upnb-NO.noandnbare different language subtags, not a region pair; usenbas the target.
Using locale resolution with the API#
Resolution happens automatically when you call the localize endpoint. The engine matches the request's sourceLocale and targetLocale against stored glossaries, brand voices, instructions, and model configs - no additional parameters are needed.
