UI Toolkit (2023.3+)

Note

This feature requires Unity 2023.3 and above.

The localization package provides UI Toolkit support through the data bindings system. When you bind a field, it automatically updates itself when you create the UI Document, change the selected locale, or change a persistent variable with a LocalizedString. You can add a localized binding in UI Builder, UXML, or C# script.

The following table lists the supported localization bindings:

Binding Type Asset Type
LocalizedString string
LocalizedAudioClip Audio Clip
LocalizedFont Font
LocalizedGameObject GameObject / Prefab
LocalizedMaterial Material
LocalizedMesh Mesh
LocalizedObject Object
LocalizedTexture Texture
LocalizedTmpFont TextMeshPro Font
LocalizedSprite Sprite

UI Builder authoring

You can use the UI Builder to create and fine-tune UI assets and their associated data bindings, including localization data bindings. You can connect to visual element attribute fields or styles. You can also address mismatched data types smoothly by creating your own converters for data type conversion.

To bind an element's field to a localized value in UI Builder, do the following:

  1. In the Inspector panel of an element, right-click on a field and select Add binding.

    Adding a binding through the UI Builder.

  2. In the Add binding window, select the type of binding you want to use.

    Add binding window type popup showing localization binding types.

  3. To set up the binding, specify the table and entry you want to reference. If you're using a LocalizedString binding and want to include local variables, you can do so through the Variables field.

    Configuring a localized string in the Add binding window.

    Note

    By default, the table and entry are referenced using the Guid and ID. To customize this behavior, go to Edit > Preferences > Localization and adjust the Table Reference Method and Entry Reference Method options.

  4. The UI builder-generated UXML includes the new localized string binding like this:

    <ui:UXML xmlns:ui="UnityEngine.UIElements">
    <ui:Label text="Label">
        <Bindings>
            <UnityEngine.Localization.LocalizedString property="text" table="General Test Data" entry="My Entry">
                <variables>
                    <UnityEngine.Localization.LocalVariable name="counter">
                        <UnityEngine.Localization.SmartFormat.PersistentVariables.IntVariable value="2" />
                    </UnityEngine.Localization.LocalVariable>
                </variables>
            </UnityEngine.Localization.LocalizedString>
        </Bindings>
    </ui:Label>
</ui:UXML>

UXML authoring

You can also use the following UXML structure to create a binding directly in UXML:

<ELEMENT>
    <Bindings>
        <BINDING-TYPE property="PROPERTY-PATH" table="TABLE-NAME-OF-GUID" entry="ENTRY-NAME-OF ID" />
    </Bindings>
</ELEMENT>

The following example binds to a labels text, tooltip and style.backgroundImage fields:

<ui:UXML xmlns:ui="UnityEngine.UIElements">
    <ui:Label text="Label">
        <Bindings>
            <UnityEngine.Localization.LocalizedString property="text" table="GUID:27153e20147c06c4c8d1304d28104a87" entry="Id(328014486446080)" />
            <UnityEngine.Localization.LocalizedString property="tooltip" table="My Table" entry="My Tooltip" />
            <UnityEngine.Localization.LocalizedTexture property="style.backgroundImage" table="My Asset Table" entry="My Texture" />
        </Bindings>
    </ui:Label>
</ui:UXML>

In UXML, you can reference a table by either Guid or name. To reference by Guid, prefix the attribute value with "GUID:" like this: table="GUID:27153e20147c06c4c8d1304d28104a87". Similarly, you can reference a table entry by either ID or name. To reference by ID, use this format for the attribute value: Id(1234), where the value within the parentheses represents the ID value.

You can add local variables to a LocalizedString under the variables element.

The following example shows an integer and bool local variables:

<ui:UXML xmlns:ui="UnityEngine.UIElements">
    <ui:Label text="Label">
        <Bindings>
            <UnityEngine.Localization.LocalizedString property="text" table="GUID:27153e20147c06c4c8d1304d28104a87" entry="Id(328014486446080)">
                <variables>
                    <UnityEngine.Localization.LocalVariable name="apple-count">
                        <UnityEngine.Localization.SmartFormat.PersistentVariables.IntVariable />
                    </UnityEngine.Localization.LocalVariable>
                    <UnityEngine.Localization.LocalVariable name="flag">
                        <UnityEngine.Localization.SmartFormat.PersistentVariables.BoolVariable value="true" />
                    </UnityEngine.Localization.LocalVariable>
                </variables>
            </UnityEngine.Localization.LocalizedString>
        </Bindings>
    </ui:Label>
</ui:UXML>

To simplify the UXML, define namespace prefixes like this:

<ui:UXML xmlns:ui="UnityEngine.UIElements" xmlns:l="UnityEngine.Localization" xmlns:lv="UnityEngine.Localization.SmartFormat.PersistentVariables">
    <ui:Label text="Label">
        <Bindings>
            <l:LocalizedString property="text" table="My Table" entry="My Entry">
                <variables>
                    <l:LocalVariable name="apple-count">
                        <lv:IntVariable />
                    </l:LocalVariable>
                    <l:LocalVariable name="flag">
                        <lv:BoolVariable value="true" />
                    </l:LocalVariable>
                </variables>
            </l:LocalizedString>
        </Bindings>
    </ui:Label>
</ui:UXML>

Scripting

You can manipulate bindings on an element through the Scripting API.

Add a binding

The following examples shows how to use the SetBinding method to add a new binding to an element:

To add a string binding:

var label = new Label();
label.text = "Default Text";

// Add binding to the text property of the label.
var localizedString = new LocalizedString("My table", "My Entry");
label.SetBinding("text", localizedString);

To add an asset binding:

var element = new VisualElement();

// Add binding to the text property of the label.
var localizedTexture = new LocalizedTexture { TableReference = "My assets", TableEntryReference = "My texture" };
element.SetBinding("style.backgroundImage", localizedTexture);

Get an existing binding

You can update an existing binding, such as modifying a local variable. The following examples show how to access an existing binding:

var document = GetComponent<UIDocument>();
var label = document.rootVisualElement.Q<Label>("my label");

// Get the binding from the label
var binding = label.GetBinding("text") as LocalizedString;

// Update the local variable.
// Changing the value will trigger an automatic update of the label.
var score = binding["score"] as IntVariable;
score.Value++;

var document = GetComponent<UIDocument>();
var label = document.rootVisualElement.Q<Button>("my button");

// Get the binding from the button
var binding = label.GetBinding("iconImage.sprite") as LocalizedSprite;

// Change the sprite, this will trigger an automatic update of the button image.
binding.TableEntryReference = "A different sprite";

Bind to a custom element

You can create a custom element using the UxmlElement attribute, and add UXML attributes using the UxmlAttribute attribute. Binding to the attribute also requires the CreateProperty attribute.

The following shows defines and binds to a custom element:

[UxmlElement]
public partial class MyElement : VisualElement
{
    [UxmlAttribute, CreateProperty]
    public string MyString { get; set; }

    [UxmlAttribute, CreateProperty]
    public GameObject MyPrefab { get; set; }
}

The following example shows how to add bindings in UXML:

<ui:UXML xmlns:ui="UnityEngine.UIElements" xmlns:l="UnityEngine.Localization">
    <MyElement>
        <Bindings>
            <l:LocalizedString property="MyString" table="My String Table" entry="My String Table Entry" />
            <l:LocalizedGameObject property="MyPrefab" table="My Asset Table" entry="My Asset Table Entry" />
        </Bindings>
    </MyElement>
</ui:UXML>

The following example shows how to add bindings in the C# script:

var element = new MyElement();

// Add binding to the MyString property
var localizedString = new LocalizedString { TableReference = "My strings", TableEntryReference = "My string entry" };
element.SetBinding(nameof(MyElement.MyString), localizedString);

// Add binding to the MyPrefab property
var localizedPrefab = new LocalizedGameObject { TableReference = "My assets", TableEntryReference = "My prefab entry" };
element.SetBinding(nameof(MyElement.MyPrefab), localizedPrefab);

Custom asset bindings

You can create custom asset bindings in UI Builder or UXML by inheriting from LocalizedAsset<TObject>. The following example localizes a custom ScriptableObject asset on a custom element.

[CreateAssetMenu]
public class MyAsset : ScriptableObject
{
    public string someStringValue;
    public int someIntValue;
}

public partial class MyElementWithAsset : VisualElement
{
    [UxmlAttribute, CreateProperty]
    public MyAsset MyAsset { get; set; }
}

The Localized asset binding must be a UxmlObject to support the UI Builder and UXML serialization:

[UxmlObject]
public partial class LocalizedMyAsset : LocalizedAsset<MyAsset>
{
}

You can then bind the element in UXML like this:

<ui:UXML xmlns:ui="UnityEngine.UIElements">
    <MyAsset>
        <Bindings>
            <l:LocalizedMyAsset property="MyAsset" table="My Table" entry="My Entry" />
        </Bindings>
    </MyAsset>
</ui:UXML>

You can also bind the element in C# script like this:

var element = new MyElementWithAsset();
var localizedAsset = new LocalizedMyAsset { TableReference = "My table", TableEntryReference = "My entry" };
element.SetBinding(nameof(MyElementWithAsset.MyAsset), localizedAsset);

Custom Persistent Variables

To enable custom persistent variables to be assignable with UI Builder and support UXML serialization, the variables must implement the UxmlObject. attribute.

The following example shows how to implement and use a custom persistent variable:

[UxmlObject, Serializable]
public partial class MyDateTimeVariable : IVariable
{
    [UxmlAttribute, Range(1900, 2050)] public int year;
    [UxmlAttribute, Range(0, 12)] public int month;
    [UxmlAttribute, Range(0, 31)] public int day;
    [UxmlAttribute, Range(0, 24)] public int hour;
    [UxmlAttribute, Range(0, 60)] public int min;
    [UxmlAttribute, Range(0, 60)] public int sec;

    public object GetSourceValue(ISelectorInfo _)
    {
        try
        {
            return new DateTime(year, month, day, hour, min, sec);
        }
        catch
        {
            // Ignore issues about incorrect values.
        }
        return new DateTime();
    }
}

Example UXML:

<ui:UXML xmlns:ui="UnityEngine.UIElements">
    <ui:Label text="Label">
        <Bindings>
            <UnityEngine.Localization.LocalizedString property="text" table="GUID:c8f98e364e2be0740b8f92096af691d3" entry="Id(75017969829142528)">
                <variables>
                    <UnityEngine.Localization.LocalVariable name="date">
                        <MyDateTimeVariable year="2023" />
                    </UnityEngine.Localization.LocalVariable>
                </variables>
            </UnityEngine.Localization.LocalizedString>
        </Bindings>
    </ui:Label>
</ui:UXML>