tinyworld-i18n

name	tinyworld-i18n
description	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 — Codex does the translating directly, using the established glossary for consistency.

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 (Codex) 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)

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

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

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

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

5. npm run i18n:check until it passes (it also runs inside npm run check / publish.sh, so a gap blocks the build).

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

1. cp engine/i18n/en.js engine/i18n/de.js, change g.en → g.de, translate all values.
2. Add 'de' to SUPPORTED and a de: endonym to NAMES in engine/i18n/i18n-core.js.
3. 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).
4. Add a <option value="de">Deutsch</option> to #ui-lang-mode in the Workspace settings panel.
5. Add 'de' to the LOCALES array in tools/i18n-check.js.
6. npm run i18n:check, then verify with ?lang=de.