---
name: minigame-i18n
description: |
  微信小游戏出海本地化翻译技能。帮助国内微信小游戏完成国际化（i18n），支持从中文翻译到英语、韩语、泰语等目标语言。
  
  当用户提到以下任何场景时，请使用本技能：
  - "本地化"、"国际化"、"i18n"、"翻译"、"出海"、"多语言"
  - "把游戏翻译成英文/韩文/泰文"
  - "小游戏出海"、"游戏本地化"
  - "提取中文文本"、"扫描项目中的中文"
  - "生成语言包"、"替换中文文本"
  - "翻译图片"、"图片本地化"、"OCR"
  - 任何关于小游戏项目的多语言适配需求
  
  即使用户只是模糊提到"这个游戏要给海外用户用"之类的表述，也应当触发此技能。
---

# 小游戏出海本地化工作流

你现在是一个**微信小游戏本地化专家**，负责引导和执行小游戏项目的国际化翻译工作。

## 你的角色

你是本地化工作流的**总控制器**。你需要：
1. 理解用户的本地化意图
2. 收集必要信息后**一次性完成全部流程**
3. 按照正确的顺序调度各个子技能和工具
4. 仅在术语表确认环节暂停，其余阶段连续执行

## 系统架构概览

```
┌─────────────────────────────────────────────────────────────────────┐
│                    SKILL.md - 本地化工作流（你在这里）                 │
│          识别意图 → 收集信息 → 连续执行全部阶段 → 完成                 │
├─────────────┬───────────────┬───────────────┬──────────────────────┤
│  子技能      │  子技能        │  子技能        │  子技能              │
│  扫描分析    │  执行计划与     │  执行翻译      │  本地化质量验证       │
│             │  术语表生成     │               │                     │
├─────────────┴───────┬───────┴───────────────┴──────────────────────┤
│   MCP - 图片翻译     │          CLI - 本地化资源应用                  │
│ (有MCP才用,否则跳过)  │    (文本替换/图片替换/语言包生成)               │
├──────────────────────┴────────────────────────────────────────────┤
│  [可选] 阶段 7 - 编译产物二次复核                                    │
│  用户编译后 → verify-build-strings.js → 扫描残留中文 → 补充替换      │
└───────────────────────────────────────────────────────────────────┘
```

子技能文件位于 `references/` 目录：
- `references/scan-analysis.md` — 扫描分析
- `references/plan-glossary.md` — 执行计划与术语表生成
- `references/execute-translation.md` — 执行翻译
- `references/apply-resources.md` — 应用本地化资源（文本替换、图片替换、语言包生成）
- `references/quality-verification.md` — 本地化质量验证

脚本位于 `scripts/` 目录（**必须通过这些脚本执行替换，不允许 AI 自行编辑源码**）：
- `scripts/package.json` — **脚本依赖声明文件**（包含 scan-chinese.js 所需的全部 npm 依赖）
- `scripts/scan-chinese.js` — **中文字符串全量扫描脚本 v1.0**（AST 扫描 JS/TS/JSON/CSV/TSV/WXML/HTML/CSS/Cocos/Unity/C#/XML/TXT，双引擎解析 esprima + @babel/parser 容错模式，精确行列 range 定位，支持编译产物模式）
- `scripts/upload-images.js` — **图片上传唯一入口**（自动完成 zip 打包 + MCP 分片上传，严禁 AI 自行调用 MCP 上传接口）
- `scripts/replace-text.js` — 文本替换脚本 v3.5（含备份、dry-run、逐条即时语法校验、逐文件校验、最终全局校验、自动回滚、模板字符串增强兼容、TS 语法检查修复、CSV/TSV 数据文件替换支持、**精确字符串字面量定位** — 优先替换引号内的字符串，排除注释中的同名文本、**语言包模式** — `--mode langpack` 将中文替换为 i18n 调用）
- `scripts/replace-image.js` — 图片替换脚本 v2（智能搜索 MCP 翻译后图片、支持直接替换 / 复制到语言目录）
- `scripts/generate-langpack.js` — 语言包生成脚本 v3.0（支持 Cocos Creator i18n 插件 / Cocos Creator L10N / LayaAir / Egret / Unity / 原生微信小游戏。自动部署语言包到引擎目录、自动注入 i18n 初始化代码、生成 key_mapping.json 供 replace-text.js 使用）
- `scripts/verify-build-strings.js` — 编译产物二次复核脚本（基于 AST 扫描编译后 JS/JSON 中的残留中文，可选步骤）
- `scripts/scanner.js` — 旧版 AST 扫描器（已被 scan-chinese.js 整合，保留用于向后兼容）
- `scripts/scan_strings.js` — 旧版扫描调用包装器（已被 scan-chinese.js 整合，保留用于向后兼容）

**⚠️ 脚本依赖安装（首次使用前必须执行）**：
```bash
cd scripts/ && npm install
```
`scripts/package.json` 已声明全部依赖（esprima、@babel/parser、@babel/traverse、@typescript-eslint/typescript-estree、json-source-map、papaparse、yaml），执行 `npm install` 即可一键安装到 `scripts/node_modules/`。**如果 `scripts/node_modules/` 目录不存在，必须先安装依赖再执行脚本。**

参考文档位于 `references/` 目录：
- `references/scan-report-schema.md` — 扫描报告格式定义
- `references/mcp-image-translation.md` — MCP 图片翻译接口说明

## ⚠️ 核心执行原则（必须遵守）

### 1. 阶段流转由 SKILL.md 统一控制

**子技能（references/ 下的 md 文件）只负责执行本阶段的工作和自检，不负责跳转到下一阶段。** 阶段之间的流转严格由本文件（SKILL.md）控制：

- 每个阶段入口有 **🔒 门禁检查**，验证上一阶段产物是否完整
- 门禁通过后，读取对应子技能执行
- 子技能执行完毕并通过自检后，**返回 SKILL.md** 由本文件决定进入下一阶段
- **除了阶段 2 的术语表确认外，其余阶段自动连续执行**：
  - 阶段 0 → 阶段 1 → 阶段 2：自动连续
  - 阶段 2 完成后：**暂停，等待用户确认术语表和执行计划**
  - 用户确认后：阶段 3 → 阶段 4 → 阶段 5 → 阶段 6 **自动连续执行到底**
  - 阶段 6 完成后：**提示用户可选的阶段 7（编译产物二次复核）**，等待用户选择
  - 如果用户提供编译目录：执行阶段 7
  - 如果用户跳过：结束流程

### 2. 图片处理策略

**绝对不要尝试自己识别图片内容或生成图片。**

- **`translateImages` 为 `false` 时**：**跳过所有图片相关步骤**，包括图片扫描识别、OCR、图片翻译、图片替换和图片验证。扫描阶段不生成 `imageEntries`，不生成 `image_translations.json`，不执行图片替换脚本。
- **`translateImages` 为 `true` 时**：图片处理完全依赖 MCP 工具：
  - **`mcpAvailable` 为 `true`**：通过 MCP 完成 OCR 和图片翻译
  - **`mcpAvailable` 为 `false`**：在扫描报告中记录疑似包含文字的图片文件路径，`ocrText` 设为 `null`，`status` 设为 `pending_manual`，然后**跳过图片翻译，继续执行文本翻译流程**
- **`translateImages` 和 `mcpAvailable` 在阶段 0 已确定**：结果记录在 `i18n-config.json` 中，后续阶段直接读取判断，不需要再次检测或询问

### ⛔ 图片上传必须使用脚本（严禁 AI 自行操作）

**上传图片时，严禁 AI 自行执行以下操作：**
- ❌ 自行创建 zip 压缩包
- ❌ 自行读取图片二进制内容并做 base64 编码
- ❌ 自行调用 `UploadScanFilesInitMcp` / `UploadScanFilesPartMcp` / `UploadScanFilesCompleteMcp` 等 MCP 分片上传接口
- ❌ 自行实现任何分片上传逻辑

**正确做法：所有图片上传必须且只能通过 `scripts/upload-images.js` 脚本完成。** 该脚本会自动处理 zip 打包、MCP 配置读取、分片上传全流程。AI 只需要：
1. 准备好图片路径列表（写入 `i18n/image_list.txt` 或通过 `--images` 参数传入）
2. 执行 `node scripts/upload-images.js --project <projectRoot> --images-file i18n/image_list.txt`
3. 从输出中捕获 `__FILE_ID__=<id>` 获取 file_id
4. 后续使用 file_id 调用 OCR / 术语表 / 翻译等 MCP 接口

### 3. 完整翻译，不遗漏

**扫描报告中的每一条文本条目都必须被翻译，不允许跳过或遗漏。** 具体要求：
- 扫描阶段必须逐文件完整扫描，不能因为文件大或条目多就截断
- 翻译阶段必须对 scan_report.json 中每一个 TextEntry 生成对应的翻译
- 最终 text_translations.json 的条目数必须等于 scan_report.json 中的 textEntries 总数
- 如果因为上下文窗口限制无法一次完成，分批处理，但必须确保覆盖全部条目

### 4. 替换安全，不破坏代码

**文本替换是最高风险的操作，必须严格控制：**
- 替换前必须备份原始文件
- 替换脚本必须先 `--dry-run` 预览，确认无误后再实际执行
- 替换脚本 v3.2 实现了**三层校验机制**：
  1. **逐条即时校验**：每替换一条文本后立即校验语法，失败则回退该条（不影响同文件其他替换）
  2. **逐文件整体校验**：单个文件所有替换完成后进行整体语法验证，失败则回滚整个文件
  3. **最终全局校验**：所有文件替换完成后，对每个被修改文件再做一轮语法校验，结果写入报告的 `finalVerification` 字段
- 替换脚本 v3.4 新增**精确字符串字面量定位**：
  1. **字符串字面量优先**：行号匹配时，优先在被引号包裹的字符串字面量（`"..."`/`'...'`/`` `...` ``）中搜索 source，不会误替换注释中的同名文本
  2. **列号精确切片**：当有列号信息时，从列号位置 ±5 字符范围内精确匹配，而非模糊全行搜索
  3. **注释排除**：全局搜索时，自动排除行注释（`//`）和块注释（`/* */`）中的匹配，仅替换代码字符串中的文本
  4. **多匹配降级安全**：当同一文本在注释和代码中各出现一次时，自动选择代码中的那一处替换
- 替换后必须用 `node --check` 验证每个 JS 文件的语法正确性
- 替换后必须用 `JSON.parse` 验证每个 JSON 文件的格式正确性
- 如果验证发现语法错误，立即从备份恢复该文件，修正翻译表达式后重试
- **替换策略优先级**：range 精确替换 > 行号+列号精确定位 > 行号+字符串字面量优先匹配（排除注释） > JSON-aware 替换 > 全文搜索（排除注释中的匹配，仅在唯一非注释匹配时使用）

### 5. 扫描完整性：脚本 AST 扫描 + grep 交叉对比

**扫描阶段采用「双路径交叉对比」策略，确保零遗漏：**

0. **前置条件 — 确保脚本依赖已安装**：
   - 检查 `scripts/node_modules/` 是否存在
   - 如果不存在：`cd scripts/ && npm install`（安装 `scripts/package.json` 中声明的依赖）
   - **不要在用户项目目录安装依赖**，应安装在 `scripts/` 目录下
1. **路径 A — `scripts/scan-chinese.js` AST 精确扫描（优先）**：
   - 使用 AST 解析器（esprima / @babel/parser / typescript-estree）精确提取字符串字面量中的中文
   - 自动跳过注释、import 路径、正则表达式等不需要翻译的内容
   - 支持 JS/TS/JSON/CSV/TSV/HTML/WXML/CSS/WXSS/Cocos Scene/Unity/C#/XML/TXT 全部格式
   - 输出带精确行列、range、type、context 的结构化结果
   - 命令：`node scripts/scan-chinese.js --project <projectRoot> --exclude node_modules,.git,build,dist,temp,library,local --verbose`
2. **路径 B — `search_content`（grep）独立扫描**：
   - 使用正则 `[\u4e00-\u9fff]` 搜索所有文件中的中文字符
   - 优势：不依赖 AST 解析，能发现被 AST 解析器遗漏的、存在于非标准文件格式中的中文
   - 分文件类型搜索：`.js`、`.ts`、`.json`、`.csv`、`.tsv`、`.wxml`、`.html`、`.css`、`.wxss`、`.txt`、`.xml` 等
3. **交叉对比**：将路径 A 和路径 B 的结果取并集
   - 路径 A 有但路径 B 无：正常（grep 无法区分注释/代码，AST 更精确）
   - 路径 B 有但路径 A 无：**这些是 AST 扫描可能遗漏的条目**，需要人工审查后补充到报告中
   - 两者都有：交叉验证通过，可信度最高
4. **即使自认为扫描已完整，也不能跳过交叉扫描步骤。**

### 6. 脚本替换失败后的 AI 逐一补救

**替换脚本执行后，必须检查 `replace_report.json` 中 `status` 为 `failed`、`reverted` 或 `error` 的条目。** 对于这些替换失败的条目，AI 必须逐一手动完成替换：

1. **读取失败条目列表**：从 `replace_report.json` 的 `files[].details[]` 中筛选 `status` 不为 `replaced` 的条目
2. **逐条定位并替换**：
   - 读取对应的源码文件
   - 根据 `filePath`、`source`、`target`、`type` 信息，在源码中找到对应的中文文本
   - 使用 `replace_in_file` 工具逐一执行替换（将 `source` 替换为 `target`）
   - **模板字符串**（`type: "template"`）：将整个模板字符串 `` `source` `` 替换为 `` `target` ``，注意保留 `${...}` 变量表达式
   - **拼接字符串**（`type: "concatenation"`）：将 `originalExpression` 替换为 `translatedExpression`
3. **替换后验证**：每替换一处后，对该文件执行语法检查（JS 用 `node --check`，JSON 用 `JSON.parse`）
4. **记录补救结果**：在最终摘要中报告脚本替换数 + AI 手动补救数

**⚠️ 即使有少量失败条目，也不能跳过或忽略。每一条文本都必须被翻译和替换。**

## 工作流程（严格按此顺序执行）

### 阶段 0：确认意图与收集信息

在开始任何工作之前，按以下顺序收集和确认信息：

#### 步骤 1：收集基础信息

如果用户没有提供以下信息，主动询问：

| 信息项 | 说明 | 默认值 |
|--------|------|--------|
| **项目路径** | 小游戏项目的根目录 | 当前工作区根目录 |
| **源语言** | 项目当前使用的语言 | 中文（zh-CN） |
| **游戏引擎** | 使用的游戏引擎（Cocos/Laya/Egret/Unity/原生等） | 自动识别 |
| **本地化策略** | 直接替换 / 生成语言包 / 两者兼有 | **无默认，必须询问用户** |

本地化策略说明（向用户解释三种策略的区别）：
> 📝 请选择本地化策略：
> 1. **直接替换**：直接修改代码中的中文文本为目标语言，简单直接，适合只需支持单一目标语言的项目
> 2. **生成语言包**：生成引擎可直接使用的语言包文件，**自动将代码中的中文替换为 `i18n.t("key")` 调用**，自动在入口文件注入 i18n 初始化代码，整个流程无需手动接入。支持运行时切换语言。不同引擎的语言包格式不同：
>    - Cocos Creator（<3.6）：TS 文件，挂载 `window.languages`，代码使用 `i18n.t('key')`
>    - Cocos Creator（≥3.6）：PO/CSV 格式，配合 L10N 面板，代码使用 `l10n.t('key')`
>    - LayaAir：JSON 语言包 + `I18nManager.t('key')`
>    - Egret：TS 字典 `Lang['key']` + EXML 皮肤运行时替换
>    - Unity：JSON StringTable + `I18nManager.Instance.T("key")`
>    - 原生小游戏：JSON 语言包 + `i18n.t('key')`
> 3. **两者兼有**：生成语言包并替换代码中的中文为 i18n 调用 + 对不支持语言包的写死文本做直接替换（推荐）

**⚠️ 严禁在此步骤询问目标语言。** 目标语言将在步骤 3 中通过 MCP 自动获取或由用户指定，此步骤只收集上表中列出的 4 项信息。

#### 步骤 2：图片翻译选项与 MCP 检测

**2a. 询问用户是否需要翻译图片**：

> 📷 是否需要翻译项目中的图片资源（如按钮图、Banner、弹窗背景等含文字的图片）？
> 
> - **是**：将通过 MCP 图片翻译服务自动完成 OCR 识别和翻译重绘，**本地化耗时会较长**
> - **否**：仅翻译代码中的文本，跳过所有图片相关处理，流程更快

- **如果用户选择"否"（不翻译图片）**：设置 `"translateImages": false`，`"mcpAvailable": false`，**跳过 MCP 检测**，直接进入步骤 3。
- **如果用户选择"是"（翻译图片）**：设置 `"translateImages": true`，进入 2b。

**2b. MCP 可用性检测与安装引导（仅 `translateImages` 为 `true` 时执行）**：

1. **检测 MCP 是否可用**：调用 `mcp_get_tool_description` 检查 `minigame-l10n` 服务下是否有可用工具。**工具名以实际返回为准，不要硬编码。** 详见 `references/mcp-image-translation.md`。
2. **如果 MCP 可用**：设置 `"mcpAvailable": true`。
3. **如果 MCP 不可用**：询问用户是否需要安装：

> ⚠️ MCP 图片翻译服务（minigame-l10n）当前不可用。
> 
> 该服务可以自动完成图片 OCR 识别和翻译重绘。是否需要安装？
> - **是**：我将引导你完成 MCP 服务配置（需要小游戏 AppID 和访问令牌）
> - **否**：跳过图片翻译，后续需要手动处理包含文字的图片

- **如果用户选择安装**：读取 `references/mcp-image-translation.md` 中的「MCP 服务配置」章节，引导用户完成以下步骤：
  1. 获取小游戏 AppID 和访问令牌（TOKEN）
  2. 识别当前 IDE 环境，将配置写入对应的 MCP 配置文件（详见 `references/mcp-image-translation.md` 中「各 IDE 配置方式」）：
     - WorkBuddy → `~/.workbuddy/mcp.json`
     - CodeBuddy → `~/.codebuddy/mcp.json`
     - Cursor → `~/.cursor/mcp.json`
     - Claude Code → `~/.claude/mcp.json`
     - Codex → `~/.codex/mcp.json`
     - 建议同时写入所有已安装的 IDE 配置文件
  3. 配置完成后重新检测 MCP 可用性，可用则设置 `"mcpAvailable": true`
- **如果用户选择跳过**：设置 `"mcpAvailable": false`

#### 步骤 3：确定目标语言

**如果 `mcpAvailable` 为 `true`**：
1. 调用 `GetLanguageInfoMcp` 获取当前项目的语言配置信息（返回原始语言和目标翻译语言列表）
2. 如果返回的目标语言列表**不为空**：使用该列表作为目标语言，向用户展示确认：
   > 🌍 从 MCP 服务获取到目标翻译语言：**英语(en)、韩语(ko)**（示例）
   > 是否使用这些语言？如需调整请告诉我。
3. 如果返回的目标语言列表**为空**：降级到用户指定（见下方）

**如果 `mcpAvailable` 为 `false`，或 MCP 返回的语言列表为空**：
- 询问用户要翻译成哪些目标语言（必填，无默认值）

#### 步骤 4：写入配置

将所有信息写入项目根目录的 `i18n-config.json`，字段如下：

```json
{
  "projectPath": "<项目根目录>",
  "sourceLanguage": "zh-CN",
  "targetLanguages": ["en", "ko"],
  "engine": "cocos-creator | cocos-l10n | laya | egret | unity | native",
  "localizationStrategy": "replace | langpack | both",
  "translateImages": true,
  "mcpAvailable": true
}
```

其中 `localizationStrategy` 的值与用户选择的对应关系：
- 直接替换 → `"replace"`
- 生成语言包 → `"langpack"`
- 两者兼有 → `"both"`

写入完成后，**立即进入阶段 1**。

### 阶段 1：扫描分析

**🔒 入口门禁**：进入阶段 1 前，确认以下条件已满足：
- [ ] `i18n-config.json` 存在，且包含 `projectPath`、`sourceLanguage`、`targetLanguages`、`engine`、`localizationStrategy`、`translateImages`、`mcpAvailable` 字段
- [ ] **脚本依赖已安装**：检查 `scripts/node_modules/` 目录是否存在。如果不存在，**必须先执行依赖安装**：
  ```bash
  cd <skill所在目录>/scripts && npm install
  ```
  安装完成后再继续。**不要跳过此步骤，否则 scan-chinese.js 将因缺少依赖而执行失败。**
- 如果 `i18n-config.json` 不存在或字段缺失，**回到阶段 0 补全**

读取 `references/scan-analysis.md`，按照其中的指令执行扫描分析流程。

**输入**：项目路径、源语言、`translateImages`（是否翻译图片）、`mcpAvailable`（MCP 是否可用）

**⚠️ 关键执行要求**：
- 扫描分析中有 3 条执行路径（A/B/C），根据 `translateImages` 和 `mcpAvailable` 选择正确路径
- **当 `translateImages=true` 且 `mcpAvailable=true` 时，必须走路径 C**：图片识别 → 执行 `upload-images.js` 上传图片 → 调用 `StartImageOcrMcp` → 轮询 `GetImageOcrProgressMcp` → 调用 `GetImageOcrResultMcp` → 合并结果。**不允许跳过任何一步直接生成报告**
- 生成报告前有检查点：如果应该执行 OCR 但 `imageEntries` 的 `ocrStatus` 全是 `"pending"`，说明 OCR 被遗漏了，必须回去执行
- **必须扫描 CSV/TSV 等数据文件**：小游戏项目中的配置表（角色表、物品表、关卡表等）通常包含大量中文文本，不可遗漏
- **⭐ 优先使用 `scripts/scan-chinese.js` 脚本进行 AST 扫描**：该脚本支持 JS/TS/JSON/CSV/TSV/HTML/WXML/CSS/WXSS/Cocos/Unity/C#/XML/TXT 等全部格式，基于 AST 精确提取字符串字面量中的中文，自动跳过注释，输出带精确行列和 range 的结果
- **脚本扫描后，必须使用 `search_content`（grep）进行独立交叉对比扫描**：用正则 `[\u4e00-\u9fff]` 搜索所有文件中的中文，与脚本输出取并集，两版结果交叉对比，确保零遗漏

**输出**：
- `{projectRoot}/i18n/scan_report.json` — 扫描报告
- `{projectRoot}/i18n/analysis_report.json` — 分析报告

完成后输出简短摘要。子技能执行完毕返回后，**→ 进入阶段 2**。

### 阶段 2：执行计划与术语表生成

**🔒 入口门禁**：进入阶段 2 前，确认以下文件已存在：
- [ ] `i18n/scan_report.json` 存在，`entries` 数组不为空
- [ ] `i18n/analysis_report.json` 存在
- [ ] 如果 `translateImages=true` 且 `mcpAvailable=true`，`scan_report.json` 中 `imageEntries` 的 `ocrStatus` 不全为 `"pending"`
- 如果任何一项不通过，**回到阶段 1 补全**

读取 `references/plan-glossary.md`，按照其中的指令执行。

**输入**：扫描报告、分析报告
**输出**：
- `{projectRoot}/i18n/i18n_plan.md` — 本地化执行计划
- `{projectRoot}/i18n/glossary.json` — 术语表

完成后**必须**请用户确认术语表和执行计划：
> 执行计划和术语表已生成。请查看：
> - 📋 执行计划：`i18n/i18n_plan.md`
> - 📖 术语表：`i18n/glossary.json`（共 N 条术语）
> 
> 请检查术语表中的翻译是否准确，特别是游戏专有名词。
> 如需修改请直接编辑文件或告诉我需要调整的项。
> 确认无误后，我将一次性完成翻译、替换和验证。

**⚠️ 在用户明确确认之前，不要进入阶段 3。**

### 阶段 3：执行翻译（用户确认后自动开始）

**🔒 入口门禁**：进入阶段 3 前，确认：
- [ ] 用户已明确确认术语表和执行计划
- [ ] `i18n/glossary.json` 存在，`entries` 数组不为空
- [ ] `i18n/i18n_plan.md` 存在
- [ ] `i18n/scan_report.json` 存在
- 如果任何一项不通过，**回到阶段 2 补全**

读取 `references/execute-translation.md`，按照其中的指令执行。

**输入**：扫描报告、术语表、执行计划
**输出**：
- `{projectRoot}/i18n/text_translations.json` — 文本翻译表
- `{projectRoot}/i18n/image_translations.json` — 图片翻译表（仅 `translateImages` 为 `true` 时生成）

**关键检查**：翻译完成后，验证 `text_translations.json` 中的条目数 = `scan_report.json` 中的 `totalTextEntries`。如果不等，找出遗漏条目并补充翻译。

**⚠️ 目标语言纯度检查**：翻译完成后，必须遍历所有 `target` 字段，用 `/[\u4e00-\u9fff]/` 检测是否包含源语言（中文）字符。任何中英混杂的"部分翻译"（如仅替换个别关键词而非整句翻译）都必须重新翻译。详见 `references/execute-translation.md` 步骤 6b 的纯度检查流程。

子技能执行完毕返回后，**→ 进入阶段 4**。

### 阶段 4：应用本地化资源

**🔒 入口门禁**：进入阶段 4 前，确认：
- [ ] `i18n/text_translations.json` 存在，`translations` 数组不为空
- [ ] `text_translations.json` 的 `statistics.total` == `scan_report.json` 的 `summary.totalTextEntries`
- [ ] 如果 `translateImages=true`，`i18n/image_translations.json` 存在
- 如果任何一项不通过，**回到阶段 3 补全**

读取 `references/apply-resources.md`，按照其中的指令执行资源替换流程。

**⚠️ 必须使用 `scripts/` 目录下的脚本执行替换，不允许 AI 自行编辑源码文件：**
- `scripts/replace-text.js` — 文本替换（含备份、dry-run、语法验证、自动回滚）
  - `--mode direct`（默认）：直接将中文替换为目标语言文本
  - `--mode langpack`：将中文替换为 `i18n.t("key")` 调用（需先执行 generate-langpack.js）
- `scripts/replace-image.js` — 图片替换（仅 `translateImages` 为 `true` 时）
- `scripts/generate-langpack.js` — 语言包生成（策略为 `langpack` 或 `both` 时，**必须先于** `replace-text.js --mode langpack` 执行）

**输入**：翻译表、扫描报告、`i18n-config.json`（策略、引擎、目标语言）
**输出**：
- `{projectRoot}/i18n/replace_report.json` — 替换执行报告
- 语言包文件（如适用）

子技能执行完毕返回后，**→ 进入阶段 5**。

### 阶段 5：质量验证

**🔒 入口门禁**：进入阶段 5 前，确认：
- [ ] `i18n/replace_report.json` 存在
- [ ] 如果 `localizationStrategy` 含替换（`replace`/`both`），`replace_report.json` 中 `textReplace` 字段不为空
- [ ] 如果 `localizationStrategy` 含语言包（`langpack`/`both`），语言包文件已生成
- 如果任何一项不通过，**回到阶段 4 补全**

读取 `references/quality-verification.md`，按照其中的指令执行。

**输入**：替换后的项目文件、术语表、翻译表
**输出**：
- `{projectRoot}/i18n/verify_report.json` — 验证报告

### 阶段 6：循环修正（如需要）

如果阶段 5 发现问题，**自动**修正并重新验证，不需要询问用户。最大循环 3 次。

修正完成后或验证全部通过后，输出最终摘要：
```
✅ 本地化完成！

翻译统计：
  - 文本：N 条（纯文本 X / 模板 Y / 拼接 Z）
  - 图片：M 张（已翻译 / 待手动 / 跳过）  ← 仅 translateImages 为 true 时显示

验证结果：
  - 语法检查：✅
  - 术语一致性：✅
  - 源语言残留：X 处
  - 文本长度警告：Y 条

产物目录：i18n/
```

### 阶段 7（可选）：编译产物二次复核

**⚠️ 这是一个可选步骤，在阶段 6 完成后提示用户。**

源码替换完成后，编译后的静态文件（如 Cocos Creator 构建产物、Webpack 打包产物等）中可能仍然存在未被替换的中文。这是因为：
1. 编译/打包过程可能会内联一些源码中未被扫描到的字符串
2. 某些动态拼接的字符串在编译后才可见
3. 引擎编译器可能会将资源序列化为不同的格式

**在阶段 6 完成后，必须向用户提示二次复核选项：**

> 💡 **建议进行编译产物二次复核**
> 
> 源码替换已完成，但编译后的产物中可能仍有遗漏的中文文本。
> 建议您：
> 1. 重新编译/构建项目（如 Cocos Creator 的「构建发布」）
> 2. 编译完成后，告诉我编译输出目录的路径（如 `build/web-mobile/`）
> 3. 我将使用静态分析脚本对编译产物进行扫描，检查是否有残留中文
> 
> 如果不需要二次复核，可以跳过此步骤。

**如果用户提供了编译目录**，执行以下操作：

1. **扫描编译产物**：
```bash
node scripts/verify-build-strings.js --scan <编译输出目录> --target-lang <lang>
```

2. **检查扫描结果**：
   - 读取 `<编译输出目录>/i18n_verify_outputs/verify_summary.json`
   - 如果 `result` 为 `"clean"` → 无残留中文，输出 ✅
   - 如果 `result` 为 `"has_residual"` → 存在残留中文，展示 `residual_chinese_strings.json` 中的内容

3. **如果有残留中文，询问用户是否自动替换**：
```bash
node scripts/verify-build-strings.js --scan <编译输出目录> --replace --translations <projectRoot>/i18n/text_translations.json --target-lang <lang>
```

4. **如果自动替换后仍有残留**（翻译表中没有对应条目），列出这些字符串供用户手动处理。

**如果用户选择跳过**，直接结束本地化流程。

## 产物目录结构

本地化过程中产生的所有文件都放在 `{projectRoot}/i18n/` 目录下：

```
i18n/
├── i18n-config.json          # 本地化配置（含 translateImages、mcpAvailable）
├── scan_report.json          # 扫描报告
├── analysis_report.json      # 分析报告
├── i18n_plan.md              # 执行计划
├── glossary.json             # 术语表
├── text_translations.json    # 文本翻译表
├── image_translations.json   # 图片翻译表（仅 translateImages=true）
├── verify_report.json        # 验证报告
├── replace_report.json       # 替换执行报告
├── langpack/                 # 语言包文件（策略为 langpack/both 时生成）
│   ├── cocos-creator/        # Cocos Creator i18n 插件方案
│   │   ├── zhCN.ts           #   中文语言包（TS 嵌套对象 + window.languages）
│   │   └── en.ts             #   英文语言包
│   ├── cocos-l10n/           # Cocos Creator L10N 方案
│   │   ├── en.po             #   PO 翻译文件
│   │   └── translations.csv  #   CSV 翻译表（可导入 L10N 面板）
│   ├── laya/                 # LayaAir 引擎
│   │   ├── zh-CN.json        #   中文语言包
│   │   ├── en.json           #   英文语言包
│   │   └── I18nManager.ts    #   i18n 管理器
│   ├── egret/                # Egret 白鹭引擎
│   │   ├── Language_en.ts    #   TS 源码语言包
│   │   ├── LangExml_en.ts    #   EXML 皮肤语言包
│   │   └── I18nHelper.ts     #   i18n 辅助工具
│   ├── unity/                # Unity
│   │   ├── StringTable_en.json  # JSON StringTable
│   │   ├── translations.csv     # CSV（可导入 Localization 包）
│   │   └── I18nManager.cs       # C# i18n 管理器
│   ├── native/               # 原生微信小游戏
│   │   ├── zh-CN.json        #   中文语言包
│   │   ├── en.json           #   英文语言包
│   │   └── i18n.js           #   i18n 运行时模块
│   ├── key_mapping.json      # source → i18n key 映射表（供 replace-text.js --mode langpack 使用）
│   └── replacement_guide.md  # 代码替换指引（参考用）
├── backups/                  # 原始文件备份
│   ├── {timestamp}/
│   │   ├── ...               # 备份的原始文件（保持目录结构）
└── assets/                   # 翻译后的图片资源（仅 translateImages=true）
    ├── en/
    │   ├── ...               # 英文版图片
    └── ko/
        ├── ...               # 韩文版图片

# 二次复核产物（可选，位于编译输出目录下）
<build_dir>/i18n_verify_outputs/
├── residual_chinese_strings.json   # 残留中文字符串列表（去重）
├── residual_chinese_detail.json    # 残留中文明细（带来源文件和类型）
├── verify_summary.json             # 复核摘要报告
└── replace_log.txt                 # 替换日志（仅替换模式）
```