Files

gsxdsm b2f564c2be FN-6791: add i18n regression guardrails

Add focused i18n regression coverage for dashboard localization guardrails.

- Assert dashboard hardcoded-string lint ignores stay limited to non-shipping patterns.
- Verify real locale catalogs retain key parity across supported locales and namespaces.
- Cover fallback behavior for empty secondary translations, missing keys, unsupported locale tags, and Chinese locale normalization.
- Document that @fusion/i18n tests now protect lint-ignore scope and catalog parity drift.

Files changed:
 docs/i18n-contributing.md                          |  2 +
 .../i18n/src/__tests__/i18n-gate-coverage.test.ts  | 65 +++++++++++++++++++
 .../i18n/src/__tests__/locale-fallback.test.ts     | 72 ++++++++++++++++++++++
 3 files changed, 139 insertions(+)

Fusion-Task-Id: FN-6791

Fusion-Task-Lineage: 7f52113e-237a-415d-a109-51295fdc0372

2026-06-20 11:02:55 -07:00

4.9 KiB

Raw Blame History

Localization (i18n) contributor guide

Fusion's UI is localized with react-i18next. English (en) is the source-of-truth language; everything else is a translation of it. Both UI surfaces — the React dashboard and the Ink terminal UI — share one set of catalogs and config in the @fusion/i18n package.

Where things live

Path	What it is
`packages/i18n/locales/{locale}/{namespace}.json`	Authored catalogs (translators edit here). `en` is the source.
`packages/i18n/src/config.ts`	Shared i18next config: namespaces, fallback chain, plural setup.
`packages/core` (`SUPPORTED_LOCALES`, `Locale`)	The single list of supported locale codes.
`i18next.config.ts` (repo root)	`i18next-cli` workflow config.

Namespaces: common (shared), app (dashboard-only), errors, and cli (terminal-only). The dashboard loads common/app/errors; the CLI loads common/cli/errors.

The workflow

All commands run from the repo root:

pnpm i18n:extract   # pull t()/<Trans> keys from source into the en catalogs
pnpm i18n:sync      # propagate the en key structure to every other locale
pnpm i18n:types     # regenerate key types from the en catalogs
pnpm i18n:status    # key-parity gate: structure only, empty values allowed
pnpm i18n:status:report # upstream completeness report (informational; may exit non-zero)
pnpm i18n:lint      # flag hardcoded user-facing strings
pnpm i18n:gen-cli   # regenerate the CLI static catalog import map

pnpm i18n:status must be green before landing catalog or extraction changes, but it only verifies that every secondary catalog has the same structural keys as en. Empty secondary-locale values ("") are expected placeholders and do not fail the gate because runtime falls back to English. Use pnpm i18n:status:report when you want the upstream completeness report that counts empty placeholders as untranslated; that report is informational and may exit non-zero until translations are filled.

Lint baseline policy

pnpm i18n:lint is the hardcoded user-facing string guardrail and must stay green. Its file scope intentionally matches extraction: tests and stories are excluded because they are non-shipping fixtures and extract already ignores them. Suppress non-translatable token categories with narrow lint.ignoredTags / lint.ignoredAttributes entries, such as keyboard-key content in <kbd>, instead of hiding source directories.

Any remaining user-facing copy must be localized with t() / <Trans> and an en catalog entry. A temporary deferral is only acceptable when it is scoped to specific files or a small cluster in lint.ignore, includes an FNXC rationale, and has a filed follow-up task that removes the ignore. The settings sections cluster is no longer deferred as of FN-6771; keep those files covered by lint. The @fusion/i18n regression tests also assert the lint-ignore scope and live catalog key parity so those guardrails cannot silently drift.

Translating an existing language

Run pnpm i18n:sync so every catalog has the current en keys (untranslated entries are empty strings).
Fill the empty strings in packages/i18n/locales/{locale}/*.json.
Keep interpolation placeholders verbatim: {{brand}}, {{detail}}, {{key}}. Never translate a [{{key}}] keybinding accelerator — only the words around it.
Run pnpm i18n:status to confirm key parity still holds, then optionally run pnpm i18n:status:report to inspect remaining untranslated placeholders.

zh-CN and zh-TW are independent — different script and vocabulary. Do not machine-convert one into the other.

Adding a new language (near-zero code)

Add the locale code to SUPPORTED_LOCALES in packages/core/src/types.ts and to locales in i18next.config.ts.
pnpm i18n:sync — scaffolds a full set of catalog files for the new locale with the correct plural categories.
pnpm i18n:gen-cli — adds the locale to the CLI's static import map.
Run pnpm i18n:status to verify the new locale has the same key structure as en. Translate the new catalogs as time allows, using pnpm i18n:status:report as the informational completeness report.

No feature code changes are required: the dashboard discovers the locale through the generated app/locales/ tree, and the CLI through the regenerated import map. Add the language's endonym to ENDONYMS in packages/dashboard/app/components/LanguageSelector.tsx so it appears in the Settings switcher.

Using a non-English locale

Dashboard / mobile: Settings → Appearance → Language. The choice persists to localStorage and to server settings.
Terminal UI: resolved from --lang <code> → the saved dashboard language setting → the LC_ALL/LC_MESSAGES/LANG/LANGUAGE environment → en.
```
fusion dashboard --lang zh-TW
```

4.9 KiB Raw Blame History