Documentation

Unity Engine

User Manual

Script Reference

Unity Engine

Localize strings

Display localized and dynamic text from scripts and components.
Read time 3 minutesLast updated 10 days ago
Display localized and dynamic text from scripts and components.
A 
LocalizedString
 references one entry in a table collection and provides its value for the selected locale. Add it as a serialized field, pick the entry in the
Inspector

?

window, and subscribe to its value.

Prerequisites

Before you start, make sure you have the following:

Reference a string in the Inspector window

Add a 
LocalizedString
field to a component:
public class ScoreDisplay : MonoBehaviour    {        public LocalizedString scoreText = new();        IntVariable m_Score = new();        void OnEnable()        {            scoreText.LocalVariables.Add(m_Score, "score");            scoreText.StringChanged += OnStringChanged;        }        void OnDisable()        {            scoreText.StringChanged -= OnStringChanged;            scoreText.LocalVariables.Remove("score");        }        void OnStringChanged(string value) => GetComponent<TextMesh>().text = value;        public void AddPoints(int points)        {            m_Score.Value += points;            scoreText.RefreshString();        }    }
The Inspector window drawer for the field lets you pick a collection and an entry, or create a new entry inline. Once an entry is selected, the drawer shows a rail of the collection's locales with a preview of each locale's value, and a detail pane where you edit the value for the selected locale.
For a Smart String entry, the detail pane adds three tabs that help you author and debug the format:
  • Edit edits the value in the selected locale.
  • Debug parses the value and shows its literal segments and placeholders.
  • Preview shows the value formatted with the current local variables.

React to the value

Subscribe to 
StringChanged
. The reference raises it with the current value when the string first resolves, and again whenever the value changes, including when the user switches language. Event subscription is the recommended path for UI text: subscribe once, assign the value in the handler, and the text updates on every language change.
To retrieve a value on demand instead, call 
GetLocalizedString
 or its asynchronous counterpart 
GetLocalizedStringAsync
. Refer to Synchronous and asynchronous loading.

Dynamic values

Enable the key's Smart string toggle in the table editor, and its value becomes a Smart String format, such as 
Score: {score}
. Supply values either as arguments to 
GetLocalizedString
, or through the reference's 
LocalVariables
 group. After you change a variable, call 
RefreshString
 to re-raise 
StringChanged
with the new value.
For a complete example, refer to Display dynamic values in a localized string.
A 
LocalizedString
can also act as a variable inside another Smart String. For example, if a notification's Smart String reads 
New quest: {questTitle}
and 
questTitle
is another 
LocalizedString
, the nested title resolves in the same locale as the notification.

Localize without code

To localize text with a component instead of a script:
  1. Add a Localize String Event component (
    LocalizeStringEvent
    ) to a GameObject.
  2. Set its String field to the table entry. The dropdown lists every entry across your collections.
  3. Assign a target to the On Update String event. For example, drag a text component from the same GameObject onto the event, then choose its 
    text
    property. When the entry's value updates, the event sets that property.
The component keeps the target updated on language changes.
To localize a list of values, for example a dropdown's options, use a Localize String List Event component (
LocalizeStringListEvent
) instead:
  1. Set List Kind to Single entry, split on a separator (
    LocalizedStringList
    ) or Group of entries (
    LocalizedStringGroup
    ).
  2. Select the table entries in List reference.
  3. Assign a target to the On Update List event, which receives the resolved values.

Additional resources