How localization works

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

Read time 3 minutes

Last updated 7 days ago

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:

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.
Startup selection: the startup locale selectors run in list order, and localization uses the first selector that returns an enabled locale.
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 localized value resolves, from reference to formatted result.

A reference such as

LocalizedString

names a table collection and an entry. It resolves a value in the following order:

The
```
ResourceDatabase
```
asks the content source chain for the collection's table in the selected locale. Refer to Content sources.
The table looks up the entry by key or ID.
If the entry has no value, the lookup retries with the locale's fallback.
If the key has its Smart string toggle enabled, the value formats through Smart Strings, with any arguments and local variables you supplied.
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.

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.