t1k:playablelabs:base:localize
| Field | Value |
|---|---|
| Module | base |
| Version | 2.29.2 |
| Effort | high |
| Tools | — |
Keywords: language switch playable, locale tables web playable, localize playable, multi-language playable, playable i18n, playable localization, translate playable
How to invoke
Section titled “How to invoke”/t1k:playablelabs:base:localize[--langs es,pt-BR,ja] [--src <game src dir>] [--scan-only] [--json]playablelabs localize: multi-language for web / none-host playables
Section titled “playablelabs localize: multi-language for web / none-host playables”Turn an English-only web or none-host playable (the web-game-layered layout) into a multi-language one:
scan, translate, generate tables, wire t(), verify. Provenance: ported from theonekit-cocos
t1k-cocos-playable-localize v4.8.4 (translation guide, key convention, merge rule, font gate and subsetting recipe
carried over; the scanner and runtime are new for web). Nothing here depends on an engine package: the runtime is
~60 lines of plain TypeScript you copy into the game.
Out of scope: games on the editor-based engine host (their localization is the engine kit’s own flow, see t1k-playablelabs-base-engine-hosts), words baked
into images, right-to-left layout, per-language sprites.
Decision tree
Section titled “Decision tree”| Intent | Path |
|---|---|
| “Localize this game” / “add multi-language” | Full run, Phases 0-6 |
| “What text does this game have?” | --scan-only: stop after Phase 1 |
| “Add one more language later” | Re-run; Phase 4 merges into existing tables, never overwrites |
| “Text still shows English” | Gotchas |
| “Can the dashboard set the language / text?” | references/wiring-guide.md § params |
Default languages
Section titled “Default languages”es, pt-BR, fr, de, ja, ko, zh-CN, ru, id, vi. Override with --langs. English is never a table: it is the text
already in the code.
Workflow
Section titled “Workflow”Phase 0: preflight
Section titled “Phase 0: preflight”- Locate the game’s
src/(--src, else the directory holdingmain.tsandindex.html’s script target). - Confirm the layout has a domain layer free of DOM/engine imports (
web-game-layered:src/domain). Without one, puti18n/where pure modules live and say so in the report. git status --short: keep localization edits separable from unrelated user changes.- Prior art: run
t1k-playablelabs-base-cpm-sweeponce.@playablelabs/core-i18n(the studio standard library on CPM) is engine-free but is an async loader-basedLocalizerwith a different shape; it is an option, not a dependency of this skill.@playablelabs/localizationis NOT usable on web: itscomponents/andcore/*.tsentry files import the editor engine runtime (confirmed by grep on v0.2.0).
Phase 1: scan
Section titled “Phase 1: scan”bun <skill>/scripts/scan-text.cjs --src <game>/src --jsonFacts only: unique strings (html, html attributes, code literals, ternary branches, config defaults, json), the DOM
sink assignments still to convert, what it skipped and why. Read references/scan-report-guide.md before acting on
a field. Never hand-roll this scan; run it again in Phase 6.
The scan cannot read words baked into PNG/JPG pixels. Open the real page and look at the title, CTA, win/lose and logo art; baked copy needs a Label-style replacement or a per-locale image system before the game counts as localized.
Phase 2: font gate (HARD GATE)
Section titled “Phase 2: font gate (HARD GATE)”Offer: per-language font stacks (keep the designed face where it works, swap only for scripts it cannot draw) · a subset font covering every shipped language · drop the non-Latin languages · proceed anyway, explicitly accepting the fallback look. State the visual cost of each option before asking: a font covering CJK is never a display face. No override flag skips this gate. A game on the platform system font stack has no custom font and passes the gate.
Subsetting recipe when a covering font is needed: include the scanned strings plus printable ASCII, then subset an
official TrueType source instead of renaming a CFF/OTF file. For Noto CJK, instantiate NotoSansCJKsc-VF.ttf at
wght=400 with fontTools.varLib.instancer, then subset it with fontTools.subset and --no-hinting. Keep the SIL OFL
license beside the project notices. Never ship an OS font: Windows and macOS faces are not redistributable.
Re-verify the written output, not the in-memory object: reopen it with TTFont, require glyf + loca, and compare
its cmap against every locale value and printable ASCII. A typical playable subset is roughly 50-150KB depending on copy;
it counts against the network size ceiling (t1k-playablelabs-base-networks), so measure the packed page afterwards.
Phase 3: translate
Section titled “Phase 3: translate”Translate the scanned strings per references/translation-guide.md: keep length within the source’s budget (buttons do
not reflow), preserve {placeholder} tokens exactly, match the game’s register, never translate brand names.
Phase 4: generate locale tables
Section titled “Phase 4: generate locale tables”Copy templates/i18n.ts to src/domain/i18n/i18n.ts and templates/language.ts to src/platform/language.ts. Write
src/domain/i18n/locales/<lang>.ts plus a barrel, using the source English string as the key. Merge with any existing
table: never drop a key a human edited. Shape and examples: references/wiring-guide.md.
Phase 5: wire the code
Section titled “Phase 5: wire the code”registerLocales+setLanguage(detectLanguage())at the top ofboot()inmain.ts, before any UI is built.- Convert every sink the scan flagged to
t(key, params)per the wiring guide’s judgment calls. - Optional: a
languageselect parameter so the network can pick the locale (references/wiring-guide.md§ params).
Phase 6: verify and report
Section titled “Phase 6: verify and report”bun test <skill>/scripts (scanner and template), re-run scan-text.cjs (remaining strings must be deliberate),
bun run typecheck (TSRS), then run the built page with ?lang=<tag> for each language through gameplay and both end cards.
Report per language: strings translated, keys skipped, placeholder mismatches, baked-text images, font risk, files
changed, and anything left for a human. Then the normal pack and smoke (t1k-playablelabs-base-pack).
Hard rules
Section titled “Hard rules”- Never write an
entable. An unknown key resolves to itself, which is the authored English. - Never translate numbers, percentages,
{placeholder}tokens, asset paths, or brand/product names. - Never ship blank table values. A blank falls back to the key at runtime, but it is a defect to fix.
- Keys are verbatim. Lookup is exact; copy the source string byte for byte.
- Re-runs merge. Existing translated values win over freshly generated ones unless the source English string changed.
- Domain stays pure.
i18n.tsimports nothing;navigatorandmainTheOneSdkare read inplatform/only.
Executed by
Section titled “Executed by”Running scripts/scan-text.cjs and reading its report is mechanical, so a cheap-tier agent may do it. Translation, the font gate and wiring judgment stay with the main session or a native agent. Routing SSOT: rules/orchestration-rules.md § “Task-Type → Agent Routing”.
Hard rules
Section titled “Hard rules”| Symptom | Cause |
|---|---|
| Text still English at runtime | registerLocales never called, or called after the UI was built |
| One label never translates | Its site still assigns a literal, or passes a variable that is not a table key to t() |
pt-BR / zh-CN never selects | The table key differs in case or separator; resolveLanguage normalizes pt_BR but the table name must be pt-BR |
{n} shows literally | Param name differs from the token, or the translation renamed/respaced it |
| ja/ko/zh/ru shows empty boxes | The font lacks the glyphs: Phase 2 gate |
| A translated string overflows its button | Length budget ignored; see references/translation-guide.md |
| Scan finds nothing in a game with visible text | Wrong --src, or the text is image-baked |
| Re-scan lists the tables themselves | They live outside a directory named i18n/ or locales/ |
| Dashboard language param has no effect | language is not in playable-config.json definitions, or the dashboard returned null (compiled default wins) |
Related
Section titled “Related”t1k-playablelabs-base-params (how parameter values reach a packed page), t1k-playablelabs-base-pack,
t1k-playablelabs-base-playthrough (default-language parity only), t1k-playablelabs-base-cpm-sweep.