Synchronous and asynchronous loading

Understand when localized content loads synchronously and when it must load asynchronously.

Every accessor in Localization comes in two forms: a synchronous call that returns the value directly, and an asynchronous one that returns an Awaitable and accepts a CancellationToken. For example, use GetLocalizedString for the synchronous form and GetLocalizedStringAsync for the asynchronous form. For more information about CancellationToken, refer to CancellationToken (Microsoft).

When synchronous calls work

A synchronous call succeeds when everything it needs is already loaded or can load without waiting. That depends on the content source serving the value:

• Direct references are in memory after the table loads, so they resolve synchronously.
• A Resources folder source loads both ways.
• Other sources, for example a source that reads files or downloaded content, might only load asynchronously.

When a synchronous call can’t produce the value, it returns nothing and you must request the content asynchronously instead.

// The synchronous call returns the value directly when the content can load synchronously.
string value = scoreText.GetLocalizedString();

The loading preference

Event-driven paths, such as StringChanged, components, and UI Toolkit bindings, follow the PreferredLoading setting:

Synchronous loading keeps UI updates on the same frame, but blocks on any load the source performs.

Initialization

The first request triggers initialization automatically. To front-load it, for example behind a splash screen, await InitializeAsync:

await LocalizationSettings.InitializeAsync();

Localization raises InitializationCompleted when initialization finishes.

Additional resources

• How localization works
• Content sources
• Localize assets