TinyWorld i18n workflow
TinyWorld localizes its gameplay UI into English (en), French (fr), Simplified
Chinese (zh), and Spanish (es). This skill is the repeatable process for keeping
those translations complete and consistent. There is no external API: you (Claude) are
the translator. The checker (npm run i18n:check) is the safety net.
Read docs/i18n.md first if you need the architecture. The short version:
- Locale dictionaries live in
engine/i18n/{en,fr,es,zh}.js as flat key→string maps.
en.js is authoritative. Every other locale must define exactly its key set.- Static HTML uses
data-i18n / data-i18n-title / data-i18n-tooltip /
data-i18n-placeholder / data-i18n-aria-label attributes.
- JS uses the global
t('key') (or tx('key', fallback) to keep a hard-coded English
default). Tool/group/variant labels are localized by a single mutation block near the
top of engine/world/19-tools-toolbar.js.
- Language switching is reload-on-switch (persist +
location.reload()), so every
surface re-renders correctly at boot. Don't add live re-render wiring.
Adding or changing strings (the loop)
Add the English string to engine/i18n/en.js with a namespaced key
(panel.thing, e.g. time.season). Keep keys grouped under their existing comment
section; add a new section if it's a new surface.
Reference it:
- Static HTML leaf element → add
data-i18n="key". For an element that also has
child elements (e.g. a <label> wrapping a <select>), wrap just the text in a
<span data-i18n="key">…</span> so apply() doesn't wipe the children.
- Attribute →
data-i18n-title / -tooltip / -placeholder / -aria-label. Leave
the existing attribute as the English default; apply() overwrites it.
- JS string shown to the user →
window.t('key'). Use window.t (not bare t)
inside functions that have a local variable named t (the toolbar module does).
- A label living in a data array (tools, menus) → localize once via a mutation block
guarded by
if (window.TWI18N), using tx('prefix.' + item.id, item.label).
See what's missing: npm run i18n:report. It prints per-locale coverage and any
used key that's absent from en.js (a typo).
Translate the missing keys into fr.js, es.js, zh.js. Do it yourself. Follow
the Glossary and Style below. Match en.js key-for-key — no extra keys, no
blanks. Preserve {name} interpolation placeholders verbatim.
npm run i18n:check until it passes (it also runs inside npm run check /
publish.sh, so a gap blocks the build).
Verify in the real app — never claim done from files alone:
npm run dev, then load ?lang=fr, ?lang=zh, ?lang=es. Confirm the new strings
render translated and the layout still fits (German-length / CJK glyph checks).
Scope — what gets translated
Translate: toolbar/tools/variants, world menu, camera/view, time & weather, crowd
panel, sound, layers/properties, welcome/how-to, top-bar + control tooltips, settings
tab names + the Workspace section, the mode HUD, the radial menu, player-facing toasts.
Leave in English: account/auth, the AI/agent panel, API keys, the developer overlay,
credits/sponsors, the token ticker, and the dense technical settings sliders (Rendering /
Materials / Environment / Crowd-advanced / AI). These are not "gameplay" strings. If the
product owner later wants them, add their keys to en.js and run this loop.
Style
- Match the source's tone: short, friendly, lowercase hints (
clear to grass).
- Keep it terse — UI chrome, not prose. Prefer the shortest natural phrasing.
- Use the locale's own conventions (FR:
« » guillemets are fine; ZH: full-width
punctuation 。，；（）; ES: inverted ¿¡ where applicable).
- Don't translate the brand name "Tiny World Builder",
$TINYWORLD, or proper UI keys.
- Keyboard hints: localize the verb, keep the key name (
Échap, Esc).
Glossary (keep these consistent across new strings)
| English |
fr |
es |
zh |
| world (the build) |
monde |
mundo |
世界 |
| grid / board |
grille / plateau |
cuadrícula / tablero |
网格 / 面板 |
| Grass |
Herbe |
Hierba |
草地 |
| Path |
Chemin |
Camino |
小路 |
| Water |
Eau |
Agua |
水 |
| House |
Maison |
Casa |
房屋 |
| Island |
Île |
Isla |
岛屿 |
| Fence |
Clôture |
Valla |
栅栏 |
| Bridge |
Pont |
Puente |
桥 |
| Crowd |
Foule |
Multitud |
人群 |
| Layers / Properties |
Calques / Propriétés |
Capas / Propiedades |
图层 / 属性 |
| Settings |
Réglages |
Ajustes |
设置 |
| Showcase mode |
Mode présentation |
Modo exhibición |
展示模式 |
| Reset |
Réinitialiser |
Reiniciar |
重置 |
| Clear |
Effacer / remettre en herbe |
Vaciar |
清空 |
| Select / Move |
Sélection / Déplacer |
Seleccionar / Mover |
选择 / 移动 |
Adding a new language (e.g. German de)
cp engine/i18n/en.js engine/i18n/de.js, change g.en → g.de, translate all values.- Add
'de' to SUPPORTED and a de: endonym to NAMES in engine/i18n/i18n-core.js.
- Add
<script src="engine/i18n/de.js"></script> before i18n-core.js in
tiny-world-builder.html (the i18n block, right after vendor/tinyworld-auth.js).
- Add a
<option value="de">Deutsch</option> to #ui-lang-mode in the Workspace
settings panel.
- Add
'de' to the LOCALES array in tools/i18n-check.js.
npm run i18n:check, then verify with ?lang=de.
1---2name: tinyworld-i18n-23description: Add, translate, or audit TinyWorld UI strings across English/French/Chinese/Spanish. Use when adding user-facing gameplay text, when `npm run i18n:check` fails, when a string shows up in English in a non-English locale, or when adding a new language. No translation API — Claude does the translating directly, using the established glossary for consistency.4---56# TinyWorld i18n workflow78TinyWorld localizes its **gameplay** UI into English (`en`), French (`fr`), Simplified9Chinese (`zh`), and Spanish (`es`). This skill is the repeatable process for keeping10those translations complete and consistent. There is no external API: you (Claude) are11the translator. The checker (`npm run i18n:check`) is the safety net.1213Read `docs/i18n.md` first if you need the architecture. The short version:1415- Locale dictionaries live in `engine/i18n/{en,fr,es,zh}.js` as flat key→string maps.16- **`en.js` is authoritative.** Every other locale must define exactly its key set.17- Static HTML uses `data-i18n` / `data-i18n-title` / `data-i18n-tooltip` /18 `data-i18n-placeholder` / `data-i18n-aria-label` attributes.19- JS uses the global `t('key')` (or `tx('key', fallback)` to keep a hard-coded English20 default). Tool/group/variant labels are localized by a single mutation block near the21 top of `engine/world/19-tools-toolbar.js`.22- Language switching is **reload-on-switch** (persist + `location.reload()`), so every23 surface re-renders correctly at boot. Don't add live re-render wiring.2425## Adding or changing strings (the loop)26271. **Add the English string to `engine/i18n/en.js`** with a namespaced key28 (`panel.thing`, e.g. `time.season`). Keep keys grouped under their existing comment29 section; add a new section if it's a new surface.30312. **Reference it:**32 - Static HTML leaf element → add `data-i18n="key"`. For an element that also has33 child elements (e.g. a `<label>` wrapping a `<select>`), wrap just the text in a34 `<span data-i18n="key">…</span>` so `apply()` doesn't wipe the children.35 - Attribute → `data-i18n-title` / `-tooltip` / `-placeholder` / `-aria-label`. Leave36 the existing attribute as the English default; `apply()` overwrites it.37 - JS string shown to the user → `window.t('key')`. Use `window.t` (not bare `t`)38 inside functions that have a local variable named `t` (the toolbar module does).39 - A label living in a data array (tools, menus) → localize once via a mutation block40 guarded by `if (window.TWI18N)`, using `tx('prefix.' + item.id, item.label)`.41423. **See what's missing:** `npm run i18n:report`. It prints per-locale coverage and any43 used key that's absent from `en.js` (a typo).44454. **Translate the missing keys** into `fr.js`, `es.js`, `zh.js`. Do it yourself. Follow46 the **Glossary** and **Style** below. Match `en.js` key-for-key — no extra keys, no47 blanks. Preserve `{name}` interpolation placeholders verbatim.48495. **`npm run i18n:check`** until it passes (it also runs inside `npm run check` /50 `publish.sh`, so a gap blocks the build).51526. **Verify in the real app** — never claim done from files alone:53 `npm run dev`, then load `?lang=fr`, `?lang=zh`, `?lang=es`. Confirm the new strings54 render translated and the layout still fits (German-length / CJK glyph checks).5556## Scope — what gets translated5758**Translate:** toolbar/tools/variants, world menu, camera/view, time & weather, crowd59panel, sound, layers/properties, welcome/how-to, top-bar + control tooltips, settings60tab names + the Workspace section, the mode HUD, the radial menu, player-facing toasts.6162**Leave in English:** account/auth, the AI/agent panel, API keys, the developer overlay,63credits/sponsors, the token ticker, and the dense technical settings sliders (Rendering /64Materials / Environment / Crowd-advanced / AI). These are not "gameplay" strings. If the65product owner later wants them, add their keys to `en.js` and run this loop.6667## Style6869- Match the source's tone: short, friendly, lowercase hints (`clear to grass`).70- Keep it terse — UI chrome, not prose. Prefer the shortest natural phrasing.71- Use the locale's own conventions (FR: `« »` guillemets are fine; ZH: full-width72 punctuation 。，；（）; ES: inverted ¿¡ where applicable).73- Don't translate the brand name "Tiny World Builder", `$TINYWORLD`, or proper UI keys.74- Keyboard hints: localize the verb, keep the key name (`Échap`, `Esc`).7576## Glossary (keep these consistent across new strings)7778| English | fr | es | zh |79|---|---|---|---|80| world (the build) | monde | mundo | 世界 |81| grid / board | grille / plateau | cuadrícula / tablero | 网格 / 面板 |82| Grass | Herbe | Hierba | 草地 |83| Path | Chemin | Camino | 小路 |84| Water | Eau | Agua | 水 |85| House | Maison | Casa | 房屋 |86| Island | Île | Isla | 岛屿 |87| Fence | Clôture | Valla | 栅栏 |88| Bridge | Pont | Puente | 桥 |89| Crowd | Foule | Multitud | 人群 |90| Layers / Properties | Calques / Propriétés | Capas / Propiedades | 图层 / 属性 |91| Settings | Réglages | Ajustes | 设置 |92| Showcase mode | Mode présentation | Modo exhibición | 展示模式 |93| Reset | Réinitialiser | Reiniciar | 重置 |94| Clear | Effacer / remettre en herbe | Vaciar | 清空 |95| Select / Move | Sélection / Déplacer | Seleccionar / Mover | 选择 / 移动 |9697## Adding a new language (e.g. German `de`)98991. `cp engine/i18n/en.js engine/i18n/de.js`, change `g.en` → `g.de`, translate all values.1002. Add `'de'` to `SUPPORTED` and a `de:` endonym to `NAMES` in `engine/i18n/i18n-core.js`.1013. Add `<script src="engine/i18n/de.js"></script>` before `i18n-core.js` in102 `tiny-world-builder.html` (the i18n block, right after `vendor/tinyworld-auth.js`).1034. Add a `<option value="de">Deutsch</option>` to `#ui-lang-mode` in the Workspace104 settings panel.1055. Add `'de'` to the `LOCALES` array in `tools/i18n-check.js`.1066. `npm run i18n:check`, then verify with `?lang=de`.
jasonkneen