i18n-parity — Claude Code rule: what it does, how to install
i18n-parity enforces identical localization coverage across all supported locales in the same pull request, preventing incomplete translations.
MIT ★ 1,198 updated 2026-10-23
.claude/rules/i18n-parity.mdWhat i18n-parity does
This rule stops coding agents from submitting partial translations. English serves as the single source of truth across the project. Whenever an agent creates a key in client/src/i18n/locales/en/<ns>.json, it must add the identical key path, value type, and interpolation tokens to every locale file in the same change. Edits to README-EN.md must be mirrored across README-CN.md, README-VN.md, README-KO.md, and README-ES.md.
Identifiers, CLI flags, URLs, environment variables, and Claude Code tool names like Bash, Agent, Read, and Edit remain untouched. The UI noun agent turns into agente in Spanish, while the tool name stays literal everywhere.
The canonical instructions live in .claude/skills/i18n-parity/. The check script bash .claude/skills/i18n-parity/scripts/i18n-audit.sh must return code 0, failing immediately whenever mirrors in .codex/ fall behind or a registered locale lacks translations.
What it helps with
- Keep new localization keys synchronized across every supported language file
- Mirror documentation updates from
README-EN.mdinto all translated guides - Prevent translation of identifiers, command flags, and built-in agent tool names
- Audit translation completeness before merging changes
Example prompts for the agent
- Add a new key to
client/src/i18n/locales/en/common.jsonand sync all locales following i18n-parity - Update the setup section in
README-EN.mdand mirror the changes to every localized guide - Run
bash .claude/skills/i18n-parity/scripts/i18n-audit.shand fix missing locale keys
How to install i18n-parity
Manually: put the files in place
.claude/rules/i18n-parity.mdThe paths frontmatter field limits the files
AGENTS.md
Codex reads AGENTS.md: paste the rule text there
Manually: put the files in place
.cursor/rules/i18n-parity.mdcFrontmatter: description, globs, alwaysApply
Manually: put the files in place
.github/instructions/i18n-parity.instructions.mdThe applyTo field sets which files it applies to
Manually: put the files in place
.devin/rules/i18n-parity.mdManually: put the files in place
.clinerules/i18n-parity.mdStep by step, with commands for each platform: AGENTS.md vs CLAUDE.md: what they are and which one to use
Questions about i18n-parity
How to install i18n-parity in Claude Code?
Save the rule file to .claude/rules/i18n-parity.md in your project root.
What does the i18n-parity rule do?
It requires coding agents to mirror interface text and documentation across all supported languages in the same pull request, rejecting partial translations.
What elements does the rule protect from translation?
It prohibits translating code, paths, URLs, environment variables, CLI flags, HTTP status codes, and Claude Code tool names such as Bash and Agent.
Source text
i18n-parity.md · MIT
---
paths:
- "client/src/i18n/**"
- "client/src/components/Sidebar.tsx"
- "client/src/lib/format.ts"
- "client/src/lib/paletteCommands.ts"
- "README.md"
- "README-EN.md"
- "README-CN.md"
- "README-VN.md"
- "README-KO.md"
- "README-ES.md"
- "docs/I18N.md"
---
# i18n Parity Rules (binding for every coding agent)
The dashboard is localized to **English (`en`), Simplified Chinese (`zh`),
Vietnamese (`vi`), Korean (`ko`), and Spanish (`es`)** across five independent
surfaces. English is the source of truth on all of them, and **a change is not
done until every supported language carries it in the same PR** — a fallback to
English is a safety net, never a completed translation.
The full workflow, the surface map, the new-language checklist, and the
glossary live in [`.claude/skills/i18n-parity/`](../skills/i18n-parity/SKILL.md).
Invoke that skill for anything beyond a single-key edit. It is mirrored to
`.agents/skills/i18n-parity/` and `.codex/skills/i18n-parity/` so Codex and
other agents get the same instructions; **edit the canonical `.claude/` copy and
re-run `bash .claude/skills/i18n-parity/scripts/sync-agent-mirrors.sh`** — the
audit fails on a stale mirror.
## Non-negotiables
- **Adding an i18n key** → add it to `client/src/i18n/locales/en/<ns>.json` **and
every other locale's `<ns>.json`**, with the same key path, the same value
type, and the same `{{interpolation}}` tokens. Enforced by
`client/src/i18n/__tests__/i18n.test.ts`.
- **Adding a namespace** → create the JSON for every locale, then register the
imports, the per-language `resources` entry, and the `ns` array in
`client/src/i18n/index.ts`.
- **Editing `README.md`** → keep the English-only landing concise and preserve
links to `README-EN.md` plus every localized full guide.
- **Editing `README-EN.md`** → mirror the same edit at the corresponding section of
`README-CN.md`, `README-VN.md`, `README-KO.md`, and `README-ES.md`. All four,
every time. They are full mirrors, not summaries.
- **Editing user-visible text in `wiki/index.html`** → follow
[`.claude/rules/wiki-i18n.md`](./wiki-i18n.md) and ship `zh` + `vi` + `ko` +
`es` entries in the same change, then bump the wiki cache versions.
- **Adding a language** → work through
[`.claude/skills/i18n-parity/references/new-language-checklist.md`](../skills/i18n-parity/references/new-language-checklist.md)
end to end. A complete README mirror, every app key, and a complete wiki
translation are all required; partial locales are not merged.
- **Never translate** code, commands, paths, URLs, env-var names, CLI flags,
identifiers, HTTP verbs/status codes, numbers with units, brand names, hook
event names (`PreToolUse`, `Stop`, …), or Claude Code tool names (`Bash`,
`Agent`, `Read`, `Edit`). Translate only the prose around them.
- **The Claude Code tool `Agent` and the UI noun "agent" are different things.**
The tool name is an identifier and stays literal in every locale. The UI noun
(`common:agent` / `common:subagent`) is literal in `zh`, `vi`, and `ko` but
deliberately `agente` / `subagente` in `es` — `i18n.test.ts` asserts both
halves. The Spanish exception never applies to the tool name.
- The root landing page `index.html` and repository landing `README.md` are
**English-only by design**. The complete localized guide set begins with
`README-EN.md`.
## Verify
```bash
bash .claude/skills/i18n-parity/scripts/i18n-audit.sh # must exit 0
npm run test:client
```
The audit reads `supportedLngs` from `client/src/i18n/index.ts`, so declaring a
locale there immediately turns every unfilled surface into a named failure.
© hoangsonww · MIT · hoangsonww/Claude-Code-Agent-Monitor