@alauda-fe/i18n-tools/README.md

基于 Azure OpenAI 的 JSON i18n 文件翻译和英文语法检查工具集

## 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

可选使用方式：

```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}`、ICU Message Format
- 保护技术术语的原始格式和拼写
- 失败时条目置为 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
```

## 📋 模板格式示例

### 基础变量格式
```json
{
  "welcome": "Welcome to {{app_name}}!",
  "greeting": "Hello ${username}, today is ${date}",
  "path": "File saved to ${directory}/${filename}"
}
```

### ICU 复数格式
```json
{
  "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 选择格式
```json
{
  "pronoun": "{gender, select, male{he} female{she} other{they}}",
  "status": "{userStatus, select, online{Available} offline{Away} busy{Do not disturb} other{Unknown}}"
}
```

### ICU 格式化类型
```json
{
  "price": "Total: {amount, number, currency}",
  "progress": "Complete: {value, number, percent}",
  "created": "Created on {date, date, short}",
  "lastLogin": "Last login: {time, time, medium}"
}
```

### 复杂嵌套格式
```json
{
  "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}}"
}
```

### 翻译结果示例（英文→中文）
```json
// 原文
{
  "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/`，仅想刷新快照而不翻译：

```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`。