/i18n-parity

name: i18n-parity
description: MANDATORY for every coding agent and contributor touching localized content — keep all five localization surfaces (dashboard UI keys, wiki page, full mirrored guides, locale-aware formatting, language switchers) in parity across every supported language. Use automatically (without being asked) whenever you add or change user-visible UI copy, add an i18n key, edit README-EN.md or a localized guide, edit wiki/index.html, or add a language surface.

i18n Parity

This repository is localized on **five independent surfaces**, each with its own mechanism. A change that lands on one and not the others leaves the product half-translated: the English falls through, and the gap is invisible to anyone working in English. This skill states the invariant, maps every surface to the exact files, and gives one command that proves parity.

**The invariant: English is the source of truth on every surface, and no change is done until every supported language carries it in the same PR.** A fallback to English is a safety net, never a completed translation.

Supported languages are declared in one place — `supportedLngs` in [`client/src/i18n/index.ts`](../../../client/src/i18n/index.ts). Today: **`en`, `zh`, `vi`, `ko`, `es`**. Everything below derives from that list; the audit script reads it rather than hard-coding.

The five surfaces

| # | Surface | English source of truth | Translations live in | Automated gate | |---|---|---|---|---| | 1 | **Dashboard UI** | `client/src/i18n/locales/en/*.json` | `client/src/i18n/locales/<xx>/*.json` (same 15 namespaces) | `client/src/i18n/__tests__/i18n.test.ts` — key, type, and interpolation-token parity | | 2 | **Wiki page** | English text in the `wiki/index.html` DOM | `wiki/script.js` (`T`, `ATTRIBUTE_TRANSLATIONS`, `META`, `languageLabels`, the two language ladders) + `wiki/i18n-content.js` (`window.__WIKI_CONTENT_I18N`, both the body bundles and `plain`) | `client/tests/wiki-i18n.test.ts` — live-DOM prose coverage, inline-tag preservation, block-length budgets, asset-version sync | | 3 | **Full mirrored guides** | `README-EN.md` | `README-CN.md` (zh), `README-VN.md` (vi), `README-KO.md` (ko), `README-ES.md` (es) | partial — `scripts/i18n-audit.sh` (existence, heading count, cross-links) and `server/__tests__/plugins-marketplace.test.js` (documented counts); prose parity is review-only | | 4 | **Language switchers** | — | `client/src/components/Sidebar.tsx`, `client/src/lib/paletteCommands.ts`, the two `.lang-select-menu` blocks in `wiki/index.html`, `nav.json` `languageNames` / `languageShort` | `scripts/i18n-audit.sh` | | 5 | **Locale-aware formatting** | — | `client/src/lib/format.ts` (`SupportedLanguage` union, `getCurrentLanguage()` whitelist, `getCurrentLocale()` BCP-47 map) | `client/src/lib/__tests__/format.test.ts` |

What is deliberately NOT localized

Verified against the tree — do not go looking for translation hooks in these, and do not add them without being asked:

• **The root landing page `index.html`** has no i18n layer. Do not add

`data-lang` markup; put localized long-form content in the wiki instead. Its one language-aware element is the `Languages (en/zh/…)` stat label, which just enumerates the codes.

• **The repository landing page `README.md`** is a concise English-only entry

point. It links every complete language guide but is not itself mirrored. Full technical content belongs in `README-EN.md` and its four translations.

• **`client/index.html`** is an English shell: `<html lang="en">`,

`og:locale=en_US`, and English `<title>`/meta. The React app never reassigns `document.documentElement.lang` when the user switches language — a known gap, not something a translation PR is expected to fix.

• **The CLI (`bin/ccam.js` + `cli/`), the MCP server (`mcp/`), the Express server

(`server/`), the desktop shell (`desktop/`), the VS Code extension, and the statusline** contain no i18n wiring at all. Their output is English.

• **`client/src/lib/event-summary.ts` and `event-grouping.ts`** build tool-event

headlines and bullets from English template literals (`Last message: …`, `3 lines stdout`, `2 matches`). Their MODULE_GUIDE boilerplate claims strings belong in i18n JSON, but neither file imports i18next. They sit outside the key system today; do not "fix" them as part of a localization change.

• **Number and date formatting is only locale-aware where the `format.ts`

helpers are used.** Most components call `toLocaleString()` / `toLocaleString(undefined, …)` directly, which follows the *browser* locale rather than the chosen UI language. In new code prefer `getCurrentLocale()` from `format.ts`; leave existing call sites alone unless asked.

Workflow A — you changed content (the common case)

Find what you touched in the left column and ship everything in the right column **in the same PR**.

| You changed | You must also do | |---|---| | Added/renamed a UI string or i18n key | Add the key to `en` **and every other locale** in the same namespace file. Same key path, same value type, same `{{interpolation}}` tokens. | | Added a new namespace (new `*.json`) | Create it for every locale, then register the imports, the `resources` entry per language, and the `ns` array in `client/src/i18n/index.ts`. | | Added user-visible wiki text in `wiki/index.html` | Follow [`.claude/rules/wiki-i18n.md`](../../rules/wiki-i18n.md): scannable layer (the `PLAIN` selector set — `.logo-sub`, `.section-label`, `.nav-section`, `.nav-empty`, `.stat-label`, `.t-label`, `h2`/`h3`/`h4`, `th`, `.hero-desc`, plus `.nav-link` / `.hero-badge` trailing text nodes) → `T` in `wiki/script.js`; body prose (the `HTML_SEL` set — `p`, `li`, `td`, `th`, captions, `.callout-body > strong`, `.route-desc`, footer) → `wiki/i18n-content.js` keyed by whitespace-normalized `innerHTML`; new `alt`/`aria-label`/`title`/`placeholder` → `ATTRIBUTE_TRANSLATIONS`. Then bump `CACHE_NAME` in `wiki/sw.js` and the matchin