Luna UI Documentation

Unity's localization package is integrated with UI Toolkit.

Luna UI provides demos, guidelines, and utility functions for using Unity's Localization package.

Guide

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:

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

Adding a binding through the UI Builder.

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

Add binding window type popup showing localization binding types.

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.

Warning: 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.

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

xml

<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>

Luna UI Runtime Style Switching

Luna UI provides LocalizationViewStyleSwitcher component that enables runtime font and style switching based on the active locale. This works around Unity's limitation of not being able to change global USS variables at runtime by applying locale-specific USS classes to all UIViews.

Setup

Add the LocalizationViewStyleSwitcher component to a GameObject in your scene (typically on the same GameObject as your LunaUIManager).

Configuration

Locale Class Prefix

The _localeClassPrefix field determines the prefix used for locale-specific USS classes. The default value is "locale-". The component automatically generates class names based on the active locale. For example, with the default prefix, it generates classes like locale-en, locale-zh-cn, and locale-ja.

How It Works

When the locale changes, LocalizationViewStyleSwitcher:

Removes the previous locale class from all UIViews using LunaUIManager.RemoveClassFromAllUIViews()
Adds the new locale class to all UIViews using LunaUIManager.AddClassToAllUIViews()

The component automatically subscribes to LocalizationSettings.SelectedLocaleChanged and applies the appropriate locale class whenever the locale changes.

USS Class Structure

Create locale-specific styles in your USS files using the generated class names. You can override USS custom properties (CSS variables) for locale-specific fonts.

In the Localization Sample, LocalizationViewStyleSwitcher is implemented only for Japanese locale—switching to Japanese changes the font. Example:

css

/* Japanese locale - uses custom font */
.locale-ja {
  --font-black: url("../Fonts/DelaGothicOne-RegularSDF.asset");
  --font-black-italic: url("../Fonts/DelaGothicOne-RegularSDF.asset");
  --font-bold: url("../Fonts/DelaGothicOne-RegularSDF.asset");
  --font-bold-italic: url("../Fonts/DelaGothicOne-RegularSDF.asset");
  --font-light: url("../Fonts/DelaGothicOne-RegularSDF.asset");
  --font-light-italic: url("../Fonts/DelaGothicOne-RegularSDF.asset");
  --font-medium: url("../Fonts/DelaGothicOne-RegularSDF.asset");
  --font-medium-italic: url("../Fonts/DelaGothicOne-RegularSDF.asset");
}

You can add similar styles for other locales (e.g., .locale-en, .locale-zh-cn) as needed.

For more details, see the Localization Sample and Global UIView Registry.

AutoSizeText with Localization

Auto-sizing text is particularly useful for localization, as different languages have varying text lengths. The Localization Sample includes an AutoSizeText example demonstrating how text automatically adjusts font size when changing locales. See Auto Size Text for detailed information on auto-sizing text in UI Toolkit.