i18n-expert

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

I18n Expert

I18n 专家

Overview

概述

Deliver a complete i18n setup + audit pass: configure the i18n framework, replace user-facing strings with keys, ensure locale parity, and validate pluralization/formatting for en-US and zh-CN.

提供完整的i18n设置+审核流程：配置i18n框架，将面向用户的字符串替换为键，确保语言包一致性，并验证en-US和zh-CN的复数形式/格式。

Core Capabilities

核心能力

Library selection and setup (React, Next.js, Vue).
Key architecture and locale file organization.
Translation generation and quality strategy (AI, professional, manual).
Routing and language detection/switching.
SEO and metadata localization (when applicable).
RTL support (only if RTL locales are in scope).

库选择与设置（React、Next.js、Vue）。
键架构与语言包文件组织。
翻译生成与质量策略（AI、专业人工、手动）。
路由与语言检测/切换。
SEO与元数据本地化（适用时）。
RTL支持（仅当涉及RTL语言时）。

Scope Inputs (ask if unclear)

范围输入（不明确时询问）

Framework and routing style.
Existing i18n state (none, partial, legacy).
Target locales (default: en-US + zh-CN).
Translation quality needs (AI vs professional vs manual).
Locale formats in use (JSON, YAML, PO, XLIFF).
Formality/cultural requirements (if any).

框架与路由风格。
现有i18n状态（无、部分完成、遗留系统）。
目标语言（默认：en-US + zh-CN）。
翻译质量需求（AI生成 vs 专业人工 vs 手动）。
使用的语言包格式（JSON、YAML、PO、XLIFF）。
正式程度/文化要求（如有）。

Workflow (Audit -> Fix -> Validate)

工作流程（审核 -> 修复 -> 验证）

Confirm scope and locale targets

Identify the i18n framework and locale locations.
Confirm locales; default to en-US + zh-CN when specified.

Setup i18n baseline (if missing)

Choose a framework-appropriate library (e.g., React: react-i18next; Next.js: next-intl; Vue: vue-i18n).
Install packages and create the i18n entry/config file.
Wire the provider at the app root and load locale resources.
Add a language switcher and persistence (route/param/localStorage) as appropriate.
Establish locale file layout and key namespaces.
If routing is locale-aware, define the locale segment strategy early (subpath, subdomain, query param).
If metadata is user-facing, include translation for titles/descriptions.

Audit key usage and locale parity

Run:

bash

python scripts/i18n_audit.py --src <src-root> --locale <path/to/en-US.json> --locale <path/to/zh-CN.json>

Treat missing keys/parity gaps as blockers.
Manually verify dynamic keys (
```
t(var)
```
).

Find raw user-facing strings

Search:

bash

rg -n --glob '<src>/**/*.{ts,tsx,js,jsx}' "<[^>]+>[^<{]*[A-Za-z][^<{]*<"
rg -n --glob '<src>/**/*.{ts,tsx,js,jsx}' "aria-label=\"[^\"]+\"|title=\"[^\"]+\"|placeholder=\"[^\"]+\""

Localize accessibility labels.

Replace strings with keys

Use
```
t('namespace.key')
```
for UI text.
For plurals use
```
t('key', { count })
```
+
```
_one/_other
```
keys.
Use Intl/app formatters for time/date/number.

Localize error handling (critical)

Map error codes to localized keys; show localized UI only.
Log raw error details only.
Provide localized fallback for unknown codes.

Update locale files

Add missing keys in both locales.
Keep placeholders consistent; avoid renames unless requested.
Generate translations using the agreed method; preserve placeholders and plural rules.

Validate

Re-run the audit until missing/parity issues are zero.
Validate JSON (e.g.,
```
python -m json.tool <file>
```
).
Update tests asserting visible text.

确认范围与目标语言

确定i18n框架和语言包位置。
确认语言；指定时默认使用en-US + zh-CN。

搭建i18n基础（若缺失）

选择适合框架的库（例如React：react-i18next；Next.js：next-intl；Vue：vue-i18n）。
安装包并创建i18n入口/配置文件。
在应用根节点接入provider并加载语言包资源。
添加语言切换器并配置持久化（路由/参数/localStorage）（视情况而定）。
建立语言包文件结构和键命名空间。
如果路由支持语言感知，尽早定义语言段策略（子路径、子域名、查询参数）。
如果元数据面向用户，需翻译标题/描述。

审核键使用与语言包一致性

运行：

bash

python scripts/i18n_audit.py --src <src-root> --locale <path/to/en-US.json> --locale <path/to/zh-CN.json>

将缺失的键/一致性差异视为阻塞问题。
手动验证动态键（
```
t(var)
```
）。

查找原始面向用户的字符串

搜索：

bash

rg -n --glob '<src>/**/*.{ts,tsx,js,jsx}' "<[^>]+>[^<{]*[A-Za-z][^<{]*<"
rg -n --glob '<src>/**/*.{ts,tsx,js,jsx}' "aria-label=\"[^\"]+\"|title=\"[^\"]+\"|placeholder=\"[^\"]+\""

本地化无障碍标签。

将字符串替换为键

对UI文本使用
```
t('namespace.key')
```
。
复数形式使用
```
t('key', { count })
```
+
```
_one/_other
```
键。
对时间/日期/数字使用Intl/应用格式化工具。

本地化错误处理（关键）

将错误代码映射为本地化键；仅显示本地化UI。
仅记录原始错误详情。
为未知代码提供本地化回退。

更新语言包文件

在两种语言的语言包中添加缺失的键。
保持占位符一致；除非有要求，否则避免重命名。
使用约定的方法生成翻译；保留占位符和复数规则。

验证

重新运行审核直到缺失/一致性问题为零。
验证JSON格式（例如
```
python -m json.tool <file>
```
）。
更新断言可见文本的测试。

Guardrails

约束规则

Never expose raw
```
error.message
```
to UI; show localized strings only.
Do not add extra locales unless explicitly requested.
Prefer structured namespaces (e.g.,
```
errors.*
```
,
```
buttons.*
```
,
```
workspace.*
```
).
Keep translations concise and consistent.
Some technical/brand terms should remain untranslated (e.g., product name, API, MCP, Bash).

绝不要在UI中暴露原始
```
error.message
```
；仅显示本地化字符串。
除非明确要求，否则不要添加额外语言。
优先使用结构化命名空间（例如
```
errors.*
```
、
```
buttons.*
```
、
```
workspace.*
```
）。
保持翻译简洁一致。
部分技术/品牌术语应保持不翻译（例如产品名称、API、MCP、Bash）。

Deliverables (expected outputs)

交付成果（预期输出）

i18n config/provider wiring.
Locale files for each target language.
Replaced UI strings with stable keys.
Language switcher and persistence (if applicable).
Updated tests for visible text.

i18n配置/provider接入代码。
各目标语言的语言包文件。
已替换为稳定键的UI字符串。
语言切换器与持久化（如适用）。
更新后的可见文本测试。

Architecture Guidance (keep concise)

架构指导（简洁为主）

Key structure: prefer nested namespaces by area (e.g.,
```
common.buttons.save
```
,
```
pricing.tier.pro
```
).
File layout: one file per locale or per-locale namespaces; keep keys in sync across locales.
Placeholders: preserve
```
{name}
```
/
```
{{name}}
```
exactly; validate plurals by locale rules.
Formatting: use Intl/app helpers for date, time, number, and list formatting.
SEO/metadata: localize titles and descriptions if the app exposes them.
RTL: only needed for RTL locales; use logical CSS properties and test layout.
Non-web surfaces (Electron main-process dialogs, CLI prompts, native menus) need localization too.

键结构：按领域优先使用嵌套命名空间（例如
```
common.buttons.save
```
、
```
pricing.tier.pro
```
）。
文件布局：每种语言一个文件，或按语言分命名空间；保持各语言的键同步。
占位符：严格保留
```
{name}
```
/
```
{{name}}
```
；按语言规则验证复数形式。
格式化：使用Intl/应用工具进行日期、时间、数字和列表格式化。
SEO/元数据：如果应用对外暴露，需本地化标题和描述。
RTL：仅在涉及RTL语言时需要；使用逻辑CSS属性并测试布局。
非Web场景（Electron主进程对话框、CLI提示、原生菜单）也需要本地化。

Performance Notes (short)

性能注意事项（简短）

Lazy-load locale bundles when the app supports it.
Split large locale files by namespace.

如果应用支持，延迟加载语言包。
按命名空间拆分大型语言包文件。

Failure Modes (watchlist)

失败模式（注意事项）

Missing translations: fall back to default locale and log warnings.
RTL layout issues: verify logical CSS and test pages.
SEO missing: ensure alternates and metadata are localized when applicable.

缺失翻译：回退到默认语言并记录警告。
RTL布局问题：验证逻辑CSS并测试页面。
SEO缺失：确保适用时本地化替代内容和元数据。

Validation Checklist (short)

验证清单（简短）

No missing keys and no raw UI strings.
Locale switching works and persists.
Plurals and formatting verified in both locales.
Fallback locale configured.

无缺失键和原始UI字符串。
语言切换功能正常并可持久化。
已验证两种语言的复数形式和格式。
已配置回退语言。

Resources

资源

scripts/

```
scripts/i18n_audit.py
```
: Extracts
```
t('key')
```
usage and compares against locale JSON files.

```
scripts/i18n_audit.py
```
：提取
```
t('key')
```
的使用情况并与语言包JSON文件对比。