Agentscope AI I18n

用于百炼内部的国际化工具，支持智能翻译和多语言管理。

特性

• 🔍 自动检测并提取中文文本
• 🤖 支持 AI 智能翻译（支持多语言）
• 🚀 新增MT机器翻译：支持单条翻译，翻译质量更高
• ⚡ 并发控制：MT翻译支持可配置的并发数和延迟控制
• 📏 批量配置：批量翻译支持可配置的批次大小
• 🔄 支持 JSX/TSX 文件解析
• 🔑 智能生成翻译 key（MT模式下保留文件路径结构）
• ✅ 支持翻译 key 使用检查
• 📊 生成 Medusa Excel 文件用于翻译管理
• 🌍 从 Medusa 平台拉取翻译文件
• 🔄 支持增量更新
• ↩️ 支持国际化代码还原为中文
• ⚙️ 可配置的文件匹配模式
• 🛠️ 简单易用的命令行工具
• 🚫 支持多种忽略功能（文件级别、行级别、块级别）
• 🎯 智能过滤标点符号和 emoji

安装

# 使用 npm
npm install @ali/agentscope-ai-i18n

# 使用 yarn
yarn add @ali/agentscope-ai-i18n

配置

在项目根目录创建 i18n.config.js 文件：

module.exports = {
  // 不需要翻译的文件和路径列表
  doNotTranslateFiles: ['node_modules', 'dist', '.git', 'tests/locales'],

  // 要处理的文件类型
  fileType: '.tsx,.ts,.js,.jsx',

  // 需要翻译的文件目录
  targetPath: './src',

  // 翻译文件输出目录
  localesFilePath: './src/locales',

  // i18n实例文件输出目录
  i18nFilePath: './src/i18n',

  // 翻译key的前缀
  keyPrefix: 'app',

  // i18n函数导入路径
  functionImportPath: '@/i18n',

  // DashScope API配置
  dashScope: {
    // 翻译key的大模型工作流appId
    keyTranslateAppId: 'your-key-translate-app-id',

    // 翻译value的大模型工作流appId（支持多语言）
    valueTranslateAppId: {
      'en-us': 'your-en-translate-app-id',
      'ja-jp': 'your-ja-translate-app-id',
      // 可以添加更多语言
    },

    // API密钥
    apiKey: 'your-api-key',

    // 批量翻译配置（适用于init和patch命令）
    batchSize: 50, // 可选：每批处理的文案数量，默认100

    // MT翻译配置（适用于init-mt和patch-mt命令）
    mtConcurrency: 3, // 可选：MT翻译的并发数，默认1
    mtDelay: 200, // 可选：MT翻译批次间的延迟时间（毫秒），默认100ms
    mtBatchSize: 10, // 可选：MT翻译每次调用翻译的条数，默认5（用于应对API速率限制）
  },

  // Medusa 配置，用于生成 Excel 文件和从平台拉取翻译文件
  medusa: {
    // 应用名称
    appName: 'your-app-name',
    
    // 标签名称（用于拉取文件）
    tag: 'your-tag-name',
    
    // 包类型（用于拉取文件）json/android/ios
    type: 'json',
    
    // 输出目录（用于拉取文件）
    outputPath: './locales',
    
    // 是否合并现有文件（用于拉取文件）
    mergeExisting: true,
    
    // 分组名称（用于生成 Excel 文件）
    group: 'your-group-name',
    
    // 语言映射配置（用于生成 Excel 文件）
    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. 文件级别忽略

在文件的第一行添加注释来忽略整个文件：

// @i18n-ignore
import React from 'react';

const Component = () => {
  return <div>这个文件中的所有中文都不会被处理</div>;
};

或者：

/* @i18n-ignore */
import React from 'react';

const Component = () => {
  return <div>这个文件中的所有中文都不会被处理</div>;
};

2. 行级别忽略

使用 @i18n-ignore-line 来忽略特定行：

// 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 来忽略代码块：

{/* @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

使用

命令行

# 批量翻译模式
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 - 初始化翻译（批量模式）

npx i18n init

这个命令会：

1. 扫描指定目录中的文件
2. 提取中文文案
3. 生成翻译 key
4. 批量翻译为配置的多语言（每批可配置数量）
5. 替换代码中的中文为国际化函数调用
6. 询问是否生成 Medusa Excel 文件

init-mt - 初始化翻译（MT模式）

npx i18n init-mt

新增功能，这个命令会：

1. 扫描指定目录中的文件
2. 提取中文文案
3. 使用MT机器翻译逐条生成翻译key（保留文件路径结构）
4. 使用MT机器翻译逐条翻译为配置的多语言
5. 支持并发控制，提高翻译效率
6. 替换代码中的中文为国际化函数调用
7. 询问是否生成 Medusa Excel 文件

patch - 增量更新（批量模式）

npx i18n patch

这个命令会：

1. 扫描新增的中文文案
2. 只翻译新增的内容（批量模式）
3. 更新现有的翻译文件
4. 询问是否生成 Medusa Excel 文件

patch-mt - 增量更新（MT模式）

npx i18n patch-mt

新增功能，这个命令会：

1. 扫描新增的中文文案
2. 使用MT机器翻译逐条处理新增内容
3. 支持并发控制，提高更新效率
4. 更新现有的翻译文件
5. 询问是否生成 Medusa Excel 文件

check - 检查翻译状态

npx i18n check

这个命令会：

1. 检查代码中使用的翻译 key
2. 对比翻译文件的完整性
3. 显示缺失和未使用的 key
4. 询问是否删除未使用的 key

reverse - 还原国际化代码

npx i18n reverse

这个命令会：

1. 扫描文件中的 $i18n.get 调用
2. 提取 dm（default message）参数作为中文文本
3. 替换 $i18n.get 调用为原始中文文本
4. 删除 $i18n 的导入语句

medusa - 从 Medusa 平台拉取翻译文件

npx i18n medusa

这个命令会：

1. 从 Medusa 平台拉取指定应用的翻译文件
2. 自动将语言标签转换为小写（如 en-US → en-us）
3. 支持合并现有文件或完全覆盖
4. 生成多语言 JSON 文件

命令选项

# 使用配置文件中的默认设置
npx i18n medusa

# 指定配置文件
npx i18n medusa --config ./my-i18n.config.js

# 自定义输出目录
npx i18n medusa --output ./src/locales

# 自定义应用名称和标签
npx i18n medusa --app my-app --tag main

# 指定包类型
npx i18n medusa --type json

# 不合并现有文件，直接覆盖
npx i18n medusa --no-merge

配置说明

命令会按以下优先级使用配置：

1. 命令行参数（最高优先级）
2. 配置文件 (i18n.config.js 中的 medusa 配置)
3. 默认值（最低优先级）

支持的选项：

• -c, --config <path>: 配置文件路径
• -o, --output <dir>: 输出目录（覆盖配置文件）
• -a, --app <name>: Medusa 应用名称（覆盖配置文件）
• -t, --tag <name>: Medusa 标签名称（覆盖配置文件）
• --type <type>: 包类型 json/android/ios（覆盖配置文件）
• --no-merge: 不合并现有文件，直接覆盖

翻译模式对比

工具提供两种翻译模式，您可以根据需求选择：

批量翻译模式（init / patch）

特点：

• 🚀 速度快：每批可配置数量（默认100条）一起翻译
• 💰 成本低：减少API调用次数
• 📦 批量处理：适合大量文案的初始化场景
• ⚙️ 可配置批次大小：通过 batchSize 参数调整

适用场景：

• 项目初始化，需要处理大量文案
• 对翻译速度要求较高的场景
• API调用成本敏感的项目

MT机器翻译模式（init-mt / patch-mt）

特点：

• 🎯 精度高：逐条翻译，避免批量翻译的上下文干扰
• 🔧 智能Key生成：保留文件路径结构（如：app.components.Button.confirmDelete）
• ⚡ 并发控制：支持配置并发数，平衡速度与稳定性
• 🕒 延迟控制：支持配置请求间隔，避免API限流
• 📦 批量调用：每次API调用可翻译多条文案，应对速率限制
• 🛡️ 稳定性好：独立翻译每条文案，错误不会相互影响

适用场景：

• 对翻译质量要求较高的项目
• 需要精确key命名的场景
• 增量更新，处理少量新增文案

配置参数对比

dashScope: {
  // 批量翻译配置
  batchSize: 50,        // 每批处理50条，默认100

  // MT翻译配置  
  mtConcurrency: 3,     // 并发数3，默认1
  mtDelay: 200,         // 批次间延迟200ms，默认100ms
  mtBatchSize: 10,      // 每次API调用翻译10条，默认5
}

多语言支持

工具支持多语言翻译，配置 valueTranslateAppId 为对象格式：

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

代码示例

翻译前

const Form = () => {
  return (
    <form>
      <label>用户名：</label>
      <input placeholder="请输入用户名" />
      <button>提交</button>
    </form>
  );
};

翻译后

import $i18n from '@/i18n';

const Form = () => {
  return (
    <form>
      <label>{$i18n.get({ id: 'app.username', dm: '用户名：' })}</label>
      <input placeholder={$i18n.get({ id: 'app.enter_username', dm: '请输入用户名' })} />
      <button>{$i18n.get({ id: 'app.submit', dm: '提交' })}</button>
    </form>
  );
};

还原后

const Form = () => {
  return (
    <form>
      <label>用户名：</label>
      <input placeholder="请输入用户名" />
      <button>提交</button>
    </form>
  );
};

翻译文件

工具会生成以下文件：

• src/locales/zh-cn.json: 中文翻译文件
• src/locales/en-us.json: 英文翻译文件
• src/locales/ja-jp.json: 日文翻译文件
• 等等...

环境变量

创建 .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

开发

# 安装依赖
npm install

# 运行测试
npm test

# 代码格式化
npm run format

# 代码检查
npm 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