Localization

Unity's localization package is integrated with UI Toolkit.

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

For a working end-to-end reference, use the Showcase sample's LocalizationDemo — Samples~/Showcase/Components/LocalizationDemo/ and its LocalizationDemo.unity scene wire LocalizationViewStyleSwitcher together with localization data, fonts, and locale styles. The GameFull sample ships the localization data (Samples~/GameFull/Setup/Localization/) and fonts (Samples~/GameFull/Fonts/) only; it does not wire LocalizationViewStyleSwitcher in any scene or prefab.

Unity Localization: UI Toolkit

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:

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

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

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.

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:

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:

1. Removes the previous locale class from all UIViews using LunaUIManager.RemoveClassFromAllUIViews()
2. 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.

The shipped .locale-ja block lives in the Essentials theme's LocalizedStyles.uss (a copy also ships with the Showcase LocalizationDemo, under its Setup/ folder). Only the Japanese locale is covered — switching to Japanese swaps in a glyph-capable SDF font via the .locale-ja class. The snippet below is an illustrative pattern for your own theme copy — adjust the url() depth to wherever your USS file sits relative to the fonts (the Essentials theme copy uses ../../Fonts/…; the Showcase copy uses ../Fonts/…):

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

For more details, see Global UIView Registry.

AutoSizeText with Localization

Auto-sizing text is particularly useful for localization, as different languages have varying text lengths. See Auto Size Text for detailed information on auto-sizing text in UI Toolkit.