Skip to content

t1k:unity:base:localization

FieldValue
Modulebase
Version5.116.6
Effortmedium
Tools—

Keywords: i18n, localization, translation

/t1k:unity:base:localization

Unity Localization — Multi-Language Support

Section titled “Unity Localization — Multi-Language Support”

Localization package for Unity 6 (com.unity.localization). Full pipeline for strings, assets, and locale management.

  1. Install com.unity.localization via Package Manager
  2. Edit → Project Settings → Localization → Create Localization Settings
  3. Add locales: Locale Generator → select languages → Create
  4. Create string tables: Assets → Create → Localization → String Table Collection
Table: "UI"
├── Key: "menu_start" → EN: "Start Game" | VI: "Bắt đầu" | JP: "ゲーム開始"
├── Key: "menu_options" → EN: "Options" | VI: "Cài đặt" | JP: "オプション"
└── Key: "menu_quit" → EN: "Quit" | VI: "Thoát" | JP: "終了"
Table: "Gameplay"
├── Key: "health_label" → EN: "Health: {0}" | VI: "Máu: {0}"
└── Key: "score_format" → EN: "Score: {0:N0}" | VI: "Điểm: {0:N0}"
  1. Async loading: Strings load asynchronously. Use StringChanged event, not direct access
  2. Missing entries: Falls back to key name. Set fallback locale in settings
  3. Smart String escaping: Use \{ for literal braces
  4. Locale codes: Use ISO 639-1 (en, vi, ja, ko, zh-Hans, zh-Hant)
  5. Preload race: Don’t call AvailableLocales.GetLocale until LocalizationSettings.InitializationOperation has completed
  6. Font coverage: CJK languages need large font atlases — use SDF fonts + fallback chains
  7. RTL: TMPro supports RTL via isRightToLeftText. Test with Arabic/Hebrew early
  8. Bulk conversion scope: Do not auto-localize debug/instruction/placeholder labels just because their text matches a table key; verify the text is user-facing and translated in every target locale, otherwise keep it static or report it for review
  9. Never cache a StringTable object across a locale change. LocalizationSettings releases every table on each switch (OnLocaleChanged reaches LocalizedDatabase.ReleaseAllTables, before SelectedLocaleChanged), so a cached reference becomes a destroyed object and the next read throws. Cache keys and re-resolve, or clear your cache in SelectedLocaleChanged. This class of fault is invisible in the Editor: the AssetDatabase path does not unload on release, so an Editor-only walkthrough passes. Verify in a player build, and see t1k-gamedev-testing-red-proof on choosing a gate that can actually go red.

→ Full C# API, Smart Strings, locale management, asset tables, TMPro integration, import/export: references/api-and-examples.md → First-time enable gotchas (UITemplate Castle.Core fix, consumer asmdef references): references/enable-checklist.md

  • t1k-unity-ui-toolkit — Localized UI elements
  • t1k-unity-audio-core — Localized voice/sound assets
  • t1k-unity-base-addressables — Remote locale loading
FileContents
api-and-examples.md (references/api-and-examples.md)C# API, Smart Strings, locale mgmt, asset tables, TMPro, import/export, gotchas
enable-checklist.md (references/enable-checklist.md)First-time enable: TMPLocalization Castle.Core fix, consumer asmdef references for UITemplate.AutoLocalize + Unity.Localization