Skip to content

hoangsonww/Claude-Code-Agent-Monitor / .claude/skills/i18n-parity

i18n-parity

Verified

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.

FileKindSize
SKILL.mdskill md13.3 KB
references/new-language-checklist.mdmarkdown10.3 KB
references/translation-style.mdmarkdown6.3 KB
scripts/i18n-audit.shexecutablescript15.0 KB
scripts/sync-agent-mirrors.shexecutablescript5.4 KB

references/translation-style.md

View on GitHub
# Translation Style and Glossary

Terminology drift — the same concept rendered three ways on three pages — is the
most common review comment on localization PRs. This file is the tie-breaker.

## Never translate

| Category | Examples |
|---|---|
| Code and commands | anything inside `<code>` / backticks, `npm run dev`, `ccam sessions` |
| Paths and URLs | `client/src/i18n/index.ts`, `~/.claude/settings.json`, any link target |
| Env vars and CLI flags | `DASHBOARD_TOKEN_REPAIR`, `--list`, `PORT` |
| HTTP | `GET`, `POST`, `404`, `WebSocket`, `SSE` |
| Identifiers | function, class, table, column, and namespace names |
| Claude Code vocabulary | hook events (`PreToolUse`, `PostToolUse`, `Stop`, `SessionStart`, `Notification`), tool names (`Bash`, `Agent`, `Read`, `Edit`) — the **tool** `Agent` is an identifier and is never translated in any locale |
| Brand and product names | Claude Code, Codex, MCP, SQLite, Express, React, Vite, Prometheus, Grafana, Tabby |
| Numbers with units | `~50,000 inserts/sec`, `200 KB / 63 KB gzip`, `< 5ms` |

**Two different things are spelled `Agent`.** The Claude Code **tool** named
`Agent` (alongside `Bash`, `Read`, `Edit`) is an identifier and stays literal in
**every** locale, everywhere it appears — hook-event tables, tool lists, event
names. The **UI noun** for an agent (`common:agent` / `common:subagent`) is
product vocabulary with a per-locale contract, and only that noun has the
Spanish exception below. Never carry the exception into the tool name.

**As product vocabulary, `Agent` and `Subagent` are not ordinary English
words** — but the repo does not treat them identically in every locale, and
`client/src/i18n/__tests__/i18n.test.ts` pins the actual contract:

| Locale | `common:agent` | `common:subagent` |
|---|---|---|
| `zh` / `vi` / `ko` | `Agent` (literal) | `Subagent` (literal) |
| `es` | `agente` | `subagente` |

Spanish localizing the pair is deliberate and asserted, not drift — Spanish has
no comfortable way to carry the bare English noun through inflected prose. So
keep `Agent` literal in `zh`, `vi`, and `ko` (`运行 Agent`, `Chạy Agent`,
`Agent 실행`) and follow the Spanish convention in `es` (`Ejecutar agente`).
**If you add a locale, decide this explicitly and add its row to the test** —
do not leave it to whichever phrasing the first translated string happens to use.

A wiki block whose content is *entirely* code, identifiers, or product names
needs no `wiki/i18n-content.js` entry — it correctly falls back to English.

## Core glossary

Established renderings. Match these; do not introduce a synonym.

| English | `zh` | `vi` | `ko` | `es` |
|---|---|---|---|---|
| Dashboard | 仪表盘 | Tổng quan | 대시보드 | Panel |
| Kanban Board | Kanban 看板 | Bảng Kanban | 칸반 보드 | Tablero Kanban |
| Sessions | 会话 | Phiên | 세션 | Sesiones |
| Activity Feed | 活动流 | Luồng hoạt động | 활동 피드 | Feed de Actividad |
| Analytics | 分析 | Phân tích | 분석 | Analíticas |
| Workflows | 工作流 | Quy trình | 워크플로 | Flujos |
| Alerts | 警报 | Cảnh báo | 알림 | Alertas |
| Agent Config | Agent 配置 | Cấu hình Agent | Agent 설정 | Configuración del agente |
| Run Agent | 运行 Agent | Chạy Agent | Agent 실행 | Ejecutar agente |
| Settings | 设置 | Cài đặt | 설정 | Configuración |
| Live | 在线 | Trực tiếp | 실시간 | En vivo |
| Disconnected | 已断开 | Mất kết nối | 연결 끊김 | Desconectado |

### Session status vocabulary

These five values appear in filters, badges, charts, the Kanban columns, and
every state-machine diagram in the docs. Keep them identical everywhere.

| English | `zh` | `vi` | `ko` | `es` |
|---|---|---|---|---|
| Active | 活跃 | Đang hoạt động | 활성 | Activas |
| Waiting | 等待中 | Đang chờ | 대기 중 | En espera |
| Completed | 已完成 | Hoàn tất | 완료됨 | Completadas |
| Error | 错误 | Lỗi | 오류 | Error |
| Abandoned | 已废弃 | Bị bỏ dở | 중단됨 | Abandonadas |

When adding a new locale, extend both tables in this file with its column before
you start translating — deciding the vocabulary once up front is what keeps 15
namespaces and a 7,000-line wiki bundle coherent.

## Mechanics

- **Interpolation tokens are literal.** `{{count}}`, `{{name}}`, `%{value}` must
  survive verbatim; only their surrounding words are translated. Reordering
  around a token is fine and often necessary.
- **Plurals use the i18next v4 JSON suffixes `_one` / `_other`** (the client is
  on i18next 26). Never use the legacy `_plural` suffix: v4 does not resolve
  it, so the count silently falls back to the singular text. Because the parity test requires an **identical key set in
  every locale**, `zh`, `vi`, and `ko` must still carry both `_one` and
  `_other` even though they have no plural inflection: give both the same
  string. `es` gets genuinely different forms, as English does.
- **Inline markup is preserved exactly.** A `wiki/i18n-content.js` value must
  contain the same set of `<code>`, `<strong>`, `<a>`, and `<span>` tags as its
  English key, with the same attributes. Dropping a tag silently breaks the
  page's styling and links in that locale only.
- **Length matters in the UI.** Sidebar labels, buttons, table headers, and
  Kanban column titles live in fixed-width space. After translating, check a
  narrow viewport; prefer the shorter natural phrasing over a literal one.
- **Wiki blocks have length budgets** (feature cards ~450–550 chars, screenshot
  captions ~150–300). A translation that doubles the English length breaks the
  carousel layout. See `.claude/rules/wiki-i18n.md`.
- **Tone matches the English**: direct, technical, second person, no marketing
  filler. Documentation register, not advertising.

## README mirrors

- Mirror **structure first**: same headings in the same order, same tables with
  the same rows and column counts, same code blocks, same mermaid diagrams.
- In mermaid, translate **labels only** — node IDs, arrows, and directives stay
  as written, or the diagram stops parsing.
- Keep badges, links, and anchors pointing at the same targets as `README-EN.md`.
- Numbers quoted in prose (plugin counts, skill counts, namespace counts) must
  match the English exactly; they are asserted in
  `server/__tests__/plugins-marketplace.test.js`.
brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation).Stars: 323kUpdated Claude CodeCodexVerifiedInstall
brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK).Stars: 198kUpdated Claude CodeCodexVerifiedInstall