How localization works

Understand how localization initializes, selects a locale, and resolves a value.

The LocalizationSettings asset holds the available locales, the startup locale selectors, the content sources, and the ResourceDatabase that resolves values. The asset ships with the Player and registers itself at startup.

Initialization

Localization initializes once, the first time something asks for a localized value, or when you call InitializeAsync yourself. Initialization runs three steps in order:

1. Locale discovery: each content source that implements ILocaleDiscovery can add locales it finds in its content. For example, a data-file source adds a locale for each table file it finds, so a build can gain a language after release. Refer to Add a language to a built Player.
2. Startup selection: the startup locale selectors run in list order, and localization uses the first selector that returns an enabled locale.
3. Fallback: if no selector returns a locale, localization selects the project locale.

When initialization completes, localization raises InitializationCompleted, and any selector that needs one-time setup runs at this point.

How a value resolves

flowchart TD
    ref["LocalizedString / LocalizedAsset<br>(table reference + entry reference)"]
    ref --> db["ResourceDatabase"]
    db --> src["Content source chain<br>resolves the table for the selected locale"]
    src --> entry["Entry lookup by key or ID"]
    entry --> fb{"Value found?"}
    fb -- no --> fallback["Retry with the locale's fallback"]
    fallback --> entry
    fb -- yes --> smart{"Smart string enabled?"}
    smart -- yes --> fmt["Format with Smart Strings<br>(arguments + local variables)"]
    smart -- no --> post
    fmt --> post["Locale post-processing<br>(IPostProcessValueLocale)"]
    post --> value["Value"]

    classDef code fill:#F5F5F5,stroke:#BDBDBD,color:#111;
    class ref,db,src,entry,fallback,fmt,post,value code;
    linkStyle default stroke:#2196F3,stroke-width:1.5px;

A reference such as LocalizedString names a table collection and an entry. It resolves a value in the following order:

1. The ResourceDatabase asks the content source chain for the collection’s table in the selected locale. Refer to Content sources.
2. The table looks up the entry by key or ID.
3. If the entry has no value, the lookup retries with the locale’s fallback.
4. If the key has its Smart string toggle enabled, the value formats through Smart Strings, with any arguments and local variables you supplied.
5. If the locale implements IPostProcessValueLocale, it post-processes the value. A pseudo-locale can use this hook to transform text for layout testing.

Every step has a synchronous and an asynchronous path. Refer to Synchronous and asynchronous loading.

React to language changes

Localization raises LocalizationSettings.SelectedLocaleChanged when the language changes. References raise their own events too: a LocalizedString raises StringChanged with the new value, so UI subscribed to it updates without polling.

Additional resources

• Locales
• Content sources
• Localize strings
• Generate dynamic text with Smart Strings