@agentscope-ai/i18n

前端代码仓库中文国际化工具，支持 AI 智能翻译和多语言管理。

特性

• 自动检测并提取中文文本
• 支持 AI Agent 翻译和 MT 机器翻译两种模式
• 支持 JSX/TSX/TS/JS 文件解析
• 智能生成翻译 key（MT 模式下保留文件路径结构）
• 支持翻译 key 使用检查与自动清理
• 集成 Medusa 翻译平台（拉取翻译文件、生成 Excel）
• 支持增量更新，只翻译新增文案
• 支持国际化代码还原为中文
• 支持文件级、块级、行级忽略控制
• 自动过滤纯标点符号和 emoji
• 一键安装 IDE AI 助手的 i18n skill（Cursor / Qoder / Claude Code 等）

安装

npm install @agentscope-ai/i18n

快速开始

# 1. 生成配置文件
npx i18n init-config

# 2. 修改 i18n.config.js 中的配置（targetPath、keyPrefix 等）

# 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 |

通用选项

大部分命令支持以下通用选项：

-c, --config <path>       # 指定配置文件路径（默认查找 i18n.config.js）
-p, --target-path <path>  # 覆盖配置中的 targetPath
--skip-confirm             # 跳过所有确认提示

配置

init-config — 生成配置文件

npx i18n init-config

将 i18n.config.example.js 模板复制到项目根目录作为 i18n.config.js，同时：

• 如果 .env 不存在，自动创建并写入 DASHSCOPE_APIKEY=
• 如果 .gitignore 中未包含 .env，自动追加

配置文件说明

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,     // 每批翻译条数
  },

  // Medusa 翻译平台配置（可选）
  medusa: {
    appName: '',
    appId: '',
    tag: '',
    type: 'json',
    outputPath: './locales',
    mergeExisting: true,
    group: '',
    keyMap: {
      'en-us': 'English',
      'ja-jp': 'Japanese',
      'zh-cn': 'Simplified Chinese',
    },
  },
};

命令详解

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

npx i18n init

1. 扫描 targetPath 目录中的源文件
2. 提取中文文案
3. 使用 MT 机器翻译逐条生成翻译 key（保留文件路径结构）
4. 翻译为配置的多语言
5. 替换代码中的中文为 $i18n.get() 调用
6. 询问是否生成 Medusa Excel 文件

init-agent — 初始化翻译（Agent 批量模式）

npx i18n init-agent

使用百炼 Agent 工作流进行批量翻译，适合大量文案的初始化场景。

patch / patch-mt — 增量翻译（MT 模式）

npx i18n patch

只扫描和翻译新增的中文文案，更新现有翻译文件。

patch-agent — 增量翻译（Agent 批量模式）

npx i18n patch-agent

使用百炼 Agent 工作流进行批量增量翻译。

check — 检查翻译状态

npx i18n check
npx i18n check --auto-delete-unused

1. 检查代码中使用的翻译 key
2. 对比翻译文件的完整性
3. 显示缺失和未使用的 key
4. --auto-delete-unused：自动删除未使用的 key

reverse — 还原国际化代码

npx i18n reverse

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

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

npx i18n medusa                          # 使用配置文件默认设置
npx i18n medusa --app my-app --tag main  # 自定义应用和标签
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

npx i18n install-skill
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 配置目录。

翻译模式对比

| | Agent 批量模式 (init-agent / patch-agent) | MT 机器翻译模式 (init / patch) | |---|---|---| | 翻译方式 | 批量翻译 | 逐条翻译 | | 速度 | 快（批量处理） | 较慢（支持并发控制） | | 翻译质量 | 一般 | 高（无上下文干扰） | | Key 生成 | 批量生成 | 保留文件路径结构 | | 错误隔离 | 批次粒度 | 单条粒度 | | 适用场景 | 大量文案初始化 | 高质量翻译、增量更新 |

性能调优

dashScope: {
  // Agent 批量模式：调整每批数量，建议 50-200
  batchSize: 50,

  // MT 模式：需满足 1000 / mtDelay * mtConcurrency <= API rps 限制
  mtConcurrency: 1,   // 并发数，建议 1-5
  mtDelay: 1000,       // 批次间延迟（ms）
  mtBatchSize: 25,     // 每次 API 调用翻译条数
}

忽略功能

工具支持三种级别的忽略控制，优先级从高到低：

1. 文件级别忽略

在文件第一行添加注释，跳过整个文件：

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

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

2. 块级别忽略

使用 @i18n-ignore-block-start / @i18n-ignore-block-end 包裹代码块：

{/* @i18n-ignore-block-start */}
<div>这个块中的所有文本都不会被处理</div>
<span>这个也不会被处理</span>
{/* @i18n-ignore-block-end */}

3. 行级别忽略

在行尾添加 @i18n-ignore-line 注释：

<p>这行文本不会被处理 {/* @i18n-ignore-line */}</p>
const message = '这个变量不会被处理'; // @i18n-ignore-line

多语言支持

在 valueTranslateAppId 中配置各语言对应的工作流 appId：

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 等）。

代码示例

翻译前

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>
  );
};

注意事项

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）

开发

# 安装依赖
pnpm install

# 运行测试
pnpm test

# 代码格式化
pnpm run format

# 代码检查
pnpm run lint

许可证

MIT