Documentation

Unity Engine

User Manual

Script Reference

Unity Engine

Synchronous and asynchronous loading

Understand when localized content loads synchronously and when it must load asynchronously.
Read time 1 minuteLast updated 12 days ago
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:

Value

Description

AsynchronousValues resolve in the background and arrive through events. The default.
SynchronousValues resolve immediately when they can. When a value can't resolve synchronously, it falls back to the asynchronous path rather than failing.
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