@ali/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 @ali/agentscope-ai-i18n

快速开始

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

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

# 3. 在 .env 文件中填写 DASHSCOPE_APIKEY

# 4. 初始化翻译（默认使用 MT 引擎）
npx i18n init

# 5. 后续新增文案时，增量翻译
npx i18n patch

命令一览

| 命令 | 说明 | |------|------| | npx i18n init-config | 生成 i18n.config.js 配置文件 | | 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 |

通用选项

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

-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',
  i18nFilePath: './src/i18n',
  keyPrefix: 'app',
  functionImportPath: '@/i18n',

  dashScope: {
    keyTranslateAppId: '',
    valueTranslateAppId: {
      'en-us': '',
      'ja-jp': '',
    },
    apiKey: process.env.DASHSCOPE_APIKEY,
    batchSize: 50,
    mtConcurrency: 1,
    mtDelay: 1000,
    mtBatchSize: 25,
  },

  medusa: {
    appName: '',
    appId: '',
    tag: '',
    type: 'json',
    outputPath: './locales',
    mergeExisting: true,
    group: '',
    keyMap: {
      'en-us': 'English',
      'ja-jp': 'Japanese',
      'zh-cn': 'Simplified Chinese',
    },
  },
};

命令详解

init — 初始化翻译

npx i18n init                # 默认使用 MT 引擎
npx i18n init --engine agent # 使用 Agent 批量引擎

1. 扫描 targetPath 目录中的源文件
2. 提取中文文案
3. 使用选定引擎翻译生成 key 和多语言文件
4. 替换代码中的中文为 $i18n.get() 调用
5. 询问是否生成 Medusa Excel 文件

patch — 增量翻译

npx i18n patch                # 默认使用 MT 引擎
npx i18n patch --engine agent # 使用 Agent 批量引擎

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

check — 检查翻译状态

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 — 还原国际化代码

npx i18n reverse

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

translate / replace — 三步工作流

npx i18n translate           # Step 1: 只生成 locale 文件，不修改源码
npx i18n translate -f file   # 单文件模式
# Step 2: 同步到 Medusa（外部操作）
npx i18n replace             # Step 3: 替换源码中的中文

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

npx i18n medusa                          # 使用配置文件默认设置
npx i18n medusa --app my-app --tag main  # 自定义应用和标签
npx i18n medusa --output ./src/locales   # 自定义输出目录
npx i18n medusa --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。

翻译引擎对比

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

性能调优

dashScope: {
  batchSize: 50,       // Agent 批量模式：每批数量，建议 50-200
  mtConcurrency: 1,    // MT 模式并发数，建议 1-5
  mtDelay: 1000,       // MT 批次间延迟（ms）
  mtBatchSize: 25,     // MT 每次 API 调用翻译条数
}

忽略功能

1. 文件级别忽略

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

// @i18n-ignore
import React from 'react';
const Component = () => <div>这个文件中的所有中文都不会被处理</div>;

2. 块级别忽略

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

3. 行级别忽略

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

代码示例

翻译前

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

从旧版迁移

以下命令已弃用，但仍可使用（会提示迁移）：

| 旧命令 | 新命令 | |--------|--------| | 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 |

注意事项

1. 使用前请确保 .env 中已填写 DASHSCOPE_APIKEY
2. reverse 命令会永久删除国际化代码，请谨慎使用
3. 忽略标记必须出现在注释中，字符串中的标记不会被识别
4. Medusa 拉取功能需要确保网络连接到 Medusa 平台
5. MT 翻译的并发参数需满足 1000 / mtDelay * mtConcurrency <= API rps 限制
6. 错误日志自动记录到 logs/ 目录下

开发

pnpm install
pnpm test
pnpm run format
pnpm run lint

许可证

MIT