@agentscope-ai/i18n 0.1.3 → 0.1.5

package/README.md

@@ -1,44 +1,90 @@
-# Agentscope AI I18n
+# @agentscope-ai/i18n
 
-用于百炼内部的国际化工具，支持智能翻译和多语言管理。
+前端代码仓库中文国际化工具，支持 AI 智能翻译和多语言管理。
 
 ## 特性
 
-- 🔍 自动检测并提取中文文本
-- 🤖 支持 AI 智能翻译（支持多语言）
-- 🚀 **新增MT机器翻译**：支持单条翻译，翻译质量更高
-- ⚡ **并发控制**：MT翻译支持可配置的并发数和延迟控制
-- 📏 **批量配置**：批量翻译支持可配置的批次大小
-- 🔄 支持 JSX/TSX 文件解析
-- 🔑 智能生成翻译 key（MT模式下保留文件路径结构）
-- ✅ 支持翻译 key 使用检查
-- 📊 生成 Medusa Excel 文件用于翻译管理
-- 🌍 从 Medusa 平台拉取翻译文件
-- 🔄 支持增量更新
-- ↩️ 支持国际化代码还原为中文
-- ⚙️ 可配置的文件匹配模式
-- 🛠️ 简单易用的命令行工具
-- 🚫 支持多种忽略功能（文件级别、行级别、块级别）
-- 🎯 智能过滤标点符号和 emoji
+- 自动检测并提取中文文本
+- 支持 AI Agent 翻译和 MT 机器翻译两种模式
+- 支持 JSX/TSX/TS/JS 文件解析
+- 智能生成翻译 key（MT 模式下保留文件路径结构）
+- 支持翻译 key 使用检查与自动清理
+- 集成 Medusa 翻译平台（拉取翻译文件、生成 Excel）
+- 支持增量更新，只翻译新增文案
+- 支持国际化代码还原为中文
+- 支持文件级、块级、行级忽略控制
+- 自动过滤纯标点符号和 emoji
+- 一键安装 IDE AI 助手的 i18n skill（Cursor / Qoder / Claude Code 等）
 
 ## 安装
 
 ```bash
-# 使用 npm
-npm install @ali/agentscope-ai-i18n
+npm install @agentscope-ai/i18n
+```
+
+## 快速开始
+
+```bash
+# 1. 生成配置文件
+npx i18n init-config
+
+# 2. 修改 i18n.config.js 中的配置（targetPath、keyPrefix 等）
 
-# 使用 yarn
-yarn add @ali/agentscope-ai-i18n
+# 3. 在 .env 文件中填写 DASHSCOPE_APIKEY
+
+# 4. 初始化翻译
+npx i18n init
+
+# 5. 后续新增文案时，增量翻译
+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 check` | 检查翻译 key 使用状态 |
+| `npx i18n reverse` | 还原国际化代码为中文 |
+| `npx i18n medusa` | 从 Medusa 平台拉取翻译文件 |
+| `npx i18n install-skill` | 安装 IDE AI 助手的 i18n-helper skill |
+
+### 通用选项
+
+大部分命令支持以下通用选项：
+
+```bash
+-c, --config <path>       # 指定配置文件路径（默认查找 i18n.config.js）
+-p, --target-path <path>  # 覆盖配置中的 targetPath
+--skip-confirm             # 跳过所有确认提示
 ```
 
 ## 配置
 
-在项目根目录创建 `i18n.config.js` 文件：
+### init-config — 生成配置文件
+
+```bash
+npx i18n init-config
+```
+
+将 `i18n.config.example.js` 模板复制到项目根目录作为 `i18n.config.js`，同时：
+- 如果 `.env` 不存在，自动创建并写入 `DASHSCOPE_APIKEY=`
+- 如果 `.gitignore` 中未包含 `.env`，自动追加
+
+### 配置文件说明
 
 ```javascript
+require('dotenv').config();
+
 module.exports = {
   // 不需要翻译的文件和路径列表
-  doNotTranslateFiles: ['node_modules', 'dist', '.git', 'tests/locales'],
+  doNotTranslateFiles: ['node_modules', 'dist', '.git'],
 
   // 要处理的文件类型
   fileType: '.tsx,.ts,.js,.jsx',
@@ -47,7 +93,7 @@ module.exports = {
   targetPath: './src',
 
   // 翻译文件输出目录
-  localesFilePath: './src/locales',
+  localesFilePath: './src/i18n/locales',
 
   // i18n实例文件输出目录
   i18nFilePath: './src/i18n',
@@ -60,367 +106,219 @@ module.exports = {
 
   // DashScope API配置
   dashScope: {
-    // 翻译key的大模型工作流appId
-    keyTranslateAppId: 'your-key-translate-app-id',
+    // Agent 模式使用的工作流 appId
+    keyTranslateAppId: '',
 
-    // 翻译value的大模型工作流appId（支持多语言）
+    // MT 模式使用的翻译工作流 appId（按语言配置）
     valueTranslateAppId: {
-      'en-us': 'your-en-translate-app-id',
-      'ja-jp': 'your-ja-translate-app-id',
-      // 可以添加更多语言
+      'en-us': '',
+      'ja-jp': '',
     },
 
-    // API密钥
-    apiKey: 'your-api-key',
+    // API密钥（从 .env 读取）
+    apiKey: process.env.DASHSCOPE_APIKEY,
 
-    // 批量翻译配置（适用于init和patch命令）
-    batchSize: 50, // 可选：每批处理的文案数量，默认100
+    // Agent 批量翻译配置
+    batchSize: 50,
 
-    // MT翻译配置（适用于init-mt和patch-mt命令）
-    mtConcurrency: 3, // 可选：MT翻译的并发数，默认1
-    mtDelay: 200, // 可选：MT翻译批次间的延迟时间（毫秒），默认100ms
-    mtBatchSize: 10, // 可选：MT翻译每次调用翻译的条数，默认5（用于应对API速率限制）
+    // MT 翻译配置
+    mtConcurrency: 1,   // 并发数
+    mtDelay: 1000,       // 批次间延迟（ms）
+    mtBatchSize: 25,     // 每批翻译条数
   },
 
-  // Medusa 配置，用于生成 Excel 文件和从平台拉取翻译文件
+  // Medusa 翻译平台配置（可选）
   medusa: {
-    // 应用名称
-    appName: 'your-app-name',
-    
-    // 标签名称（用于拉取文件）
-    tag: 'your-tag-name',
-    
-    // 包类型（用于拉取文件）json/android/ios
+    appName: '',
+    appId: '',
+    tag: '',
     type: 'json',
-    
-    // 输出目录（用于拉取文件）
     outputPath: './locales',
-    
-    // 是否合并现有文件（用于拉取文件）
     mergeExisting: true,
-    
-    // 分组名称（用于生成 Excel 文件）
-    group: 'your-group-name',
-    
-    // 语言映射配置（用于生成 Excel 文件）
+    group: '',
     keyMap: {
-      'zh-cn': 'Simplified Chinese',
       'en-us': 'English',
       'ja-jp': 'Japanese',
-      // 可以添加更多语言映射
-    }
-  }
-};
-```
-
-## 忽略功能
-
-工具提供了多种忽略功能，让你可以精确控制哪些内容需要翻译。
-
-### 忽略功能优先级
-
-1. **文件级别忽略** (`@i18n-ignore`) - 最高优先级，忽略整个文件
-2. **块级别忽略** (`@i18n-ignore-block-start`/`@i18n-ignore-block-end`) - 忽略包裹的代码块
-3. **行级别忽略** (`@i18n-ignore-line`) - 忽略特定行
-
-### 1. 文件级别忽略
-
-在文件的第一行添加注释来忽略整个文件：
-
-```jsx
-// @i18n-ignore
-import React from 'react';
-
-const Component = () => {
-  return <div>这个文件中的所有中文都不会被处理</div>;
-};
-```
-
-或者：
-
-```jsx
-/* @i18n-ignore */
-import React from 'react';
-
-const Component = () => {
-  return <div>这个文件中的所有中文都不会被处理</div>;
+      'zh-cn': 'Simplified Chinese',
+    },
+  },
 };
 ```
 
-### 2. 行级别忽略
-
-使用 `@i18n-ignore-line` 来忽略特定行：
-
-```jsx
-// JSX 注释形式
-<p>这行文本不会被处理 {/* @i18n-ignore-line */}</p>
-
-// 单行注释形式  
-<div>这行也不会被处理</div> // @i18n-ignore-line
-
-// 变量声明
-const message = '这个变量不会被处理'; // @i18n-ignore-line
-```
-
-### 3. 块级别忽略
-
-使用 `@i18n-ignore-block-start` 和 `@i18n-ignore-block-end` 来忽略代码块：
-
-```jsx
-{/* @i18n-ignore-block-start */}
-<div>这个块中的所有文本都不会被处理</div>
-<span>这个也不会被处理</span>
-<button>这个按钮文本也不会被处理</button>
-{/* @i18n-ignore-block-end */}
-
-// 或者使用单行注释形式
-// @i18n-ignore-block-start
-<div>这个块中的文本不会被处理</div>
-<span>这个也不会被处理</span>
-// @i18n-ignore-block-end
-```
-
-## 使用
-
-### 命令行
-
-```bash
-# 批量翻译模式
-npx i18n init      # 初始化国际化（批量翻译）
-npx i18n patch     # 更新翻译（批量翻译）
-
-# MT机器翻译模式（新增）
-npx i18n init-mt   # 初始化国际化（MT单条翻译）
-npx i18n patch-mt  # 更新翻译（MT单条翻译）
-
-# 其他命令
-npx i18n check     # 检查翻译状态
-npx i18n reverse   # 还原国际化代码为中文
-npx i18n medusa    # 从 Medusa 平台拉取翻译文件
-```
-
 ## 命令详解
 
-### init - 初始化翻译（批量模式）
+### init / init-mt — 初始化翻译（MT 模式）
 
 ```bash
 npx i18n init
 ```
 
-这个命令会：
-1. 扫描指定目录中的文件
+1. 扫描 `targetPath` 目录中的源文件
 2. 提取中文文案
-3. 生成翻译 key
-4. 批量翻译为配置的多语言（每批可配置数量）
-5. 替换代码中的中文为国际化函数调用
+3. 使用 MT 机器翻译逐条生成翻译 key（保留文件路径结构）
+4. 翻译为配置的多语言
+5. 替换代码中的中文为 `$i18n.get()` 调用
 6. 询问是否生成 Medusa Excel 文件
 
-### init-mt - 初始化翻译（MT模式）
+### init-agent — 初始化翻译（Agent 批量模式）
 
 ```bash
-npx i18n init-mt
+npx i18n init-agent
 ```
 
-**新增功能**，这个命令会：
-1. 扫描指定目录中的文件
-2. 提取中文文案
-3. 使用MT机器翻译逐条生成翻译key（保留文件路径结构）
-4. 使用MT机器翻译逐条翻译为配置的多语言
-5. 支持并发控制，提高翻译效率
-6. 替换代码中的中文为国际化函数调用
-7. 询问是否生成 Medusa Excel 文件
+使用百炼 Agent 工作流进行批量翻译，适合大量文案的初始化场景。
 
-### patch - 增量更新（批量模式）
+### patch / patch-mt — 增量翻译（MT 模式）
 
 ```bash
 npx i18n patch
 ```
 
-这个命令会：
-1. 扫描新增的中文文案
-2. 只翻译新增的内容（批量模式）
-3. 更新现有的翻译文件
-4. 询问是否生成 Medusa Excel 文件
+只扫描和翻译新增的中文文案，更新现有翻译文件。
 
-### patch-mt - 增量更新（MT模式）
+### patch-agent — 增量翻译（Agent 批量模式）
 
 ```bash
-npx i18n patch-mt
+npx i18n patch-agent
 ```
 
-**新增功能**，这个命令会：
-1. 扫描新增的中文文案
-2. 使用MT机器翻译逐条处理新增内容
-3. 支持并发控制，提高更新效率
-4. 更新现有的翻译文件
-5. 询问是否生成 Medusa Excel 文件
+使用百炼 Agent 工作流进行批量增量翻译。
 
-### check - 检查翻译状态
+### check — 检查翻译状态
 
 ```bash
 npx i18n check
+npx i18n check --auto-delete-unused
 ```
 
-这个命令会：
 1. 检查代码中使用的翻译 key
 2. 对比翻译文件的完整性
 3. 显示缺失和未使用的 key
-4. 询问是否删除未使用的 key
+4. `--auto-delete-unused`：自动删除未使用的 key
 
-### reverse - 还原国际化代码
+### reverse — 还原国际化代码
 
 ```bash
 npx i18n reverse
 ```
 
-这个命令会：
 1. 扫描文件中的 `$i18n.get` 调用
 2. 提取 `dm`（default message）参数作为中文文本
-3. 替换 `$i18n.get` 调用为原始中文文本
+3. 替换为原始中文文本
 4. 删除 `$i18n` 的导入语句
 
-### medusa - 从 Medusa 平台拉取翻译文件
+### medusa — 从 Medusa 平台拉取翻译文件
 
 ```bash
-npx i18n medusa
+npx i18n medusa                          # 使用配置文件默认设置
+npx i18n medusa --app my-app --tag main  # 自定义应用和标签
+npx i18n medusa --output ./src/locales   # 自定义输出目录
+npx i18n medusa --no-merge               # 不合并，直接覆盖
 ```
 
-这个命令会：
-1. 从 Medusa 平台拉取指定应用的翻译文件
-2. 自动将语言标签转换为小写（如 en-US → en-us）
-3. 支持合并现有文件或完全覆盖
-4. 生成多语言 JSON 文件
+支持的选项：
 
-#### 命令选项
+| 选项 | 说明 |
+|------|------|
+| `-c, --config <path>` | 配置文件路径 |
+| `-o, --output <dir>` | 输出目录 |
+| `-a, --app <name>` | Medusa 应用名称 |
+| `-t, --tag <name>` | Medusa 标签名称 |
+| `--type <type>` | 包类型（json/android/ios） |
+| `--no-merge` | 不合并现有文件，直接覆盖 |
 
-```bash
-# 使用配置文件中的默认设置
-npx i18n medusa
+配置优先级：命令行参数 > 配置文件 > 默认值。
 
-# 指定配置文件
-npx i18n medusa --config ./my-i18n.config.js
+### install-skill — 安装 IDE i18n Skill
 
-# 自定义输出目录
-npx i18n medusa --output ./src/locales
+```bash
+npx i18n install-skill
+npx i18n install-skill --agent cursor qoder
+npx i18n install-skill --app-id 12345
+```
 
-# 自定义应用名称和标签
-npx i18n medusa --app my-app --tag main
+为 Cursor、Qoder、Claude Code、Codex、OpenCode 等 IDE 安装 i18n-helper skill。默认自动检测已有的 IDE 配置目录。
 
-# 指定包类型
-npx i18n medusa --type json
+## 翻译模式对比
 
-# 不合并现有文件，直接覆盖
-npx i18n medusa --no-merge
-```
+| | Agent 批量模式 (init-agent / patch-agent) | MT 机器翻译模式 (init / patch) |
+|---|---|---|
+| 翻译方式 | 批量翻译 | 逐条翻译 |
+| 速度 | 快（批量处理） | 较慢（支持并发控制） |
+| 翻译质量 | 一般 | 高（无上下文干扰） |
+| Key 生成 | 批量生成 | 保留文件路径结构 |
+| 错误隔离 | 批次粒度 | 单条粒度 |
+| 适用场景 | 大量文案初始化 | 高质量翻译、增量更新 |
 
-#### 配置说明
+### 性能调优
 
-命令会按以下优先级使用配置：
-1. **命令行参数**（最高优先级）
-2. **配置文件** (`i18n.config.js` 中的 `medusa` 配置)
-3. **默认值**（最低优先级）
+```javascript
+dashScope: {
+  // Agent 批量模式：调整每批数量，建议 50-200
+  batchSize: 50,
 
-支持的选项：
-- `-c, --config <path>`: 配置文件路径
-- `-o, --output <dir>`: 输出目录（覆盖配置文件）
-- `-a, --app <name>`: Medusa 应用名称（覆盖配置文件）
-- `-t, --tag <name>`: Medusa 标签名称（覆盖配置文件）
-- `--type <type>`: 包类型 json/android/ios（覆盖配置文件）
-- `--no-merge`: 不合并现有文件，直接覆盖
+  // MT 模式：需满足 1000 / mtDelay * mtConcurrency <= API rps 限制
+  mtConcurrency: 1,   // 并发数，建议 1-5
+  mtDelay: 1000,       // 批次间延迟（ms）
+  mtBatchSize: 25,     // 每次 API 调用翻译条数
+}
+```
 
-## 翻译模式对比
+## 忽略功能
 
-工具提供两种翻译模式，您可以根据需求选择：
+工具支持三种级别的忽略控制，优先级从高到低：
 
-### 批量翻译模式（init / patch）
+### 1. 文件级别忽略
 
-**特点：**
-- 🚀 **速度快**：每批可配置数量（默认100条）一起翻译
-- 💰 **成本低**：减少API调用次数
-- 📦 **批量处理**：适合大量文案的初始化场景
-- ⚙️ **可配置批次大小**：通过 `batchSize` 参数调整
+在文件**第一行**添加注释，跳过整个文件：
 
-**适用场景：**
-- 项目初始化，需要处理大量文案
-- 对翻译速度要求较高的场景
-- API调用成本敏感的项目
+```jsx
+// @i18n-ignore
+import React from 'react';
 
-### MT机器翻译模式（init-mt / patch-mt）
+const Component = () => {
+  return <div>这个文件中的所有中文都不会被处理</div>;
+};
+```
 
-**特点：**
-- 🎯 **精度高**：逐条翻译，避免批量翻译的上下文干扰
-- 🔧 **智能Key生成**：保留文件路径结构（如：`app.components.Button.confirmDelete`）
-- ⚡ **并发控制**：支持配置并发数，平衡速度与稳定性
-- 🕒 **延迟控制**：支持配置请求间隔，避免API限流
-- 📦 **批量调用**：每次API调用可翻译多条文案，应对速率限制
-- 🛡️ **稳定性好**：独立翻译每条文案，错误不会相互影响
+### 2. 块级别忽略
 
-**适用场景：**
-- 对翻译质量要求较高的项目
-- 需要精确key命名的场景
-- 增量更新，处理少量新增文案
+使用 `@i18n-ignore-block-start` / `@i18n-ignore-block-end` 包裹代码块：
 
-### 配置参数对比
+```jsx
+{/* @i18n-ignore-block-start */}
+<div>这个块中的所有文本都不会被处理</div>
+<span>这个也不会被处理</span>
+{/* @i18n-ignore-block-end */}
+```
 
-```javascript
-dashScope: {
-  // 批量翻译配置
-  batchSize: 50,        // 每批处理50条，默认100
+### 3. 行级别忽略
 
-  // MT翻译配置  
-  mtConcurrency: 3,     // 并发数3，默认1
-  mtDelay: 200,         // 批次间延迟200ms，默认100ms
-  mtBatchSize: 10,      // 每次API调用翻译10条，默认5
-}
+在行尾添加 `@i18n-ignore-line` 注释：
+
+```jsx
+<p>这行文本不会被处理 {/* @i18n-ignore-line */}</p>
+const message = '这个变量不会被处理'; // @i18n-ignore-line
 ```
 
 ## 多语言支持
 
-工具支持多语言翻译，配置 `valueTranslateAppId` 为对象格式：
+在 `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` - 日文
-- 等等...
-
-## Medusa 平台集成
-
-工具提供了与 Medusa 平台的深度集成，支持两个主要功能：
-
-### 1. 拉取翻译文件
-
-使用 `npx i18n medusa` 命令可以直接从 Medusa 平台拉取翻译文件：
-
-- **智能合并**: 默认情况下会合并现有文件，保留本地修改
-- **语言标签标准化**: 自动将语言标签转换为小写（如 en-US → en-us）
-- **多格式支持**: 支持 JSON、Android XML、iOS strings 等格式
-- **灵活配置**: 支持命令行参数和配置文件
-
-### 2. 生成 Excel 文件
-
-当配置了 `medusa` 选项时，工具会在 init 和 patch 命令的最后询问是否生成 Excel 文件。
-
-Excel 文件包含以下列：
-- **AppName**: 配置文件中的 `medusa.appName`
-- **Group**: 配置文件中的 `medusa.group`
-- **Key**: 翻译的 key
-- **其他列**: 根据 `medusa.keyMap` 配置，每列对应一种语言的翻译
-
-文件命名格式：`medusa-translations-YYYY-MM-DD.xlsx`
+每种语言会生成对应的翻译文件（`zh-cn.json`、`en-us.json`、`ja-jp.json` 等）。
 
 ## 代码示例
 
 ### 翻译前
+
 ```tsx
 const Form = () => {
   return (
@@ -434,6 +332,7 @@ const Form = () => {
 ```
 
 ### 翻译后
+
 ```tsx
 import $i18n from '@/i18n';
 
@@ -449,6 +348,7 @@ const Form = () => {
 ```
 
 ### 还原后
+
 ```tsx
 const Form = () => {
   return (
@@ -461,85 +361,31 @@ const Form = () => {
 };
 ```
 
-## 翻译文件
-
-工具会生成以下文件：
-
-- `src/locales/zh-cn.json`: 中文翻译文件
-- `src/locales/en-us.json`: 英文翻译文件
-- `src/locales/ja-jp.json`: 日文翻译文件
-- 等等...
-
-## 环境变量
-
-创建 `.env` 文件：
-
-```env
-# DashScope API 配置
-DASH_SCOPE_API_KEY=your_api_key_here
-DASH_SCOPE_MUST_KEY_TRANSLATE_APP_ID=your_key_translate_app_id
-DASH_SCOPE_MUST_VALUE_TRANSLATE_APP_ID=your_value_translate_app_id
+## 注意事项
 
-# Medusa 平台配置（可选）
-MEDUSA_HOST=https://medusa.alibaba-inc.com
-```
+1. 使用前请确保 `.env` 中已填写 `DASHSCOPE_APIKEY`
+2. `reverse` 命令会永久删除国际化代码，请谨慎使用
+3. 忽略标记必须出现在注释中，字符串中的标记不会被识别
+4. Medusa 拉取功能需要确保网络连接到 Medusa 平台
+5. MT 翻译的并发参数需满足 `1000 / mtDelay * mtConcurrency <= API rps 限制`
+6. 错误日志自动记录到 `logs/` 目录下（`api-errors.log`、`translation-errors.log`、`mt-translation-errors.log`）
 
 ## 开发
 
 ```bash
 # 安装依赖
-npm install
+pnpm install
 
 # 运行测试
-npm test
+pnpm test
 
 # 代码格式化
-npm run format
+pnpm run format
 
 # 代码检查
-npm run lint
+pnpm run lint
 ```
 
-## 注意事项
-
-1. 确保 DashScope API 配置正确
-2. 翻译文件会保存在 `localesFilePath` 指定的目录中
-3. i18n 实例文件会复制到 `i18nFilePath` 指定的目录中
-4. Excel 文件会保存在翻译文件目录中
-5. 工具会自动处理文件编码和格式问题
-6. reverse 命令会永久删除国际化代码，请谨慎使用
-7. **忽略功能**：
-   - 文件级别忽略优先级最高，会完全跳过文件处理
-   - 块级别忽略支持嵌套，会正确处理最近的 start 和 end 标记
-   - 行级别忽略在块级别忽略中仍然有效
-   - 所有忽略标记必须出现在注释中，字符串中的标记不会被误判
-   - 工具会自动过滤只包含标点符号或 emoji 的文本
-8. **Medusa 拉取功能**：
-   - 需要确保网络连接到 Medusa 平台
-   - 默认合并现有文件，使用 `--no-merge` 可直接覆盖
-   - 语言标签会自动转换为小写格式
-   - 支持从配置文件读取默认设置，命令行参数优先级更高
-9. **错误日志功能**：
-   - API 调用失败时会自动记录到 `logs/api-errors.log` 文件
-   - 翻译结果解析失败时会自动记录到 `logs/translation-errors.log` 文件
-   - MT翻译错误会记录到 `logs/mt-translation-errors.log` 文件
-   - 日志文件包含详细的错误信息、请求上下文和时间戳
-   - 日志目录会在首次错误时自动创建
-10. **MT翻译功能**：
-    - MT翻译会替换原key的下标部分，保留文件路径结构
-    - 合理配置并发数，过高可能导致API限流，建议1-5之间
-    - 并发翻译支持错误隔离，单个翻译失败不影响其他翻译
-    - MT翻译适合对质量要求高的场景，批量翻译适合大规模处理
-11. **性能调优建议**：
-    - 批量翻译：调整 `batchSize` 参数，建议50-200之间
-    - MT翻译：调整 `mtConcurrency`、`mtDelay` 和 `mtBatchSize` 参数平衡速度与稳定性
-    - 针对API速率限制：增加 `mtBatchSize` 减少调用次数，或增加 `mtDelay` 控制调用频率
-    - 网络不稳定时建议降低并发数和增加延迟时间
-
-## 贡献
-
-欢迎提交 Pull Request 或创建 Issue。
-
 ## 许可证
 
 MIT

package/lib/cli.js

@@ -186,6 +186,57 @@ withCommonOptions(
   }
 });
 
+program
+  .command('init-config')
+  .description('Create i18n.config.js configuration file from template')
+  .action(async () => {
+    try {
+      const cwd = process.cwd();
+      const configPath = path.resolve(cwd, 'i18n.config.js');
+
+      if (fs.existsSync(configPath)) {
+        console.error('❌ i18n.config.js 已存在，如需重新生成请先删除已有文件');
+        process.exit(1);
+      }
+
+      const templatePath = path.join(__dirname, '../i18n.config.example.js');
+      if (!fs.existsSync(templatePath)) {
+        throw new Error(`模板文件未找到: ${templatePath}`);
+      }
+
+      fs.copySync(templatePath, configPath);
+
+      // 检查 .env 文件是否存在
+      const envPath = path.resolve(cwd, '.env');
+      if (!fs.existsSync(envPath)) {
+        fs.writeFileSync(envPath, 'DASHSCOPE_APIKEY=\n', 'utf8');
+        console.log('📝 已创建 .env 文件，请填写 DASHSCOPE_APIKEY');
+      }
+
+      // 检查 .gitignore 中是否包含 .env
+      const gitignorePath = path.resolve(cwd, '.gitignore');
+      if (fs.existsSync(gitignorePath)) {
+        const gitignoreContent = fs.readFileSync(gitignorePath, 'utf8');
+        if (!gitignoreContent.includes('.env')) {
+          fs.appendFileSync(gitignorePath, '\n.env\n', 'utf8');
+          console.log('📝 已将 .env 添加到 .gitignore');
+        }
+      }
+
+      console.log('');
+      console.log('✅ i18n.config.js 已创建！');
+      console.log(`📁 路径: ${configPath}`);
+      console.log('');
+      console.log('💡 后续步骤:');
+      console.log('   1. 根据项目需要修改 i18n.config.js 中的配置');
+      console.log('   2. 在 .env 文件中填写 DASHSCOPE_APIKEY');
+      console.log('   3. 运行 npx i18n init 初始化翻译');
+    } catch (error) {
+      console.error('❌ 创建配置文件失败:', error.message);
+      process.exit(1);
+    }
+  });
+
 program
   .command('install-skill')
   .description('Install i18n-helper skill for Cursor / Qoder / Claude Code and other IDEs')

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentscope-ai/i18n",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "description": "A tool for translating Chinese content in frontend code repositories",
   "keywords": [
     "i18n",

package/skills/i18n-helper/SKILL.md

@@ -105,29 +105,51 @@ description: 国际化(i18n)自动化助手。当用户要对项目目录执行i
 
    使用 Chrome DevTools MCP 的 `new_page`（不要用 `navigate_page`，它会关闭当前页）打开上述 URL。
 
-3. **操作美杜莎页面（一次快照完成所有操作）**
+3. **操作美杜莎页面（最小化交互次数）**
 
-   页面加载后调用 `take_snapshot` 获取快照，从快照中识别以下元素的 uid：
-   - `zh_CN` textarea（`value="当前中文值"`）
-   - `en_US` textarea（`value="当前英文值"`）
+   使用 `wait_for` 等待 `en_US` 或 `zh_CN` 文本出现（它会自动返回快照，无需再调 `take_snapshot`）。从快照中识别：
+   - `zh_CN` textarea、`en_US` textarea 的 uid
    - 标签区域是否已有 `do_not_trans`
+   - 「保存」按钮 uid
 
-   然后**批量执行**以下操作：
+   **只修改用户指定的语言**，未指定的不要动。按以下顺序操作：
 
-   a. **填入文案** — 通过 `evaluate_script` 设置 textarea 的值（`fill` 会追加而非替换）：
+   a. **填入文案** — 对每个需要修改的 textarea，通过 `evaluate_script` 设置值（可以在**一次调用**中同时处理多个 textarea）：
       ```javascript
-      (el) => {
-        const setter = Object.getOwnPropertyDescriptor(window.HTMLTextAreaElement.prototype, 'value').set;
-        setter.call(el, '<新文案>');
-        el.dispatchEvent(new Event('input', { bubbles: true }));
-        el.dispatchEvent(new Event('change', { bubbles: true }));
-        return el.value;
+      (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 标签** — 如果快照中标签区域没有 `do_not_trans`：点击标签 combobox → 从下拉列表中点击 `do_not_trans` 选项 → 按 Escape 关闭下拉
+   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. **保存并发布** — 点击「保存」按钮保存修改，然后点击「立即发布」按钮。截图展示当前状态，等待用户确认后再继续操作
+   c. **保存并发布** — 点击「保存」按钮（带 `includeSnapshot: true` 确认结果），然后截图展示当前状态，等待用户确认后再点击「立即发布」按钮。
 
 ## 注意事项