t1k:unity:base:localize
| Field | Value |
|---|---|
| Module | base |
| Version | 5.116.6 |
| Effort | medium |
| 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
How to invoke
Section titled “How to invoke”/t1k:unity:base:localizeUnity 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 int1k:unity:base:localization; the UITemplate auto-localize layer lives int1k:unity:tof:localization. Read this for the process, those for the calls. Text conversion itself ist1k:translate— never hand-translate in this skill.
When to use
Section titled “When to use”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.
The seven phases
Section titled “The seven phases”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.
| # | Phase | Output | Check |
|---|---|---|---|
| 1 | Audit | every hardcoded player-visible string, with file:line | scripts/scan-hardcoded-strings.cjs |
| 2 | Decide languages | a tiered target list with the font cost named | language-tiering.md (references/language-tiering.md) |
| 3 | Author keys | a Game string table (CSV round trip) | key-authoring.md (references/key-authoring.md) |
| 4 | Translate | filled locale columns | t1k:translate --mode ui |
| 5 | Wire | LocalizeStringEvent / API calls + a language selector | t1k:unity:base:localization |
| 6 | FONT GATE | proof every glyph of every string exists | scripts/check-glyph-coverage.cjs |
| 7 | Verify | per-locale parity + a capture per language | scripts/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).
Phase 6 — the font hard gate
Section titled “Phase 6 — the font hard gate”This is a HARD-GATE. Do not report the localisation done with it failing.
bun scripts/check-glyph-coverage.cjs --fonts Assets/Fonts --csv Assets/Localization/Game.csvExit 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:
| Surface | Keyable? |
|---|---|
C# string literal reaching a TMP label (direct or likely) | yes — replace with a LocalizedString |
TMP m_text: authored in prefab/scene YAML | yes — wire a LocalizeStringEvent |
| Words baked into a sprite/PNG | no — 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.cjsgates both, per key, per locale.
Scripts
Section titled “Scripts”| Script | Phase | Exit codes |
|---|---|---|
scripts/scan-hardcoded-strings.cjs | 1 | 0 scan ok · 1 scan failed · 2 usage error |
scripts/check-glyph-coverage.cjs | 6 | 0 pass · 1 check failed · 2 usage error · 3 gate failed |
scripts/check-locale-parity.cjs | 7 | 0 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.
Executed by
Section titled “Executed by”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.
| Step | Agent |
|---|---|
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_AtlasPopulationMode | t1k-fact-fetcher |
Phase 7 — run scripts/check-locale-parity.cjs, report per-key/per-locale gaps | t1k-fact-fetcher |
| Phase 2 — pick the locale tiers and accept the font cost | reasoning tier — judgment, not a label |
| Phase 3 — author keys, resolve placeholder sets, route baked-sprite text to art | reasoning tier — judgment, not a label |
Phase 4/5 — drive t1k:translate --mode ui and wire LocalizeStringEvent | t1k-unity-base-developer |
Read a phase-6 3 and decide fix-in-font vs drop-the-locale | reasoning tier — judgment, not a label |
Hard rules
Section titled “Hard rules”The eight that cost the most time, with the fix for each:
hard-rules.md (references/hard-rules.md). The short version:
- Baked-sprite text — audit-only; needs art, no key reaches it.
- Static font atlases silently never populate — the phase-6 gate exists for this.
- RTL (Arabic/Hebrew) — needs a font asset and layout mirroring; budget it.
- Pluralisation is not string substitution — use Smart String plural/gender rules.
- App name is per-platform, outside the string table: Android
values-<lang>/strings.xml, iOSInfoPlist.strings. - Store listing copy is not this workflow — that is the store skills.
- Mixed typefaces from a fallback chain are visible and read as a bug.
- Debug/instruction labels are often not user-facing — do not key them blindly.
Related
Section titled “Related”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.