@micha.bigler/ui-core-micha 2.41.0 → 2.41.2

package/work-orders/I18N-3.md

@@ -0,0 +1,139 @@
+# I18N-3 — Backfill Swahili in `messagingTranslations` and restore the four-locale shape test
+
+**Target repo:** `ui-core-micha` (branch `main`)
+**Tier:** 3 — shared-core, and it re-tightens a test the estate deliberately loosened.
+
+---
+
+## A. Envelope
+
+### Goal
+
+`src/i18n/messagingTranslations.ts` carries **116 keys with `de`/`fr`/`en` and zero `sw`**. Every one of the
+other six bundles carries all four locales:
+
+| bundle | de | fr | en | sw |
+|---|---|---|---|---|
+| `auth` | ✓ | ✓ | ✓ | ✓ |
+| `charts` | 12 | 12 | 12 | 12 |
+| **`messaging`** | **116** | **116** | **116** | **0** |
+| `notifications` | 30 | 30 | 30 | 30 |
+| `onboarding` | 27 | 27 | 27 | 27 |
+| `sectionNav` | 3 | 3 | 3 | 3 |
+| `userMenu` | 3 | 3 | 3 | 3 |
+
+`I18N-1` hit this while writing its aggregate test: the required "every value keeps its `{de,fr,en,sw}` shape"
+assertion failed, the gap was confirmed as pre-existing rather than caused by the merge, and the operator
+scoped the test down to `{de,fr,en}` with the backfill recorded as a follow-up. **The follow-up was never
+written, and a scoped-down test tends to stay scoped down.** That is what this WO closes.
+
+### Scope
+
+1. **`src/i18n/messagingTranslations.ts`** — add `sw` to all 116 keys.
+2. **`tests/i18nAggregate.test.js`** — restore the shape assertion to `{de,fr,en,sw}` and **remove the comment
+   recording the scope-down**, since it no longer describes the state.
+3. Nothing else. No other bundle is touched; they already conform.
+
+### The translation quality question, which is this WO's real risk
+
+**Machine-translated UI strings that nobody on the team can check are a worse outcome than an honest gap.**
+Messaging strings are user-facing and include the kinds of phrase that go wrong invisibly — actions,
+confirmations, error states, relative time. So:
+
+- **Name the source of the translations in the register note.** If they are machine-produced, say so plainly
+  rather than shipping them as if reviewed.
+- **Flag any key the translator was unsure of** rather than guessing. A `sw` value that is wrong is harder to
+  find later than one that is missing, because the shape test will then pass.
+- **Do not invent terminology.** Where `notifications` or `onboarding` already has a Swahili term for the same
+  concept — send, reply, unread, conversation, attachment — **reuse their wording** rather than coining a
+  second one. Those bundles are the existing precedent and consistency across them matters more than any
+  individual phrasing.
+
+### Who this is actually for
+
+`sw` is configured as a locale in **hram** and in no other app measured. hram does **not** register
+`messagingTranslations` today, so nothing is currently broken for a user — this is prevention, and the honest
+framing is: it closes an inconsistency and re-arms a test, rather than fixing a live defect.
+
+That matters for the effort trade-off, and it is why the quality bar above is not negotiable: there is no
+urgency justifying unreviewed strings.
+
+### Non-goals / do not touch
+
+- **The other six bundles.** They conform.
+- **The aggregate itself, the directory ratchet, or the key/value fidelity and collision checks.** Only the
+  locale-shape assertion changes.
+- **`de`/`fr`/`en` values.** Not a re-translation pass.
+- **Adding an eighth locale**, or any change to how consumers register strings (`I18N-2`'s territory).
+
+### Risks
+
+- **116 unreviewable strings.** The mitigation is disclosure, not confidence — see above.
+- **Re-tightening the test is the irreversible half.** Once the assertion demands four locales, any future
+  bundle addition must supply `sw` or fail CI. That is the intent, and it is worth stating so the next person
+  adding a bundle is not surprised.
+- **A push to `main` publishes.** See Part C.
+
+### Required tests to WRITE
+
+None new — **`tests/i18nAggregate.test.js`'s restored four-locale assertion IS the test**, and re-arming it is
+scope item 2. It will fail until the backfill is complete, which is the correct behaviour and the reason it
+belongs in the same change.
+
+Scoped run: `i18nAggregate` plus the messaging export specs. Not the full suite — no dependency or theme
+change.
+
+### Parity guardrail
+
+No API, behaviour or visual change for `de`/`fr`/`en` consumers. Purely additive.
+
+---
+
+## B. Implementation map
+
+*Filled by the Orchestrator on `git pull` — see `AGENTS.md` → "Work Order".*
+
+---
+
+## C. Orchestrator only
+
+> **STOP — if you are the implementer reading this work order as your own specification, this section is NOT
+> addressed to you. Skip it entirely.** It tells the Orchestrator how to invoke you. **You ARE that
+> invocation — do NOT shell out to `codex exec`, do NOT spawn reviewers, do NOT edit `WORK_ORDERS.md`, and do
+> NOT `git add`/`commit`/`push`.**
+
+### Execution directive
+
+Check `.claude/codex-status.md` first. **No line for the current date means use Codex.** A dated `unavailable`
+line for today means skip the attempt, implement directly in Claude and name the record — that flips
+authorship. Otherwise one probe, outcome written back either way.
+
+### Review routing
+
+Tier 3: **independent `reviewer`** — mandatory. Ask it specifically to check **terminology consistency against
+`notifications` and `onboarding`**, and to confirm that no `de`/`fr`/`en` value was altered in passing. **No
+`ui_reviewer`** — nothing renders. No `sec_reviewer`.
+
+Neither reviewer can validate Swahili. **Say that in the note** rather than letting a clean verdict imply the
+translations were checked.
+
+### Verification
+
+The restored four-locale assertion passing is the verification. Nothing renders, so no gate.
+
+**A push to `main` here IS the npm publish** — `publish.yml` triggers on `push: branches: [main]` with `src/**`
+in its paths, and publishes cannot be undone. Additive strings, so a **patch** by scope.
+
+### Register + commit
+
+One row, `I18N-3`. `done` only with the reviewer and verdict named, **the translation source stated**, and any
+uncertain keys listed. Also update `I18N-1`'s note: its recorded follow-up is now closed, and leaving it open
+there is how the same gap gets rediscovered.
+
+### Mini-handover
+
+Repo: `ui-core-micha`, branch `main`. WO: `work-orders/I18N-3.md`. 116 `sw` values into
+`messagingTranslations.ts`, then restore `i18nAggregate.test.js` to `{de,fr,en,sw}` and drop the scope-down
+comment. **Reuse `notifications`/`onboarding` terminology; disclose the translation source; flag uncertain
+keys instead of guessing.** No app is broken today — this closes an inconsistency and re-arms a test. Tier 3,
+`reviewer` mandatory. **Pushing to main publishes.** Follow `orchestrate-codex`.