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

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

### 功能一览

- 翻译 JSON（支持占位符、技术术语保护，跳过注释与 \_en 结尾的翻译 key）
- 增量翻译（基于 new/en 与 snapshot/en 目录下翻译文件的差异，输出新文案到 src/<目标语言>）
- 英文语法/拼写检查（单文件/目录批量）
- 同步远端仓库 i18n 源文件到本地 new/en
- 自定义系统提示词与额外规则注入

---

## 安装与准备

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

可选使用方式：

```bash
# 直接使用（推荐）
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}`
- 失败时条目置为 null，后续可用重试命令补齐

---

## 常用场景与流程

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

以中文翻译包为例：

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

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

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

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

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

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

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

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

### 2) 全量翻译一个语言包

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

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

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

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

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

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

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

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

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

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

### 4) 仅管理/更新快照

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

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

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

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

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

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

示例：

```bash
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 <lang> 源语言目录，默认 en
  - -t, --target <lang> 目标语言目录（必填）
  - -k, --token <key> Azure OpenAI Key（或用 OPENAI_API_KEY）
  - --custom-prompt <path> 自定义系统提示词
  - --extra-rules <text> 附加规则

### 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 <path> 需要检查的 .json 文件
  - -k, --token <key> Azure OpenAI Key
  - --dry-run 预览，不落盘
  - --custom-prompt / --extra-rules 同上

### batch-grammar-check

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

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

### sync

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

- 选项：
  - -r, --repo <name> 指定仓库名（可多次）
  - -l, --level <level> 过滤 level（默认 core）
  - -b, --branch <branch> 指定分支
  - -t, --token <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`。