开源项目 MAR 05, 2026

ai-i18n-sync：AI 驱动的 i18n 翻译同步工具

#CLI#i18n#npm#开源
code GitHub package_2 npm

我写了一个 AI 国际化翻译同步工具，i18n 再也不用手动翻了

检测缺失 key → AI 翻译 → 增量同步，还有术语表保证翻译一致性。

背景：i18n 的最后一公里痛在哪

做过国际化的前端都知道，i18n 最烦的不是接入 vue-i18n / react-intl，而是——

翻译文件的维护。

你的 zh.json 有 200 个 key，然后你要把每一个翻译成英文、日文、韩文……

一开始你会老老实实翻。三个月后你就这样了：

// en.json — 只翻了 150 个，还有 50 个忘了
{
  "common.submit": "Submit",
  "common.cancel": "Cancel",
  // mall.order.refund_pending ← 丢了
  // mall.coupon.claim_success ← 丢了
}

用 Google Translate？翻出来的 UI 文案生硬得不能看。找专业翻译？一个 key 几块钱，200 个 key 就是几百块，还要等。

更要命的是同步问题：你在 zh.json 加了 10 个新 key，然后忘了同步到 en.json、ja.json。上线后日文用户看到一堆中文——出事了。

所以我做了这个工具：ai-i18n-sync —— 让 AI 帮你翻译和同步 i18n 文件。

npx ai-i18n-sync sync --source locales/zh.json --targets en,ja

一行命令：扫描 → 找出缺失的 key → AI 翻译 → 写回文件。只翻缺失的部分，已有翻译不动。

它能做什么

sync — 同步翻译

$ npx ai-i18n sync --source locales/zh.json --targets en

🔍  正在扫描 i18n 文件...
📄  Source: zh.json (142 keys)
📄  Target: en.json (130 keys)  ⚠️  12 missing

📋  发现 12 个缺失 key (en.json):
     + mall.order.refund_pending    "退款审核中"
     + mall.order.refund_approved   "退款已通过"
     + mall.coupon.claim_success    "领取成功"
     ... (9 more)

🤖  正在翻译 12 个 key → en...
     mall.order.refund_pending:  "退款审核中" → "Refund Under Review"
     mall.order.refund_approved: "退款已通过" → "Refund Approved"
     mall.coupon.claim_success:  "领取成功" → "Claimed Successfully"
     ... (9 more)

✅  已同步 12 个 key → en.json

🎉  翻译同步完成，共 12 个 key。

增量翻译：只翻缺失的 12 个 key，已有的 130 个不动。不会覆盖你手动调整过的翻译。

check — 检查完整性

不想翻译，只想知道缺了什么？

$ npx ai-i18n check

🔍  正在检查 i18n 完整性...

   zh.json                   142 keys  (source)
   en.json                   130 keys  ⚠️  12 missing
   ja.json                   128 keys  ⚠️  14 missing
   ko.json                   142 keys  ✅

❌  存在缺失 key，运行 `ai-i18n sync` 修复。

一眼看清哪个语言文件差了多少。CI 里可以当门禁：缺 key 就 exit(1) 阻断合并。

translate — 快速翻译

临时要翻一个词，不想打开 Google Translate？

$ npx ai-i18n translate "退款审核中" --to en,ja

🤖  翻译: "退款审核中"

   en: Refund Under Review
   ja: 返金審査中

30 秒上手

# 1. 配 Key
echo 'DEEPSEEK_API_KEY=sk-xxx' >> .env.local

# 2. 同步翻译
npx ai-i18n-sync sync --source src/locales/zh.json --targets en,ja

# 3. 检查完整性
npx ai-i18n-sync check

核心设计决策

增量翻译，不是全量覆盖

这是最重要的设计决策。工具会：

  1. 读 source 文件（如 zh.json），拿到所有 key
  2. 读 target 文件（如 en.json），拿到已有 key
  3. 只翻译 target 中缺失的 key
  4. 合并后写回，保留已有翻译不动

这意味着：

  • 你手动调整过的翻译不会被覆盖
  • 多次运行是幂等的——没有缺失 key 就什么都不做
  • 每次只花一点点 token 费用

术语表保证一致性

翻译最怕的就是不一致：同一个”订单”，有的地方翻成 “Order”，有的翻成 “Purchase”。

.ai-i18n-glossary.json 解决这个问题：

{
  "zh-en": {
    "订单": "Order",
    "优惠券": "Coupon",
    "购物车": "Shopping Cart",
    "收货地址": "Shipping Address",
    "退款": "Refund"
  },
  "zh-ja": {
    "订单": "注文",
    "优惠券": "クーポン"
  }
}

术语表会注入到 AI prompt 中，强制遵守。

业务上下文提升准确度

同一个”充值”，游戏平台翻成 “Top-up”，金融平台翻成 “Deposit”。通过 --context 告诉 AI 你的业务场景：

npx ai-i18n sync --source zh.json --targets en --context "跨境电商平台"

翻译准确度显著提升。也可以写在配置文件里，不用每次传：

{
  "context": "跨境电商平台"
}

保留文件格式

写回文件时：

  • key 顺序与 source 文件一致（方便 diff 对照）
  • 嵌套结构保持不变
  • 尾部换行符保留
  • 最小化 git diff

分批翻译

如果缺了 100 个 key，不会一次性塞进一个 prompt。按 batchSize（默认 30）分批调用 AI，避免 token 超限和响应超时。

支持嵌套结构

// zh.json
{
  "common": {
    "buttons": {
      "submit": "提交",
      "cancel": "取消"
    }
  },
  "mall": {
    "order": {
      "status": "订单状态",
      "refund_pending": "退款审核中"
    }
  }
}

工具会自动 flatten → 翻译 → unflatten，完整支持任意深度嵌套。

配置文件

npx ai-i18n init

生成两个文件：

.ai-i18n.json — 翻译配置

{
  "sourceLocale": "zh",
  "targetLocales": ["en"],
  "localesDir": "src/locales",
  "filePattern": "{locale}.json",
  "nested": true,
  "sortKeys": false,
  "context": "",
  "glossary": ".ai-i18n-glossary.json",
  "batchSize": 30,
  "model": ""
}

.ai-i18n-glossary.json — 术语表

{
  "zh-en": {
    "订单": "Order",
    "优惠券": "Coupon"
  }
}

两个文件都提交到 git，团队共享翻译规范。

6 大 AI 厂商

和 ai-review-pipeline / ai-git-msg 共享环境变量，配过一次直接能用：

Provider默认模型翻译 30 个 key 约
DeepSeekdeepseek-chat¥0.01
OpenAIgpt-4o-mini$0.005
Ollamaqwen2.5-coder免费
Claudeclaude-sonnet-4$0.01
Geminigemini-2.0-flash免费额度内

DeepSeek 翻一整套 200 key 的 i18n 文件大概几毛钱，比人工翻译便宜几百倍。

真实使用场景

场景一：日常开发同步

你在 zh.json 加了 5 个新 key，跑一下：

npx ai-i18n sync

自动补上 en.json 和 ja.json 里缺的 5 个。

场景二：CI 门禁

GitHub Actions 里加一个 step：

- name: Check i18n completeness
  run: npx ai-i18n-sync check

缺 key 就阻断 PR 合并，防止遗漏。

场景三：接手老项目

接了一个只有中文的项目，要加多语言支持：

npx ai-i18n sync --source zh.json --targets en,ja,ko

一次性生成所有语言文件。

场景四：快速翻译查词

开发时临时要知道一个词怎么翻：

npx ai-i18n translate "结算中" --to en,ja

比打开 Google Translate 快。

常用命令速查

# 同步翻译
npx ai-i18n sync --source locales/zh.json --targets en,ja
npx ai-i18n sync --context "跨境电商平台"
npx ai-i18n sync --dry-run                        # 只展示不写入

# 检查完整性
npx ai-i18n check
npx ai-i18n check --strict                        # 多余 key 也报错

# 快速翻译
npx ai-i18n translate "用户管理" --to en,ja

# 初始化
npx ai-i18n init

和同类方案的对比

维度ai-i18n-synci18next-scanner人工翻译
翻译质量AI 自然语言，支持术语表不翻译最高
翻译成本200 key ≈ 几毛钱免费200 key ≈ ¥500
缺失检测✅✅靠人检查
增量翻译✅ 只翻缺失的❌需要指定范围
术语一致性✅ 术语表❌靠翻译记忆
速度30 key ≈ 3 秒即时1-3 天
依赖零多无

工具链

这是我做的 AI 开发工具链的第三个工具：

代码编写
   │
   ├── ai-review-pipeline ── 代码质量审查
   │         npx ai-review-pipeline
   │
   ├── ai-git-msg ── 提交信息生成
   │         npx ai-git-msg
   │
   └── ai-i18n-sync ── 国际化翻译同步       ← 你在这里
              npx ai-i18n-sync

三个工具共享同一套环境变量和 AI Provider，配一次 Key 全家用。

开源地址

npx ai-i18n-sync sync --source locales/zh.json --targets en,ja

试试看，3 秒搞定你的 i18n 翻译。

如果对你有帮助，给个 ⭐ 或者掘金点个赞，是我继续迭代的动力。

有问题或建议欢迎提 issue 或评论区交流。

评论