# Localization
The **Localization** package (`com.unity.localization`) makes text, fonts, sprites, audio and prefabs vary by **Locale**. It stores content in **String Tables** and **Asset Tables** (loaded through Addressables), formats text with **Smart Strings** (plurals, variables, conditionals), and binds directly into **UI Toolkit** through data bindings on Unity 6+.
**Target:** Unity **6000.5+**. For Quest builds, VR work in this vault targets **Unity 6.3 LTS (6000.3.27f2+)** ([[0.Choosing a Unity Version]]); Localization 1.5.x supports Unity 6.x (1.5.11 notes "Removed use of GetInstanceId from Unity 6.3+").
> [!warning] Code not compiled
> None of the C# in this series has been compiled or play-tested in Unity. API names were checked against the Localization 1.5 Scripting API pages on 2026-11-10.
> [!note] Verification status
> **Versions (2026-11-10):** the 6000.5 package page lists **1.5.13** as "released for Unity Editor version 6000.5" with 1.5.12 and 1.5.13 available; the package changelog's newest entry is **1.5.14 (2026-11-05)**, which may not yet be reflected on the editor's package page. Use whatever Package Manager offers on your editor (1.5.13 or newer).
> **Verified APIs:** `LocalizedString` (`StringChanged`, `GetLocalizedString`, `GetLocalizedStringAsync`, local variables via `Add`/indexer, `RefreshString`), UI Toolkit `element.SetBinding("text", localizedString)` and UXML `<Bindings>` (Unity 6+), `LocalizationSettings` (`InitializationOperation`, `SelectedLocale`, `SelectedLocaleChanged`, `AvailableLocales`, `StringDatabase`, `StartupLocaleSelectors`), `LocalizeStringEvent` (`StringReference`, `OnUpdateString`, `RefreshString`, `SetEntry`, `SetTable`), `PlayerPrefLocaleSelector`, Plural formatter syntax `{0:plural:...|...}` (CLDR categories), Persistent Variables `{group-name.variable-name}`, `LocalizationEditorSettings.GetStringTableCollections()`. 1.5.12 added dropdown localization (UI Toolkit/UGUI/TMP) and `LocalizedTextCoreFontAsset`.
> **Not verified:** the exact UI Builder menu wording in 6000.5; dropdown-binding API details (mentioned, not coded).
## Parts
| # | Note | Covers |
|---|---|---|
| 1 | [[1. Localization Install Locales and String Tables]] | Install, Localization Settings, locales, string table collections, keys, Addressables |
| 2 | [[2. Localizing UI Toolkit and uGUI Text]] | UXML/UI Builder bindings, `SetBinding`, HUD script with live variables, `LocalizeStringEvent` for uGUI/TMP |
| 3 | [[3. Smart Strings Plurals and Variables]] | Smart format, plurals (CLDR), local and global variables, a global variables updater |
| 4 | [[4. Asset Tables Fonts Icons and Voice]] | Asset tables, localized fonts for CJK, icons vs text (Level Up! HUD), voice lines |
| 5 | [[5. Language Menu Saving and Runtime Scripting]] | Initialization, language dropdown, saved choice, async lookups from code |
| 6 | [[6. Localizing Game Data Dialogue and Pseudo-Localization]] | `LocalizedString` in ScriptableObjects (items, quests, dialogue), pseudo-localization, CSV/Sheets, missing-translation report |
| 7 | [[7. Localization Pitfalls and VR]] | Pitfalls; world-space text and fonts in VR |
## Design lens (Level Up!)
Rogers' HUD and icon chapter (Level 8 in [[Level Up! (Review)]]) argues for clear symbols ("Keep Your Symbols Simple") and context-sensitive prompts. Localization tests that advice brutally: every word on the HUD is a translation, a font and a layout risk. Prefer **icons** for universal concepts (health, ammo, map), **short** labels where words are needed, and design layouts with 30-40% text expansion headroom (German, Finnish) - pseudo-localization (part 6) proves it before translators ever see the strings. Writing (Level 3) and cutscenes (Level 17) become voice/subtitle tables (part 4).
## Patterns used (Game Programming Patterns)
- **Observer** - `StringChanged` / `SelectedLocaleChanged` / UI Toolkit bindings refresh UI when the locale or a variable changes.
- **Service Locator** - `LocalizationSettings` is a global access point to the string and asset databases; wrap it if you want testable code.
- **Flyweight** - one String Table entry (shared key in `SharedTableData`) referenced by every UI element that shows it.
- **Type Object** - items, quests and dialogue lines carry `LocalizedString` fields in ScriptableObjects (part 6).
See [[Game Programming Patterns (Review)]].
## Related (existing)
- [[UI Toolkit and Diegetic UI]] - especially [[3.HUD and Inventory Example]], [[4.Data Binding and Custom Controls]] and [[8.UI Toolkit for VR]]
- [[Inventory Systems]] and [[Quest Systems]] - their ScriptableObject definitions get `LocalizedString` fields in part 6
- [[0.Dialogue System]] and [[TypewriterEffect.cs]] - localized dialogue lines and per-locale typing speed
- [[ScriptableObject Architecture]] - data-driven content
- [[PlayerPrefs Advanced]] and [[High Scores, Saves and Player Stats]] - persisting the chosen language
- [[Input System]] - localized control prompts and rebinding UI
- [[Audio]] - localized voice routed through the mixer
## Sources
- Localization 1.5 manual: https://docs.unity3d.com/Packages/
[email protected]/manual/index.html
- Localization changelog (1.5.14, 2026-11-05): https://docs.unity3d.com/Packages/
[email protected]/changelog/CHANGELOG.html
- Localization package page for 6000.5: https://docs.unity.com/en-us/engine/6000.5/manual/packages-list/packages-all/pack-safe/com-unity-localization
- UI Toolkit (Unity 6+) bindings: https://docs.unity3d.com/Packages/
[email protected]/manual/UIToolkit.html
- `LocalizedString` API: https://docs.unity3d.com/Packages/
[email protected]/api/UnityEngine.Localization.LocalizedString.html
- `LocalizationSettings` API: https://docs.unity3d.com/Packages/
[email protected]/api/UnityEngine.Localization.Settings.LocalizationSettings.html
- Smart Strings: https://docs.unity3d.com/Packages/
[email protected]/manual/Smart/SmartStrings.html
- Startup Locale Selectors: https://docs.unity3d.com/Packages/
[email protected]/manual/LocaleSelector.html
## See also (added 2026-11-10)
- [[Addressables]] — Localization tables are packed and loaded through Addressables