Skill: tencent-adm/minigame-i18n (version 1.0.1)

--- 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 # 替换日志（仅替换模式） ```

path: scripts/package.json
content: {
  "name": "minigame-i18n-scripts",
  "version": "1.0.0",
  "private": true,
  "description": "微信小游戏国际化工具脚本依赖",
  "dependencies": {
    "@babel/parser": "^7.24.0",
    "@babel/traverse": "^7.24.0",
    "@typescript-eslint/typescript-estree": "^7.0.0",
    "esprima": "^4.0.1",
    "json-source-map": "^0.6.1",
    "papaparse": "^5.4.0",
    "pinyin": "^4.0.0",
    "yaml": "^2.4.0"
  }
}


Security scan verdicts — ClawScan: suspicious | static analysis: suspicious | VirusTotal:  | SkillSpector: suspicious (CRITICAL)