@agentscope-ai/i18n 1.0.1 → 1.0.2

package/skills/i18n-helper/SKILL.md

@@ -1,19 +1,42 @@
 ---
 name: i18n-helper
-description: 国际化(i18n)自动化助手。当用户要对项目目录执行i18n增量翻译（如「翻译 @src/xxx」「i18n」「国际化」「patch」），或要修改指定i18n key的中英文文案（如「修改xxx的英文」「英文改为」）时触发。仅翻译普通文案时不触发。
+description: 国际化(i18n)自动化助手。当用户要对项目目录执行i18n增量翻译（如「翻译 @src/xxx」「i18n」「国际化」「patch」「提翻 @src/xxx」「@src/xxx 翻译」「@src/xxx 提翻」），或要修改指定i18n key的中英文文案（如「修改xxx的英文」「英文改为」），或要检查翻译状态（如「检查翻译」「翻译检查」「国际化检查」「i18n check」）时触发。仅翻译普通文案时不触发。
 ---
 
 # 国际化自动化助手
 
 ## 项目配置
 
-- 工具：`@agentscope-ai/i18n`
-- 美杜莎应用名：`{{MEDUSA_APP_NAME}}`
-- 美杜莎应用ID：`{{MEDUSA_APP_ID}}`
-- 标签：`{{MEDUSA_TAG}}`
-- 翻译文件目录：`{{LOCALES_FILE_PATH}}`
-- 支持语言：{{LANGUAGES}}
-- 配置文件：`i18n.config.js`
+工具：`@ali/agentscope-ai-i18n`，配置文件：项目根目录的 `i18n.config.js`。
+
+执行任何操作前，先读取 `i18n.config.js` 获取以下信息：
+- `medusa.appName` — 美杜莎应用名
+- `medusa.appId` — 美杜莎应用ID
+- `medusa.tag` — 标签
+- `localesFilePath` — 翻译文件目录
+- `dashScope.valueTranslateAppId` — 从其 key 推断支持的语言列表
+
+## 前置环境检查
+
+**每次执行任何 i18n 操作前，必须先检查以下配置文件是否存在：**
+
+1. **检查 `i18n.config.js`**：如果项目根目录下不存在 `i18n.config.js`（或 `i18n.config.cjs`），停止操作并提示用户：
+   - 运行 `npx i18n init-config` 生成配置文件
+   - 根据项目实际情况修改 `targetPath`、`keyPrefix`、`medusa` 等配置
+
+2. **检查 `.env`**：如果项目根目录下不存在 `.env` 文件或缺少必要的环境变量（`DASHSCOPE_APIKEY`、`BUC_ID`），停止操作并提示用户：
+   - 在 `.env` 中填写 `DASHSCOPE_APIKEY`（AI 翻译所需）
+   - 在 `.env` 中填写 `BUC_ID`（同步美杜莎所需，可在 https://wanx-medusa-config.pre-fn.alibaba-inc.com/ 登录后右上角查看）
+
+## Medusa 权限问题诊断
+
+当调用 medusa 相关接口（如 `npx i18n medusa`、sync-to-mds 脚本等）返回的不是 JSON 而是 HTML 页面时，通常是因为没有该美杜莎应用的 ACL 权限。此时需要停止操作并提示用户前往以下两个平台申请权限：
+
+1. **Medusa 平台**：`https://mds-portal.alibaba-inc.com/applications/detail?navItemType=keyList&appId={medusa.appId}&appName={medusa.appName}`
+   （将 `{medusa.appId}` 和 `{medusa.appName}` 替换为 `i18n.config.js` 中的实际值）
+2. **MCMS 平台**：`https://mcms-portal.alibaba-inc.com`
+
+提示用户在以上两个平台完成 ACL 权限申请后重试。
 
 ## 场景判断
 
@@ -25,16 +48,31 @@ description: 国际化(i18n)自动化助手。当用户要对项目目录执行i
 - 仅出现「翻译」或「翻译 xxx」但不带目录路径时，**不触发**此场景
 
 **修改文案** — 用户要修改指定 i18n key 的中英文文案：
-- 触发条件：用户消息中包含 i18n key（如 `bailian.xxx.xxx`）或引用了含有 `$i18n.get` 的代码行
+- 触发条件：用户消息中包含 i18n key（如 `app.xxx.xxx`）或引用了含有 `$i18n.get` 的代码行
 - 关键词：「修改 xxx 的中文/英文」「把 xxx 改成」「英文改为」「中文改为」「英文改成」「中文改成」「更新文案」
 
+**检查翻译** — 用户要检查项目翻译状态，确认是否有未翻译文案、缺失 key 等：
+- 触发条件：用户消息中包含检查/巡查翻译状态的意图
+- 关键词：「检查翻译」「国际化检查」「i18n check」「翻译检查」「检查i18n」「翻译状态」「check」
+
+## 核心原则：翻译必须通过美杜莎平台
+
+**禁止直接修改本地 `locales/` 目录下的翻译 JSON 文件来新增或修改翻译。** 所有翻译变更必须经过以下流程：
+
+1. 使用 `npx i18n patch`（或 `translate`）生成 Excel 文件
+2. 将 Excel 上传到美杜莎平台
+3. 在美杜莎平台上确认并发布
+4. 通过 `npx i18n medusa` 从平台拉取最新翻译到本地
+
+本地 locale 文件仅作为平台翻译的本地缓存，不应手动编辑。
+
 ## 增量翻译：扫描中文 + 生成 Excel + 上传美杜莎
 
-### 步骤
+这是一个分步工作流，在每步完成后暂停让用户确认，再继续下一步。
 
-1. **提交当前代码（创建回退点）**
+### Step 1: patch — 扫描中文 + AI 翻译 + 生成 Excel
 
-   在翻译前先将当前所有变更提交，方便翻译后不满意时通过 `git revert` 回退：
+1. **提交当前代码（创建回退点）**
 
    ```bash
    git add -A && git commit -m "chore: save before i18n patch"
@@ -43,120 +81,186 @@ description: 国际化(i18n)自动化助手。当用户要对项目目录执行i
 2. **执行增量翻译命令**
 
    如果用户指定了目标目录 `<dir>`：
-
    ```bash
    npx i18n patch --target-path <dir> --skip-confirm
    ```
 
    否则使用默认配置：
-
    ```bash
    npx i18n patch --skip-confirm
    ```
 
    `--skip-confirm` 会跳过所有确认提示，自动完成翻译流程。等待命令完成。
 
+   **可选引擎**：默认使用 MT 机器翻译，如需使用 Agent 批量翻译，追加 `--engine agent`。
+
 3. **定位并打开生成的 Excel 文件**
 
-   命令执行完成后，在 `{{LOCALES_FILE_PATH}}` 目录下查找最新生成的 `medusa-translations-*.xlsx` 文件，使用 `open` 命令打开它，方便用户预览确认翻译内容：
+   命令执行完成后，在 `localesFilePath` 目录下查找最新生成的 `medusa-translations-*.xlsx` 文件，使用 `open` 命令打开它，方便用户预览确认翻译内容：
 
    ```bash
-   open "{{LOCALES_FILE_PATH}}/medusa-translations-<timestamp>.xlsx"
+   open "<localesFilePath>/medusa-translations-<timestamp>.xlsx"
    ```
 
-4. **打开美杜莎上传页面**
+4. **暂停确认**
+
+   使用 AskQuestion 询问用户：
+   - Excel 文件已打开，请确认翻译内容
+   - 选项：「继续上传到美杜莎」/「暂停，我先手动检查 Excel」
+
+### Step 2: 上传到美杜莎平台
+
+1. **打开美杜莎上传页面**
 
    使用 `open` 命令在系统默认浏览器（Chrome）中打开以下地址，不要使用 Cursor 内置浏览器：
 
    ```bash
-   open "https://mds-portal.alibaba-inc.com/applications/upload?appName={{MEDUSA_APP_NAME}}&appId={{MEDUSA_APP_ID}}&&appGroupId=&lastPage=%5Bobject%20Object%5D"
+   open "https://mds-portal.alibaba-inc.com/applications/upload?appName={medusa.appName}&appId={medusa.appId}&&appGroupId=&lastPage=%5Bobject%20Object%5D"
    ```
 
-5. **提示用户操作**
+   > 将 `{medusa.appName}` 和 `{medusa.appId}` 替换为 `i18n.config.js` 中的实际值。
+
+2. **提示用户操作**
 
    告知用户：
-   - Excel 文件已打开，请确认翻译内容
    - **如果有文案是产品指定，请添加 do_not_trans 标签！**
    - 在美杜莎页面上传该 Excel 文件，上传后确认导入
-   - 然后筛选未发布文案（标签={{MEDUSA_TAG}}，发布状态=未发布），全选后发布中文
+   - 然后筛选未发布文案（标签={medusa.tag}，发布状态=未发布），全选后发布中文
    - 下一个工作日翻译同学会收到翻译任务（T+1）
+   - 如果上传/导入时页面报错或跳转到登录页，可能是权限问题，参考上方「Medusa 权限问题诊断」
 
-## 修改文案：更新指定 key 的中英文并同步美杜莎
+3. **暂停确认**
+
+   使用 AskQuestion 询问用户：
+   - 选项：「已上传并发布，继续替换代码」/「暂停，我先去美杜莎确认」
 
-### 前置条件
+### Step 3: replace — 替换代码中的中文
 
-确保 Chrome 调试模式已启动（`npm run chrome:debug`），如果端口 9222 已被 Chrome 占用则无需重复启动。
+1. **执行替换命令**
+
+   ```bash
+   npx i18n replace
+   ```
+
+   或指定文件：
+   ```bash
+   npx i18n replace --file <file>
+   ```
+
+2. **完成**
+
+   告知用户：
+   - 代码替换完成
+   - 请检查 git diff 确认改动
+   - 如不满意可 `git revert HEAD` 回退
+
+## 检查翻译：拉取最新文案 + 检查缺失 + 引导后续操作
+
+### 步骤
+1. **拉取美杜莎最新翻译到本地**
+   ```bash
+   npx i18n medusa
+   ```
+   如果命令执行后输出中包含 HTML 标签（如 `<html`、`<!DOCTYPE`）而非正常 JSON 处理日志，说明是权限问题，参考上方「Medusa 权限问题诊断」停止并引导用户。
+
+2. **执行检查命令**
+   ```bash
+   npx i18n check --skip-confirm
+   ```
+   命令执行后有两种结果：
+   - **输出行数 <= 100**：直接将控制台输出解析结果，**不会**生成 JSON 文件
+   - **输出行数 > 100**：在项目根目录生成 `check-result-{timestamp}.json`，控制台只打印概要
+
+   可选参数：
+   - `--auto-delete-unused`：自动删除未使用的 key
+   - `--summary-only`：只输出各语言缺失 key 数量统计，跳过删除和文件生成
+
+3. **读取结果**
+   检查命令完成后，用 Glob 工具搜索项目根目录下的 `check-result-*.json`，取**最新的**一个读取。
+   JSON 文件结构如下：
+   ```json
+   {
+     "timestamp": "...",
+     "summary": {
+       "totalMissingKeys": 0,
+       "totalUnusedKeys": 0,
+       "totalUntranslatedTexts": 0,
+       "totalOutputLines": 0
+     },
+     "missingKeys": { "zhCN": [], "enUS": [] },
+     "unusedKeys":  { "zhCN": [], "enUS": [] },
+     "untranslatedTexts": []
+   }
+   ```
+   如果没有 JSON 文件（输出行数 <= 100），则从控制台输出中解析以下信息：
+   - 各语言缺失的 key 数量（`zh-cn.json 缺失: N`）
+   - 未翻译的中文文案数量（`未翻译的中文文案: N 条`）
+4. **向用户展示概要并询问下一步**
+   用简洁的 Markdown 展示检查结果，然后使用 AskQuestion 询问用户（**可多选**）希望进行哪些后续操作：
+   - 「增量翻译未翻译的中文文案（运行 patch 工作流）」
+   - 「暂不处理，我自己看结果」
+5. **根据用户选择执行对应工作流**
+
+## 修改文案：更新指定 key 的中英文并同步美杜莎
+
+**重要：修改文案也必须通过美杜莎平台，不要直接修改本地 locale JSON 文件。**
 
 ### 步骤
 
-1. **解析用户意图并验证 key**
+1. **解析用户意图**
+
+   从用户消息中提取 `key`、各语言新值（可选，如 `zhValue`、`enValue`）。如果用户只提供了部分信息，主动询问缺失的内容。
 
-   从用户消息中提取 `key`、`zhValue`（可选）、`enValue`（可选）。如果用户只提供了部分信息，主动询问缺失的内容。
+2. **读取现有文案并构造 payload**
 
-2. **构造 URL 并导航到美杜莎详情页**
+   从 `i18n.config.js` 的 `localesFilePath` 目录下读取各语言 JSON 文件，获取该 key 的现有值。
 
-   URL 模板（将 `{KEY_ENCODED}` 替换为编码后的 key）：
+   将要更新的内容构造成 `mds-payload.json` 格式：
 
+   ```json
+   [
+     {
+       "key": "<key>",
+       "appName": "<medusa.appName>",
+       "i18n": {
+         "zh_CN": "<zh 值>",
+         "en_US": "<en 值>"
+       }
+     }
+   ]
    ```
-   https://mds-portal.alibaba-inc.com/applications/detail?appName={{MEDUSA_APP_NAME}}&appId={{MEDUSA_APP_ID}}&currentPageInfo=%7B%22searchValue%22%3A%22%22%2C%22releaseId%22%3A0%2C%22pageSize%22%3A10%2C%22senior%22%3Afalse%2C%22pageNumber%22%3A1%2C%22showKeyDetail%22%3Atrue%2C%22pageTagesBuffer%22%3A%22en_US%2Czh_CN%2Ctag%22%2C%22showDetailAppName%22%3A%22{{MEDUSA_APP_NAME}}%22%2C%22showDetailKeys%22%3A%22{KEY_ENCODED}%22%2C%22searchCriteria%22%3A%7B%22key%22%3A%22{KEY_ENCODED}%22%2C%22string%22%3A%22%22%2C%22missTrans%22%3A%22%22%2C%22tags%22%3A%22%22%2C%22published%22%3A%22%22%2C%22reviewed%22%3A%22%22%2C%22tested%22%3A%22%22%2C%22translated%22%3A%22%22%2C%22transSource%22%3A%22%22%2C%22user%22%3A%22%22%2C%22updateDateStart%22%3A%22%22%2C%22updateDateEnd%22%3A%22%22%7D%7D
+
+   > `i18n` 对象中只包含**本次要更新的语言**，不要写入未修改的语言。
+   >
+   > 语言 key 使用下划线格式：`zh_CN`、`en_US`。
+
+   将文件写入项目根目录的 `mds-payload.json`。
+
+3. **调用同步脚本上传到美杜莎**
+
+   ```bash
+   node <SKILL_DIR>/scripts/sync-to-mds.js --env pre --yes
    ```
 
-   > **编码规则**：`{KEY_ENCODED}` = 将 key 中的 `.` 全部替换为 `%2E`。直接做字符串替换即可，**不要调用 python 或其他外部脚本**。
-   > 例如：`bailian.foo.bar` → `bailian%2Efoo%2Ebar`
-   
-   使用 Chrome DevTools MCP 的 `new_page`（不要用 `navigate_page`，它会关闭当前页）打开上述 URL。
-
-3. **操作美杜莎页面（最小化交互次数）**
-
-   使用 `wait_for` 等待 `en_US` 或 `zh_CN` 文本出现（它会自动返回快照，无需再调 `take_snapshot`）。从快照中识别：
-   - `zh_CN` textarea、`en_US` textarea 的 uid
-   - 标签区域是否已有 `do_not_trans`
-   - 「保存」按钮 uid
-
-   **只修改用户指定的语言**，未指定的不要动。按以下顺序操作：
-
-   a. **填入文案** — 对每个需要修改的 textarea，通过 `evaluate_script` 设置值（可以在**一次调用**中同时处理多个 textarea）：
-      ```javascript
-      (zh, en) => {
-        const set = (el, v) => {
-          if (!el || v === null) return;
-          const setter = Object.getOwnPropertyDescriptor(window.HTMLTextAreaElement.prototype, 'value').set;
-          setter.call(el, v);
-          el.dispatchEvent(new Event('input', { bubbles: true }));
-          el.dispatchEvent(new Event('change', { bubbles: true }));
-        };
-        set(zh, '新中文值或null');
-        set(en, '新英文值或null');
-        return 'ok';
-      }
-      ```
-      > 不需要修改的语言传 `null`，对应 `args` 中仍需传一个占位 uid（任意元素即可）。
-
-   b. **添加 do_not_trans 标签**（如果快照中已有则**跳过此步**） — 通过 `evaluate_script` 一次完成：
-      ```javascript
-      (combobox) => {
-        combobox.click();
-        return new Promise(resolve => {
-          setTimeout(() => {
-            const opt = [...document.querySelectorAll('[role="option"]')].find(el => el.textContent.trim() === 'do_not_trans');
-            if (opt) opt.click();
-            setTimeout(() => {
-              combobox.blur();
-              document.body.click();
-              resolve('done');
-            }, 200);
-          }, 300);
-        });
-      }
-      ```
-
-   c. **保存并发布** — 点击「保存」按钮，紧接着点击「立即发布」按钮（无需等待保存成功提示，两次 click 可连续调用），然后结束流程，等待用户手动确认即可。
+   > `<SKILL_DIR>` 替换为本 SKILL.md 所在目录相对于项目根目录的路径（如 `.cursor/skills/i18n-helper`）。
+
+   脚本会自动写入美杜莎、发布，并在完成后删除 `mds-payload.json`。
+
+   > **【安全规则】永远不要对 prod 环境使用 `--yes`**。如果用户明确要求写入 prod，去掉 `--yes`，让用户在终端手动确认冲突。
+
+   **如果脚本报错或返回 HTML 而非 JSON**，参考上方「Medusa 权限问题诊断」引导用户申请权限。
 
+4. **同步完成后更新本地 locale 文件**
+
+   运行以下命令从美杜莎拉取最新翻译到本地，确保本地文件与平台一致：
+   ```bash
+   npx i18n medusa
+   ```
 
 ## 注意事项
 
-- **静默执行**：执行过程中不要输出中间状态描述（如 uid、当前值、按钮信息等），直接操作即可。仅在最终完成或出错时输出一句简短结果
+- **静默执行**：执行过程中不要输出中间状态描述，直接操作即可。仅在最终完成或出错时输出一句简短结果
 - 美杜莎是阿里内网平台，需要连接内网/VPN 才能访问
-- `do_not_trans` 标签表示产品指定的中英文文案，不需要翻译同学翻译
+- 美杜莎后端地址：`https://wanx-medusa-config.pre-fn.alibaba-inc.com/`
 - key 中不支持模板字符串或表达式，全部使用字符串字面量
-- 忽略翻译可使用注释：`// @i18n-ignore`（文件级）、`// @i18n-ignore-line`（行级）、`// @i18n-ignore-block-start/end`（块级）
+- 忽略翻译可使用注释：`// @i18n-ignore`（文件级）、`// @i18n-ignore-line`（行级）、`// @i18n-ignore-block-start/end`（块级）