plan-glossary.md

# Skill — 执行计划与术语表生成

## 职责

基于扫描报告和分析报告，提取高频词汇生成术语表，按功能模块组织翻译内容，生成可执行的本地化计划。

## 前置条件

- `i18n/scan_report.json` 已生成（来自扫描分析阶段）
- `i18n/analysis_report.json` 已生成
- `i18n-config.json` 中已配置目标语言

## 执行步骤

### 步骤 1：读取扫描报告和分析报告

1. 读取 `i18n/scan_report.json`，获取所有文本条目（以及图片条目，如果 `translateImages` 为 `true`）
2. 读取 `i18n/analysis_report.json`，获取项目结构和模块分组信息
3. 读取 `i18n-config.json`，获取目标语言列表

### 步骤 2：术语提取与术语表生成

#### 2a. 词频分析

从所有文本条目（如果 `translateImages` 为 `true`，还包括图片 OCR 结果）中提取高频词汇：

1. **分词处理**：对所有中文文本进行分词
   - 游戏常见术语：金币、钻石、体力、经验、等级、血量、攻击、防御、技能、装备、道具等
   - UI 常见词汇：确认、取消、返回、设置、商城、背包、任务、成就等
   - 动词短语：获得、消耗、升级、解锁、购买、开始、结束等

2. **统计词频**：计算每个词汇出现的频次
3. **筛选高频词**：选取频次 >= 2 的词汇作为术语候选

#### 2b. 生成术语表草案

为每个高频词汇生成翻译建议：

```json
{
  "version": "1.0",
  "sourceLanguage": "zh-CN",
  "targetLanguage": "en",
  "generatedAt": "2026-04-02T16:30:00Z",
  "entries": [
    {
      "id": "term_001",
      "source": "金币",
      "target": "Gold",
      "alternatives": ["Coins", "Gold Coins"],
      "context": "游戏内主要货币",
      "frequency": 23,
      "category": "currency",
      "approved": false,
      "sources": ["assets/Scripts/ShopManager.ts", "assets/Scripts/RewardManager.ts"]
    }
  ]
}
```

翻译原则：
- **游戏行业惯例**：使用游戏行业通用的翻译（如 HP, MP, EXP 等）
- **简洁优先**：游戏 UI 空间有限，尽量使用简短的翻译
- **一致性**：同一概念必须使用相同翻译
- **上下文适配**：根据游戏类型选择合适的翻译风格
  - 休闲游戏：轻松友好
  - RPG：严肃史诗风
  - 策略游戏：专业精确

#### 2c. 特殊术语处理

1. **专有名词**：角色名、地名、技能名等可能需要音译或保留原文
2. **数字相关**：如 "1级"、"第3关" 中的中文部分
3. **复合术语**：如 "攻击力"、"暴击率" 等复合词需要整体翻译
4. **缩写惯例**：如 "ATK"(攻击)、"DEF"(防御) 等游戏中常见的缩写

### 步骤 3：按功能模块分组

基于分析报告的模块信息，将所有文本条目按功能模块分组：

| 模块 | 说明 | 典型文件 |
|------|------|----------|
| **UI标签** | 按钮文本、标题、标签页 | UI 相关脚本、Scene 文件 |
| **战斗** | 战斗提示、伤害数字、状态描述 | Battle 相关脚本 |
| **教程** | 新手引导、提示文本 | Tutorial/Guide 脚本 |
| **设置** | 设置选项、说明文本 | Settings 脚本 |
| **技能描述** | 技能名称、效果描述 | Skill/Ability 脚本 |
| **商城** | 商品名称、价格描述、购买提示 | Shop 脚本 |
| **对话/剧情** | NPC 对话、剧情文本 | Dialog/Story 脚本 |
| **成就/任务** | 任务描述、成就条件 | Achievement/Quest 脚本 |
| **通知/弹窗** | 系统通知、弹窗提示 | Notification/Popup 脚本 |
| **其他** | 无法归类的文本 | — |

分组策略：
1. 先根据文件路径和文件名推断模块归属
2. 再根据文本内容关键词辅助分类
3. 无法确定的归入"其他"

### 步骤 4：生成本地化执行计划

生成 `i18n/i18n_plan.md`，包含分步执行计划。

**关键要求**：执行计划中所有步骤的条目 ID 列表合并后，必须覆盖 scan_report.json 中的全部 TextEntry。不允许遗漏。

执行计划原则：
1. **每步有明确的 ID 列表**：可以通过 ID 回溯到 scan_report 中的具体条目
2. **每步有完成标准**：可量化验证是否完成
3. **先核心后外围**：UI标签 > 游戏核心 > 教程/设置 > 图片（仅 `translateImages` 为 `true` 时包含图片步骤）
4. **同模块内相关文本一起处理**：确保上下文一致性
5. **拼接字符串单独标注**：在注意事项中提醒处理方式

### 步骤 5：保存产物

1. 将术语表保存到 `{projectRoot}/i18n/glossary.json`
2. 将执行计划保存到 `{projectRoot}/i18n/i18n_plan.md`

### 步骤 5b：自检（保存后、请求确认前）

**⚠️ 保存产物后，必须执行以下检查。任何一项不通过都必须修正后重新保存。**

**验证上游产物（阶段 1）：**

| 检查项 | 验证方法 | 不通过时 |
|--------|----------|----------|
| 扫描报告存在 | `i18n/scan_report.json` 文件存在且可解析 | 回到阶段 1 |
| 分析报告存在 | `i18n/analysis_report.json` 文件存在且可解析 | 回到阶段 1 |

**验证本阶段产物：**

| 检查项 | 验证方法 | 不通过时 |
|--------|----------|----------|
| 术语表存在 | `i18n/glossary.json` 文件存在且可解析 | 回到步骤 2 重新生成 |
| 术语表不为空 | `entries` 数组长度 > 0 | 回到步骤 2 |
| 术语表字段完整 | 每个 entry 都有 `source`、`target`、`frequency` | 补全缺失字段 |
| 执行计划存在 | `i18n/i18n_plan.md` 文件存在且非空 | 回到步骤 4 重新生成 |
| 全覆盖校验 | 执行计划中所有步骤涉及的条目 ID 总数 == `scan_report.json` 的 `summary.totalTextEntries` | 补全遗漏的条目 |

全部通过后进入步骤 6。

### 步骤 6：请求用户确认

输出摘要并请求用户确认：

```
📋 执行计划和术语表已生成！

术语表统计：
  - 总术语数：N 条

执行计划统计：
  - 总步骤：X 步
  - 文本翻译：Y 条（全覆盖）
  - 图片翻译：Z 张             ← 仅 translateImages 为 true 时显示

📖 请查看并确认：
  - 术语表：i18n/glossary.json
  - 执行计划：i18n/i18n_plan.md

⚠️ 确认后将一次性完成翻译、替换和验证，无需再次确认。
```

## 关键注意事项

1. **术语表的准确性至关重要**：它将约束后续所有翻译的用词，一旦确认就会贯穿整个翻译流程
2. **多义词处理**：同一个中文词在不同上下文可能有不同翻译，需在术语表中通过 `context` 字段区分
3. **品牌名/角色名**：这类专有名词最好由用户确认，不要擅自翻译
4. **执行计划的粒度**：每步不宜过大（建议 < 50 条），便于逐步执行和验证
5. **全覆盖校验**：生成执行计划后，统计所有步骤涉及的条目 ID 总数，确认 == scan_report 的 totalTextEntries