@agentscope-ai/i18n 1.0.0 → 1.0.2

package/README.md

@@ -1,11 +1,11 @@
-# @agentscope-ai/i18n
+# @ali/agentscope-ai-i18n
 
 前端代码仓库中文国际化工具，支持 AI 智能翻译和多语言管理。
 
 ## 特性
 
 - 自动检测并提取中文文本
-- 支持 AI Agent 翻译和 MT 机器翻译两种模式
+- 支持 AI Agent 翻译和 MT 机器翻译两种引擎
 - 支持 JSX/TSX/TS/JS 文件解析
 - 智能生成翻译 key（MT 模式下保留文件路径结构）
 - 支持翻译 key 使用检查与自动清理
@@ -19,7 +19,7 @@
 ## 安装
 
 ```bash
-npm install @agentscope-ai/i18n
+npm install @ali/agentscope-ai-i18n
 ```
 
 ## 快速开始
@@ -32,7 +32,7 @@ npx i18n init-config
 
 # 3. 在 .env 文件中填写 DASHSCOPE_APIKEY
 
-# 4. 初始化翻译
+# 4. 初始化翻译（默认使用 MT 引擎）
 npx i18n init
 
 # 5. 后续新增文案时，增量翻译
@@ -44,14 +44,14 @@ npx i18n patch
 | 命令 | 说明 |
 |------|------|
 | `npx i18n init-config` | 生成 `i18n.config.js` 配置文件 |
-| `npx i18n init` | 初始化翻译（MT 模式，等同于 `init-mt`） |
-| `npx i18n init-agent` | 初始化翻译（百炼 Agent 批量模式） |
-| `npx i18n init-mt` | 初始化翻译（MT 机器翻译模式） |
-| `npx i18n patch` | 增量翻译（MT 模式，等同于 `patch-mt`） |
-| `npx i18n patch-agent` | 增量翻译（百炼 Agent 批量模式） |
-| `npx i18n patch-mt` | 增量翻译（MT 机器翻译模式） |
+| `npx i18n init` | 初始化翻译（默认 MT 引擎） |
+| `npx i18n init --engine agent` | 初始化翻译（Agent 批量引擎） |
+| `npx i18n patch` | 增量翻译（默认 MT 引擎） |
+| `npx i18n patch --engine agent` | 增量翻译（Agent 批量引擎） |
 | `npx i18n check` | 检查翻译 key 使用状态 |
 | `npx i18n reverse` | 还原国际化代码为中文 |
+| `npx i18n translate` | 三步工作流 Step 1：提取+翻译（不改源码） |
+| `npx i18n replace` | 三步工作流 Step 3：替换源码 |
 | `npx i18n medusa` | 从 Medusa 平台拉取翻译文件 |
 | `npx i18n install-skill` | 安装 IDE AI 助手的 i18n-helper skill |
 
@@ -83,51 +83,27 @@ npx i18n init-config
 require('dotenv').config();
 
 module.exports = {
-  // 不需要翻译的文件和路径列表
   doNotTranslateFiles: ['node_modules', 'dist', '.git'],
-
-  // 要处理的文件类型
   fileType: '.tsx,.ts,.js,.jsx',
-
-  // 需要翻译的文件目录
   targetPath: './src',
-
-  // 翻译文件输出目录
   localesFilePath: './src/i18n/locales',
-
-  // i18n实例文件输出目录
   i18nFilePath: './src/i18n',
-
-  // 翻译key的前缀
   keyPrefix: 'app',
-
-  // i18n函数导入路径
   functionImportPath: '@/i18n',
 
-  // DashScope API配置
   dashScope: {
-    // Agent 模式使用的工作流 appId
     keyTranslateAppId: '',
-
-    // MT 模式使用的翻译工作流 appId（按语言配置）
     valueTranslateAppId: {
       'en-us': '',
       'ja-jp': '',
     },
-
-    // API密钥（从 .env 读取）
     apiKey: process.env.DASHSCOPE_APIKEY,
-
-    // Agent 批量翻译配置
     batchSize: 50,
-
-    // MT 翻译配置
-    mtConcurrency: 1,   // 并发数
-    mtDelay: 1000,       // 批次间延迟（ms）
-    mtBatchSize: 25,     // 每批翻译条数
+    mtConcurrency: 1,
+    mtDelay: 1000,
+    mtBatchSize: 25,
   },
 
-  // Medusa 翻译平台配置（可选）
   medusa: {
     appName: '',
     appId: '',
@@ -147,54 +123,41 @@ module.exports = {
 
 ## 命令详解
 
-### init / init-mt — 初始化翻译（MT 模式）
+### init — 初始化翻译
 
 ```bash
-npx i18n init
+npx i18n init                # 默认使用 MT 引擎
+npx i18n init --engine agent # 使用 Agent 批量引擎
 ```
 
 1. 扫描 `targetPath` 目录中的源文件
 2. 提取中文文案
-3. 使用 MT 机器翻译逐条生成翻译 key（保留文件路径结构）
-4. 翻译为配置的多语言
-5. 替换代码中的中文为 `$i18n.get()` 调用
-6. 询问是否生成 Medusa Excel 文件
+3. 使用选定引擎翻译生成 key 和多语言文件
+4. 替换代码中的中文为 `$i18n.get()` 调用
+5. 询问是否生成 Medusa Excel 文件
 
-### init-agent — 初始化翻译（Agent 批量模式）
+### patch — 增量翻译
 
 ```bash
-npx i18n init-agent
-```
-
-使用百炼 Agent 工作流进行批量翻译，适合大量文案的初始化场景。
-
-### patch / patch-mt — 增量翻译（MT 模式）
-
-```bash
-npx i18n patch
+npx i18n patch                # 默认使用 MT 引擎
+npx i18n patch --engine agent # 使用 Agent 批量引擎
 ```
 
 只扫描和翻译新增的中文文案，更新现有翻译文件。
 
-### patch-agent — 增量翻译（Agent 批量模式）
-
-```bash
-npx i18n patch-agent
-```
-
-使用百炼 Agent 工作流进行批量增量翻译。
-
 ### check — 检查翻译状态
 
 ```bash
 npx i18n check
 npx i18n check --auto-delete-unused
+npx i18n check --summary-only
 ```
 
 1. 检查代码中使用的翻译 key
 2. 对比翻译文件的完整性
 3. 显示缺失和未使用的 key
 4. `--auto-delete-unused`：自动删除未使用的 key
+5. `--summary-only`：只输出各语言缺失统计
 
 ### reverse — 还原国际化代码
 
@@ -207,6 +170,15 @@ npx i18n reverse
 3. 替换为原始中文文本
 4. 删除 `$i18n` 的导入语句
 
+### translate / replace — 三步工作流
+
+```bash
+npx i18n translate           # Step 1: 只生成 locale 文件，不修改源码
+npx i18n translate -f file   # 单文件模式
+# Step 2: 同步到 Medusa（外部操作）
+npx i18n replace             # Step 3: 替换源码中的中文
+```
+
 ### medusa — 从 Medusa 平台拉取翻译文件
 
 ```bash
@@ -216,19 +188,6 @@ npx i18n medusa --output ./src/locales   # 自定义输出目录
 npx i18n medusa --no-merge               # 不合并，直接覆盖
 ```
 
-支持的选项：
-
-| 选项 | 说明 |
-|------|------|
-| `-c, --config <path>` | 配置文件路径 |
-| `-o, --output <dir>` | 输出目录 |
-| `-a, --app <name>` | Medusa 应用名称 |
-| `-t, --tag <name>` | Medusa 标签名称 |
-| `--type <type>` | 包类型（json/android/ios） |
-| `--no-merge` | 不合并现有文件，直接覆盖 |
-
-配置优先级：命令行参数 > 配置文件 > 默认值。
-
 ### install-skill — 安装 IDE i18n Skill
 
 ```bash
@@ -237,37 +196,32 @@ npx i18n install-skill --agent cursor qoder
 npx i18n install-skill --app-id 12345
 ```
 
-为 Cursor、Qoder、Claude Code、Codex、OpenCode 等 IDE 安装 i18n-helper skill。默认自动检测已有的 IDE 配置目录。
+为 Cursor、Qoder、Claude Code、Codex、OpenCode 等 IDE 安装 i18n-helper skill。
 
-## 翻译模式对比
+## 翻译引擎对比
 
-| | Agent 批量模式 (init-agent / patch-agent) | MT 机器翻译模式 (init / patch) |
+| | MT 机器翻译（默认） | Agent 批量 (`--engine agent`) |
 |---|---|---|
-| 翻译方式 | 批量翻译 | 逐条翻译 |
-| 速度 | 快（批量处理） | 较慢（支持并发控制） |
-| 翻译质量 | 一般 | 高（无上下文干扰） |
-| Key 生成 | 批量生成 | 保留文件路径结构 |
-| 错误隔离 | 批次粒度 | 单条粒度 |
-| 适用场景 | 大量文案初始化 | 高质量翻译、增量更新 |
+| 翻译方式 | 逐条翻译 | 批量翻译 |
+| 速度 | 较慢（支持并发控制） | 快（批量处理） |
+| 翻译质量 | 高（无上下文干扰） | 一般 |
+| Key 生成 | 保留文件路径结构 | 批量生成 |
+| 错误隔离 | 单条粒度 | 批次粒度 |
+| 适用场景 | 高质量翻译、增量更新 | 大量文案初始化 |
 
 ### 性能调优
 
 ```javascript
 dashScope: {
-  // Agent 批量模式：调整每批数量，建议 50-200
-  batchSize: 50,
-
-  // MT 模式：需满足 1000 / mtDelay * mtConcurrency <= API rps 限制
-  mtConcurrency: 1,   // 并发数，建议 1-5
-  mtDelay: 1000,       // 批次间延迟（ms）
-  mtBatchSize: 25,     // 每次 API 调用翻译条数
+  batchSize: 50,       // Agent 批量模式：每批数量，建议 50-200
+  mtConcurrency: 1,    // MT 模式并发数，建议 1-5
+  mtDelay: 1000,       // MT 批次间延迟（ms）
+  mtBatchSize: 25,     // MT 每次 API 调用翻译条数
 }
 ```
 
 ## 忽略功能
 
-工具支持三种级别的忽略控制，优先级从高到低：
-
 ### 1. 文件级别忽略
 
 在文件**第一行**添加注释，跳过整个文件：
@@ -275,46 +229,24 @@ dashScope: {
 ```jsx
 // @i18n-ignore
 import React from 'react';
-
-const Component = () => {
-  return <div>这个文件中的所有中文都不会被处理</div>;
-};
+const Component = () => <div>这个文件中的所有中文都不会被处理</div>;
 ```
 
 ### 2. 块级别忽略
 
-使用 `@i18n-ignore-block-start` / `@i18n-ignore-block-end` 包裹代码块：
-
 ```jsx
 {/* @i18n-ignore-block-start */}
 <div>这个块中的所有文本都不会被处理</div>
-<span>这个也不会被处理</span>
 {/* @i18n-ignore-block-end */}
 ```
 
 ### 3. 行级别忽略
 
-在行尾添加 `@i18n-ignore-line` 注释：
-
 ```jsx
 <p>这行文本不会被处理 {/* @i18n-ignore-line */}</p>
 const message = '这个变量不会被处理'; // @i18n-ignore-line
 ```
 
-## 多语言支持
-
-在 `valueTranslateAppId` 中配置各语言对应的工作流 appId：
-
-```javascript
-valueTranslateAppId: {
-  'en-us': 'english-app-id',
-  'ja-jp': 'japanese-app-id',
-  'ko-kr': 'korean-app-id',
-}
-```
-
-每种语言会生成对应的翻译文件（`zh-cn.json`、`en-us.json`、`ja-jp.json` 等）。
-
 ## 代码示例
 
 ### 翻译前
@@ -347,19 +279,16 @@ const Form = () => {
 };
 ```
 
-### 还原后
+## 从旧版迁移
 
-```tsx
-const Form = () => {
-  return (
-    <form>
-      <label>用户名：</label>
-      <input placeholder="请输入用户名" />
-      <button>提交</button>
-    </form>
-  );
-};
-```
+以下命令已弃用，但仍可使用（会提示迁移）：
+
+| 旧命令 | 新命令 |
+|--------|--------|
+| `npx i18n init-mt` | `npx i18n init` |
+| `npx i18n init-agent` | `npx i18n init --engine agent` |
+| `npx i18n patch-mt` | `npx i18n patch` |
+| `npx i18n patch-agent` | `npx i18n patch --engine agent` |
 
 ## 注意事项
 
@@ -368,21 +297,14 @@ const Form = () => {
 3. 忽略标记必须出现在注释中，字符串中的标记不会被识别
 4. Medusa 拉取功能需要确保网络连接到 Medusa 平台
 5. MT 翻译的并发参数需满足 `1000 / mtDelay * mtConcurrency <= API rps 限制`
-6. 错误日志自动记录到 `logs/` 目录下（`api-errors.log`、`translation-errors.log`、`mt-translation-errors.log`）
+6. 错误日志自动记录到 `logs/` 目录下
 
 ## 开发
 
 ```bash
-# 安装依赖
 pnpm install
-
-# 运行测试
 pnpm test
-
-# 代码格式化
 pnpm run format
-
-# 代码检查
 pnpm run lint
 ```
 

package/i18n.config.example.js

@@ -0,0 +1,106 @@
+// 注意：这里是 i18n 脚本（node 环境）使用的配置文件，不会打包进前端产物。
+// 为避免将敏感信息（如 API Key）提交到仓库，使用 dotenv 从本地 .env 读取。
+require('dotenv').config();
+
+module.exports = {
+  // 不需要翻译的文件和路径列表
+  doNotTranslateFiles: ['node_modules', 'dist', '.git', 'tests/locales'],
+
+  // 要处理的文件类型
+  fileType: '.tsx,.ts,.js,.jsx',
+
+  // 需要翻译的文件目录
+  targetPath: './tests',
+
+  // 翻译文件输出目录
+  localesFilePath: './tests/locales',
+
+  // i18n实例文件输出目录
+  i18nFilePath: './tests/i18n',
+
+  // 翻译key的前缀
+  keyPrefix: 'test',
+
+  // i18n函数导入路径
+  functionImportPath: '@/tests/i18n',
+
+  // 自定义 i18n 调用表达式配置
+  // 默认生成 $i18n.get({ id, dm }) 形式（成员调用）
+  //
+  // 方式一：成员调用 —— objectName.methodName({ id, dm })
+  // callExpression: {
+  //   objectName: '$i18n',   // 调用对象名，如 $i18n、intl
+  //   methodName: 'get',     // 方法名，如 get、t
+  //   importName: '$i18n',   // import 绑定名，如 import $i18n from '...'
+  // },
+  //
+  // 方式二：直接函数调用 —— functionName({ id, dm })
+  // callExpression: {
+  //   functionName: 'translate',  // 函数名，如 translate、t、$t
+  //   importName: 'translate',    // import 绑定名，如 import translate from '...'
+  // },
+
+  // DashScope API配置
+  dashScope: {
+    // 翻译key的大模型工作流agent appId，如果不使用 init-agent/patch-agent，则不需要配置
+    keyTranslateAppId: '',
+
+    // 翻译value的大模型工作流appId，如果不使用 init-mt/patch-mt，则不需要配置
+    valueTranslateAppId: {
+      'en-us': '',
+      'ja-jp': '',
+    },
+
+    // API密钥
+    apiKey: process.env.DASHSCOPE_APIKEY,
+
+    // 批量翻译配置（适用于init和patch）
+    batchSize: 50, // 每批处理50条文案，默认100
+
+    // MT翻译配置（适用于init-mt和patch-mt, 1000 / mtDelay * mtConcurrency 需要满足基模调用的 rps 限制）
+    mtConcurrency: 1, // MT翻译并发数为3，默认1
+    mtDelay: 1000, // MT翻译批次间延迟200ms，默认100ms
+    mtBatchSize: 25, // MT翻译批次大小，默认10
+  },
+
+  // check 命令配置
+  check: {
+    // 需要检查的语言列表（默认从 dashScope.valueTranslateAppId 推断）
+    // 配置后优先使用此处的语言列表
+    languages: ['zh-cn', 'en-us', 'ja-jp'],
+  },
+
+  // medusa 配置，用于生成 excel 文件和从平台拉取翻译文件
+  medusa: {
+    // 应用名称
+    appName: '',
+
+    // 应用ID
+    appId: '',
+
+    // 标签名称（用于拉取文件）
+    tag: '',
+
+    // 包类型（用于拉取文件）json/android/ios
+    type: 'json',
+
+    // 输出目录（用于拉取文件）
+    outputPath: './locales',
+
+    // 是否合并现有文件（用于拉取文件）
+    mergeExisting: true,
+
+    // medusa group id（用于生成 Excel 文件）
+    group: '',
+
+    // 语言映射配置（用于生成 Excel 文件）
+    keyMap: {
+      'en-us': 'English',
+      'ja-jp': 'Japanese',
+      'zh-cn': 'Simplified Chinese',
+    },
+
+    // bucId（从 .env 中的 BUC_ID 读取）
+    bucId: process.env.BUC_ID,
+  },
+};