Skip to content

t1k:unity:base:localize

FieldValue
Modulebase
Version5.116.6
Effortmedium
Tools—

Keywords: font fallback chain, glyph coverage, hardcoded strings, language support workflow, localisation workflow, localise the game, localize the game, missing glyph, string table audit, translation keys

/t1k:unity:base:localize

Unity Localisation Workflow — Audit → Ship

Section titled “Unity Localisation Workflow — Audit → Ship”

Workflow, not API reference. This skill drives a Unity game from “all copy is hardcoded in English” to “three locales ship, verified”. The package API (LocalizedString, LocalizeStringEvent, tables, Smart Strings, StringChanged) lives in t1k:unity:base:localization; the UITemplate auto-localize layer lives in t1k:unity:tof:localization. Read this for the process, those for the calls. Text conversion itself is t1k:translate — never hand-translate in this skill.

A request to localise/add languages to a Unity game, find hardcoded strings, author translation keys, or explain why a locale renders blank boxes. For an API question (“how do I subscribe to a locale change?”) use t1k:unity:base:localization.

Each phase has a script or a check. Do not skip phase 6 — a missing glyph is the one defect in this entire workflow that ships silently to a player.

#PhaseOutputCheck
1Auditevery hardcoded player-visible string, with file:linescripts/scan-hardcoded-strings.cjs
2Decide languagesa tiered target list with the font cost namedlanguage-tiering.md (references/language-tiering.md)
3Author keysa Game string table (CSV round trip)key-authoring.md (references/key-authoring.md)
4Translatefilled locale columnst1k:translate --mode ui
5WireLocalizeStringEvent / API calls + a language selectort1k:unity:base:localization
6FONT GATEproof every glyph of every string existsscripts/check-glyph-coverage.cjs
7Verifyper-locale parity + a capture per languagescripts/check-locale-parity.cjs

Detail per phase: audit.md (references/audit.md) · translation.md (references/translation.md) · wiring.md (references/wiring.md) · verification.md (references/verification.md) · hard-rules.md (references/hard-rules.md).

This is a HARD-GATE. Do not report the localisation done with it failing.

Terminal window
bun scripts/check-glyph-coverage.cjs --fonts Assets/Fonts --csv Assets/Localization/Game.csv

Exit 3 means at least one language would render blank boxes on a device. The report names the missing codepoints and the key each came from. What makes the gate non-negotiable is the population mode the report also prints:

  • m_AtlasPopulationMode: 0 (Static) — TMP never adds a glyph at runtime. The text stays broken forever. This is the common case for shipped projects.
  • m_AtlasPopulationMode: 1 (Dynamic) — TMP may add the glyph at runtime, but only if it can read the source font file on the target platform. A stripped source is still blank. Always confirm on a device in the locale.

Do not hand-wave “TMP will fix it”. Read the mode out of the report. Full reasoning, the 0xFFFE sentinel and the fallback-chain rules: font-gate.md (references/font-gate.md).

Phase 1 — what the audit finds, and what it cannot

Section titled “Phase 1 — what the audit finds, and what it cannot”

The scanner reports three surfaces, and they are not equally fixable:

SurfaceKeyable?
C# string literal reaching a TMP label (direct or likely)yes — replace with a LocalizedString
TMP m_text: authored in prefab/scene YAMLyes — wire a LocalizeStringEvent
Words baked into a sprite/PNGno — pixels. Route to art. Cannot be keyed.

Baked text is reported as bakedTextSuspects and never silently dropped, because the alternative is a localised build that still shows an English logo. Details and the likely-vs-direct confidence split: audit.md (references/audit.md).

Phase 3/7 — authoring rules that the gate enforces

Section titled “Phase 3/7 — authoring rules that the gate enforces”
  • Key naming: <screen>.<element> (settings.title, win.get_reward), stable, never the English text as the key.
  • Placeholders are Smart Strings: {count}. Never concatenate sentences — a fragment-to-fragment join cannot be reordered by a language that needs to (“3 wins” vs “thắng 3 trận”).
  • Every key must exist in every enabled locale, with an identical placeholder set. scripts/check-locale-parity.cjs gates both, per key, per locale.
ScriptPhaseExit codes
scripts/scan-hardcoded-strings.cjs10 scan ok · 1 scan failed · 2 usage error
scripts/check-glyph-coverage.cjs60 pass · 1 check failed · 2 usage error · 3 gate failed
scripts/check-locale-parity.cjs70 pass · 1 check failed · 2 usage error · 3 gate failed

Both gates use 3 so a caller can tell “you called it wrong” (2) from “this is not shippable” (3). Findings are data: the audit scan exits 0 even when it finds hardcoded strings.

The three scripts are deterministic: a cheap-tier agent runs them and reports the findings verbatim. Everything that decides what the project should be stays on the reasoning tier.

StepAgent
Phase 1 — run scripts/scan-hardcoded-strings.cjs, return the JSON (strings, file:line, bakedTextSuspects)t1k-fact-fetcher
Phase 6 — run scripts/check-glyph-coverage.cjs, report the exit code and m_AtlasPopulationModet1k-fact-fetcher
Phase 7 — run scripts/check-locale-parity.cjs, report per-key/per-locale gapst1k-fact-fetcher
Phase 2 — pick the locale tiers and accept the font costreasoning tier — judgment, not a label
Phase 3 — author keys, resolve placeholder sets, route baked-sprite text to artreasoning tier — judgment, not a label
Phase 4/5 — drive t1k:translate --mode ui and wire LocalizeStringEventt1k-unity-base-developer
Read a phase-6 3 and decide fix-in-font vs drop-the-localereasoning tier — judgment, not a label

The eight that cost the most time, with the fix for each: hard-rules.md (references/hard-rules.md). The short version:

  1. Baked-sprite text — audit-only; needs art, no key reaches it.
  2. Static font atlases silently never populate — the phase-6 gate exists for this.
  3. RTL (Arabic/Hebrew) — needs a font asset and layout mirroring; budget it.
  4. Pluralisation is not string substitution — use Smart String plural/gender rules.
  5. App name is per-platform, outside the string table: Android values-<lang>/strings.xml, iOS InfoPlist.strings.
  6. Store listing copy is not this workflow — that is the store skills.
  7. Mixed typefaces from a fallback chain are visible and read as a bug.
  8. Debug/instruction labels are often not user-facing — do not key them blindly.
  • t1k:unity:base:localization — the package API this workflow drives.
  • t1k:unity:tof:localization — UITemplate auto-localize layer.
  • t1k:translate — the actual text conversion (--mode ui).
  • t1k:unity:base:text-config — TMP font assets, atlases and text configuration.