From 43370292e309350bbd08ca05143e5bdc0d0d580c Mon Sep 17 00:00:00 2001 From: BenStullsBets Date: Mon, 29 Jun 2026 18:38:05 -0700 Subject: [PATCH] docs(i18n): localization + language-dropdown design spec MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Design for a language dropdown localizing the simulator UI controls and the Left/Right brain annotations. This pass: en/es/fr/ja (Hebrew + Chinese deferred — no RTL work in scope). English default, session-only (no persistence), English fallback on missing keys. Annotations extend the existing per-clip strings dict (no schema change); ~2,260 strings authored via a one-shot idempotent translate_manifest tool. Co-Authored-By: Claude Opus 4.8 (1M context) --- ...9-localization-language-dropdown-design.md | 125 ++++++++++++++++++ 1 file changed, 125 insertions(+) create mode 100644 docs/superpowers/specs/2026-06-29-localization-language-dropdown-design.md diff --git a/docs/superpowers/specs/2026-06-29-localization-language-dropdown-design.md b/docs/superpowers/specs/2026-06-29-localization-language-dropdown-design.md new file mode 100644 index 0000000..11041cb --- /dev/null +++ b/docs/superpowers/specs/2026-06-29-localization-language-dropdown-design.md @@ -0,0 +1,125 @@ +# Localization & Language Dropdown — Design + +**Date:** 2026-06-29 +**Status:** Approved design, pre-plan +**Scope:** The `simulator/` web experience — localize all UI controls and the +Left/Right brain annotations, selectable via a language dropdown. + +--- + +## 1. Goal + +Let a visitor switch the experience's language from a dropdown. Switching +re-renders **both** the UI chrome (controls, labels, hints) **and** the +Left/Right brain annotation content (object labels, facts, emotion words) into +the chosen language, live, without reloading the page or interrupting playback. + +## 2. Languages (this pass) + +Four languages, English as the source/default: + +| code | native name | notes | +|------|-------------|-------| +| `en` | English | source of truth, fallback | +| `es` | Español | | +| `fr` | Français | | +| `ja` | 日本語 | CJK glyphs; no layout-direction change | + +Hebrew and Chinese were considered and **deliberately deferred** to a later +pass. Hebrew was the only right-to-left language, so **no RTL / UI-mirror work +is in scope here.** The language set is data-driven, so adding more later +(including an RTL pass) is additive. + +## 3. What needs translating — two very different costs + +1. **UI chrome** — ~20 fixed control strings (`Loading Universe`, `Output`, + `Video`, `Audio`, `Altitude`, `Think`, `Feel`, `Mood`, the six scale names, + hints, dev-mode labels). Small, static. +2. **Annotations** — the bulk. The manifest holds **41 clips / 753 authored + English string-variants** (Left labels + facts + Right emotions, many as + tier-lists). Authoring `es/fr/ja` = **753 × 3 ≈ 2,260 strings**. This is + *content*, and it is the dominant effort. + +## 4. Architecture — three isolated pieces + +### 4.1 Language registry +A single small module (`simulator/static/i18n.js` or a sibling) exporting the +ordered list `[{code, nativeName}]` for `en, es, fr, ja`. It is the **one source +of truth** consumed by the dropdown and ``. No `dir` field needed +this pass (no RTL). + +### 4.2 UI string catalog +A `{ key: {en, es, fr, ja} }` map for the ~20 control strings, living alongside +the registry. `index.html`'s static text is tagged with `data-i18n="key"` +attributes (removing hardcoded English from the markup); an +`applyUiStrings(lang)` function fills every tagged node on load and on every +language change. + +### 4.3 Annotation strings — no schema change +The manifest already stores `strings: {"en": {key: text}}` per clip. We add +`es / fr / ja` sibling keys to each clip's `strings` object. The two render +sites change from a hardcoded `.en`: + +- `simulator/static/app.js:505` (Left labels/facts) +- `simulator/static/app.js:556` (Right emotions) + +…to `clip.strings[activeLang] || clip.strings.en` — an **English fallback** so a +missing key never blanks the overlay. Tier-list structure (general→scientific, +emotion escalation) is preserved per language. + +## 5. The dropdown & selection behavior + +- A `