Skip to content

t1k:playablelabs:base:localize

FieldValue
Modulebase
Version2.29.2
Efforthigh
Tools—

Keywords: language switch playable, locale tables web playable, localize playable, multi-language playable, playable i18n, playable localization, translate playable

/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.

IntentPath
“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

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.

  1. Locate the game’s src/ (--src, else the directory holding main.ts and index.html’s script target).
  2. Confirm the layout has a domain layer free of DOM/engine imports (web-game-layered: src/domain). Without one, put i18n/ where pure modules live and say so in the report.
  3. git status --short: keep localization edits separable from unrelated user changes.
  4. Prior art: run t1k-playablelabs-base-cpm-sweep once. @playablelabs/core-i18n (the studio standard library on CPM) is engine-free but is an async loader-based Localizer with a different shape; it is an option, not a dependency of this skill. @playablelabs/localization is NOT usable on web: its components/ and core/*.ts entry files import the editor engine runtime (confirmed by grep on v0.2.0).
Terminal window
bun <skill>/scripts/scan-text.cjs --src <game>/src --json

Facts 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.

If the game ships a custom font (a `@font-face` rule, a font file, a canvas `font` naming a webfont) AND the target languages include a non-Latin script (`ja ko zh-CN zh-TW ru th ar he hi`), you MUST stop and `AskUserQuestion` before translating. A designed display face carries the glyphs its designer chose, almost always Latin only, so non-Latin text renders as blank boxes or a mismatched fallback. This is invisible in code review and in an English playtest.

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.

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.

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.

  1. registerLocales + setLanguage(detectLanguage()) at the top of boot() in main.ts, before any UI is built.
  2. Convert every sink the scan flagged to t(key, params) per the wiring guide’s judgment calls.
  3. Optional: a language select parameter so the network can pick the locale (references/wiring-guide.md § params).

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).

  • Never write an en table. 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.ts imports nothing; navigator and mainTheOneSdk are read in platform/ only.

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”.

SymptomCause
Text still English at runtimeregisterLocales never called, or called after the UI was built
One label never translatesIts site still assigns a literal, or passes a variable that is not a table key to t()
pt-BR / zh-CN never selectsThe table key differs in case or separator; resolveLanguage normalizes pt_BR but the table name must be pt-BR
{n} shows literallyParam name differs from the token, or the translation renamed/respaced it
ja/ko/zh/ru shows empty boxesThe font lacks the glyphs: Phase 2 gate
A translated string overflows its buttonLength budget ignored; see references/translation-guide.md
Scan finds nothing in a game with visible textWrong --src, or the text is image-baked
Re-scan lists the tables themselvesThey live outside a directory named i18n/ or locales/
Dashboard language param has no effectlanguage is not in playable-config.json definitions, or the dashboard returned null (compiled default wins)

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.