i18n-tools 使用手册（场景版）

面向 JSON i18n 的翻译与英文语法检查 CLI，支持增量翻译、失败重试、远端仓库同步、快照管理和自定义提示词。

✨ 主要功能

• 多格式翻译：支持 {{variable}}、${variable} 和 ICU Message Format
• 增量翻译：基于快照差异的智能增量处理
• 语法检查：英文文案的语法和拼写检查
• 模板保护：完整保护所有模板变量和格式化语法
• 远程同步：从 Git 仓库同步 i18n 源文件
• 自定义规则：支持自定义提示词和翻译规则

🎯 支持的模板格式

基础变量格式

• {{variable}}：双大括号变量，如 {{app_name}}、{{user_count}}
• ${variable}：美元符号变量，如 ${username}、${date}

ICU Message Format

• 复数格式：{count, plural, =0{no items} =1{one item} other{# items}}
• 选择格式：{gender, select, male{he} female{she} other{they}}
• 数字格式：{price, number, currency}、{value, number, percent}
• 日期格式：{date, date, short}、{time, time, medium}
• 嵌套格式：支持多层嵌套的复杂 ICU 语法

安装与准备

• Node.js 版本：>= 18
• 包名：@alauda-fe/i18n-tools

可选使用方式：

# 直接使用（推荐）
npx @alauda-fe/i18n-tools

# 或全局安装
npm i -g @alauda-fe/i18n-tools

环境变量（也可通过命令行参数传入）：

• OPENAI_API_KEY：Azure OpenAI 密钥（或用 -k/--token 指定）
• GITLAB_TOKEN / GITHUB_TOKEN：sync 同步远端仓库时的访问令牌（或用 --token 指定）

目录约定

• 翻译源/目标（全量翻译）：直接以语言代码作为目录名，如 en/、zh/、ru/。
• 增量翻译：
  • 英文源：new/en/（由 sync 命令下载文件生成）
  • 快照：snapshot/en/（上一次翻译时的参考基线）
  • 输出：src/<目标语言>/（如 src/zh/）

翻译规则关键点：

• 保留 JSON 键名，跳过空 key/value
• 跳过注释条目（值以 // 开头）
• 跳过以 _en 结尾的键（视为英文原文，不翻译）
• 严格保护所有模板变量：{{var}}、${var}、ICU Message Format
• 保护技术术语的原始格式和拼写
• 失败时条目置为 null，后续可用重试命令补齐

常用场景与流程

1) 增量翻译语言包（推荐流程）

以中文翻译包为例：

1. 到 i18n-zh 仓库根目录，同步英文源到 new/en/：

npx @alauda-fe/i18n-tools sync \
	--level core \
	--branch master\
	--token $GITLAB_TOKEN   # 私有仓库需令牌，或设置 GITHUB_TOKEN

2. 执行增量翻译（输出新文案到 src/zh/，并更新 snapshot/en/，随后清理 new/）：

npx @alauda-fe/i18n-tools incremental-translate -s en -t zh -k $OPENAI_API_KEY

3. 人工检查变更（主要看 src/zh/ 与 snapshot/en/ 的 diff），确认后提交代码。

4. 若存在失败条目（值为 null），可重试：

npx @alauda-fe/i18n-tools retry-failed -s en -t zh -k $OPENAI_API_KEY

提示：incremental-translate 会在完成后自动写回 snapshot/en/ 并删除 new/。

2) 全量翻译一个语言包

当没有快照/增量需求时，直接从 en/ 翻译到目标目录：

npx @alauda-fe/i18n-tools translate -s en -t zh -k $OPENAI_API_KEY

注意：目标目录不存在会自动创建；已有同名键仅补齐缺失或为 null 的条目。

3) 英文文案语法检查（单文件/批量）

• 单文件（预览模式，不改文件）：

npx @alauda-fe/i18n-tools grammar-check -f src/en/common.json --dry-run -k $OPENAI_API_KEY

• 单文件（直接修改，自动备份并生成变更记录）：

npx @alauda-fe/i18n-tools grammar-check -f src/en/common.json -k $OPENAI_API_KEY

• 目录批量（并行 4 个文件，预览）：

npx @alauda-fe/i18n-tools batch-grammar-check -d src/en --parallel 4 --dry-run -k $OPENAI_API_KEY

📋 模板格式示例

基础变量格式

{
  "welcome": "Welcome to {{app_name}}!",
  "greeting": "Hello ${username}, today is ${date}",
  "path": "File saved to ${directory}/${filename}"
}

ICU 复数格式

{
  "item_count": "{count, plural, =0{No items} =1{One item} other{# items}}",
  "file_size": "{size, plural, =0{Empty} =1{# byte} other{# bytes}}",
  "notification": "{unread, plural, =0{All caught up!} other{# unread messages}}"
}

ICU 选择格式

{
  "pronoun": "{gender, select, male{he} female{she} other{they}}",
  "status": "{userStatus, select, online{Available} offline{Away} busy{Do not disturb} other{Unknown}}"
}

ICU 格式化类型

{
  "price": "Total: {amount, number, currency}",
  "progress": "Complete: {value, number, percent}",
  "created": "Created on {date, date, short}",
  "lastLogin": "Last login: {time, time, medium}"
}

复杂嵌套格式

{
  "complex": "{hasItems, select, true{{count, plural, =0{No items found} =1{Found one item} other{Found # items}}} false{Search returned no results}}",
  "permissions": "{role, select, admin{You can {action, select, create{add new} edit{modify} delete{remove} other{view}} content} user{Read-only access} other{No access granted}}"
}

翻译结果示例（英文→中文）

// 原文
{
  "messages": "{count, plural, =0{You have no messages} =1{You have one message} other{You have # messages}}"
}

// 中文翻译
{
  "messages": "{count, plural, =0{您没有消息} =1{您有一条消息} other{您有 # 条消息}}"
}

注意：在 ICU 格式中，变量名（如 count）、关键字（如 plural）、标识符（如 =0, =1, other）和特殊符号（如 #）都会被严格保护，只翻译显示文本部分。

4) 仅管理/更新快照

若你已将新英文放入 new/en/，仅想刷新快照而不翻译：

npx @alauda-fe/i18n-tools update-snapshot -s en

5) 自定义提示词与额外规则

所有翻译/语法检查类命令均支持：

# 自定义系统提示词
--custom-prompt ./prompts/translation.md

# 额外规则（会附加到默认规则后）
--extra-rules "按钮文案绝不加句号。保持 PVC/PVCs 不展开为全称。"

示例：

npx @alauda-fe/i18n-tools translate -s en -t ja \
	--custom-prompt ./prompts/ja.md \
	--extra-rules "UI 文案不加句号" \
	-k $OPENAI_API_KEY

命令参考（速查）

translate

翻译 JSON 文件（全量补齐缺失/null 的目标键）。

• 选项：
  • -s, --source 源语言目录，默认 en
  • -t, --target 目标语言目录（必填）
  • -k, --token Azure OpenAI Key（或用 OPENAI_API_KEY）
  • --custom-prompt 自定义系统提示词
  • --extra-rules 附加规则

incremental-translate

基于 new/<source> 与 snapshot/<source> 的差异增量翻译，输出至 src/<target>，并更新 snapshot/<source>，随后删除 new/。

• 选项同 translate，另：
  • -s 默认为 en，-t 需指定如 zh

retry-failed

重试目标目录中值为 null 的条目（之前因校验失败或限流导致）。

• 选项同 translate

grammar-check

检查并修正英文 JSON 的语法/拼写。

• 选项：
  • -f, --file 需要检查的 .json 文件
  • -k, --token Azure OpenAI Key
  • --dry-run 预览，不落盘
  • --custom-prompt / --extra-rules 同上

batch-grammar-check

批量检查目录下所有 JSON 文件。

• 选项：
  • -d, --dir 目录路径
  • --parallel 并行数量（1-10），默认 1
  • 其余同 grammar-check

sync

从配置的 GitLab/GitHub 仓库下载英文源 JSON 到 new/en/。

• 选项：
  • -r, --repo 指定仓库名（可多次）
  • -l, --level 过滤 level（默认 core）
  • -b, --branch 指定分支
  • -t, --token 访问令牌（或设置 GITLAB_TOKEN/GITHUB_TOKEN）

说明：自动根据仓库类型优先使用对应环境变量；公开仓库可不提供令牌。

update-snapshot

将 new/<source> 的文件复制到 snapshot/<source>。

重要校验与保护

• 占位符保护：{{var}}、${var} 原样保留；若翻译后占位符集合不一致，则该条目置为 null 以待重试/人工处理
• 技术术语/标点保护：Kubernetes、Docker、PVC/PVCs、Load Balancer 等严格按原文格式；UI 文案不强加句号
• 注释和值跳过：值以 // 开头的注释项、以 _en 结尾的键、空字符串值会被跳过

日志与排错

• 错误日志：
  • 翻译：translate_errors.log
  • 语法检查：grammar_check_errors.log
• 常见问题：
  • 401/403：检查 OPENAI_API_KEY 或 GitLab/GitHub 令牌权限
  • 429 限流：工具会等待后重试；多次失败可稍后再试
  • 条目为 null：多因占位符校验失败或 API 出错，可用 retry-failed 补齐

提示

• Node 进程需能够访问 Azure OpenAI 与 GitLab/GitHub 网络
• 推荐在提交前对 src/<目标语言> 做一次抽查，并关注日志中“修改/失败”统计

如需优化提示词或术语策略，可参考仓库内 PROMPTS_OPTIMIZATION.md、TECH_TERMS_GUIDE.md 与 CUSTOM_PROMPTS_GUIDE.md。