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.
| 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) |
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 (sr-Cyrl, sr-Latn, zh-Hans, zh-Hant) on write. 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.