大家好，我最近折腾了一个小工具 —— i18n CLI。
做这个东西的原因其实很简单：项目要上多语言了，手工维护翻译真的太痛苦了。

🌍 它能做什么

它只做一件事：自动化翻译你项目中的语言包
假设你的项目里有一个语言包文件：en.json 需要翻译成其它语言
只需要执行 i18n run 即可生成 zh.json， es.json...

🤯 遇到的问题

相信做过国际化的同学都懂：

1. 翻译滞后：新增文案没人翻，或者一拖再拖。
2. 不同步：主语言（比如 en.json）改了，译文语言包还在用老的。
3. key 变更灾难：开发随手一改 key，其他语言直接废掉。
4. 校对难：翻译人员不会直接改代码里的 json，最后大家一通 copy/paste。
5. 这些问题一旦叠加，维护成本会直接爆炸

当文案一多，维护成本指数级上升。于是我萌生了一个想法：
👉 能不能搞一套 自动化翻译 + 缓存复用 + 校对闭环 的方案？

🎯 我的设计目标

我给自己定了几个原则：

• 自动化：新增/修改文案时，自动补全翻译。
• 一致性：后续迭代只更新变化的部分，未变化的文案不需再次翻译
• 可追踪：数据库文件是“唯一真相”，改动有迹可循。
• 低侵入：不依赖外部 SaaS，团队能直接用。
• 可扩展：未来可基于数据库文件，开发web页面供非技术人员校对、修改文案

🛠️ 整体架构

我的思路是用一个 CLI 工具来串起来：

主语言包 (en.json)
        ↓
   i18n CLI 工具
        ↓
  翻译缓存文件 (i18n.db.json)
        ↓
目标语言包 (zh-CN.json, es.json ...)

CLI 主要干三件事：

1. 解析主语言包
2. 比对缓存（i18n.db.json）
3. 调用大模型，翻译并输出目标语言

✨ 特性亮点

这个工具不仅仅是“能用”，我还加了不少实用的功能：

• ✅ 开源 & npm 包发布：一条命令安装，开箱即用

• ✅ 支持任何 OpenAI 兼容大模型：不管你用的是 OpenAI、DeepSeek 还是本地兼容接口，都能跑。

• ✅ 自定义提示词：提示词模板写在配置里，可以随意调整，想让模型更口语化/更正式都行。

• ✅ 专业术语保护：比如产品名、品牌名，标记后就不会被翻译。

• ✅ 固定翻译：一些业务词汇可以强制固定，比如：

  • Buy → 买入
  • Sell → 卖出

• ✅ 导出 Excel：可导出 Excel，方便非技术同学参与校对。

• ✅ key 压缩（可选）：用数字代替 key，节省 token，提高效率。

🔑 核心功能

常用命令：

• i18n init → 初始化配置文件
• i18n run → 自动翻译 & 导出语言包
• i18n check → 校验语言包是否完整
• i18n export → 导出到 Excel（方便非技术人员校对）
• i18n import → Excel 导回 db，再生成语言包

整个流程就是：

1. 开发维护主语言包，如 en.json → 执行 i18n run 生成译文语言包 （大模型翻译效果很好，如果对译文要求不是特别严格，到这里就结束了）
2. 校对 → 修改 i18n.db.json 或 Excel
3. 再执行 i18n run → 重新更新所有语言包

📦 配置文件长什么样？

执行 i18n init 会生成一个 i18n.config.json，里面可以配主语言、目标语言、翻译服务商、大模型参数、术语表等等。

比如我自己项目里长这样：

{
  "source_file": "public/en.json",
  "source_lang": "en-US",
  "target_langs": [
    "zh-TW"
  ],
  "db_file": "i18n.db.json",
  "service": {
    "provider": "deepseek",
    "model": "deepseek-chat",
    "base_url": "https://api.deepseek.com",
    "api_key": "{{OPENAI_API_KEY}}",
    "temperature": 0.3,
    "max_tokens": 4000,
    "compress_keys": false
  },
  "glossary": {},
  "non_translatable": [],
  "output": {
    "format": "nested",
    "indent": 2
  },
  "prompt_template": "你是一名专业的前端本地化(i18n)翻译专家，专门处理 Web 界面文案翻译。nn# 翻译任务n将以下 JSON 对象中的界面文案翻译成{{language}}，用于网页显示nn# 必须遵守的规则n- 保持所有 key 完全不变n- 准确翻译 value 部分为目标语言：{{language}}n- 保留所有动态占位符及其原始格式，如：{xxx}n- 空字符串、纯数字、URL、HTML 标签、CSS 类名等非文本内容保持原样n- 针对按钮文本、菜单项、标签、提示语等界面元素，使用简洁明了的表达n- 确保翻译后的文本长度适合界面布局，避免过长影响显示n{{glossary}}n{{nonTranslatable}}nn# 输出要求n- 只输出完整且合法的 JSON 对象n- 不要包含任何额外文本、注释或说明n- 保持与输入完全相同的 JSON 结构和格式nn# 网页文案翻译指南n- 按钮文本：使用动词或动作短语，保持简短n- 菜单项：使用名词或动宾短语n- 标签和标题：保持清晰准确n- 提示信息：符合当地语言习惯n- 错误信息：提供明确的操作指引nn# 输入示例n{n  "button.submit": "Submit",n  "menu.dashboard": "Dashboard",n  "title.welcome": "Welcome, {username}!",n  "error.required": "This field is required",n  "tooltip.search": "Search for products"n}nn# 输出示例（目标语言：简体中文）n{n  "button.submit": "提交",n  "menu.dashboard": "控制面板",n  "title.welcome": "欢迎，{username}！",n  "error.required": "此字段为必填项",n  "tooltip.search": "搜索商品"n}nn现在请翻译以下 JSON 内容：n"
}

支持环境变量写法，不用把 API key 直接写死。

📑 数据文件设计

i18n.db.json 是核心，它既是缓存，又是译文数据源。
里面存了：

• entries：所有 key 对应的多语言翻译
• last_update：最后更新时间（方便追踪）
• glossary / nonTranslatable：术语表和不翻译的专有名词

这样一来，译文语言包不再是“真相”，而只是生成物。

✅ 实际效果

• 不用担心重复翻译：文案没变就直接复用旧翻译。
• key 改名也不怕：自动移除旧文案, 并添加新文案
• 翻译质量可控：大模型翻译 + 人工校对 → 回写到 db（大模型翻译效果杠杠的，如果对译文要求不是特别严格，翻译后的译文可直接上线）。
• 校对更方便：支持 Excel，非技术同学也能很容易参与校对。

🔮 后续打算

目前这个工具比较适合 中小团队，如果团队再大，可能要接入专业平台。
但我觉得这套流程够用，而且比 SaaS 自由度更高。

未来想优化的点：

• 提供可视化页面校对、修改译文
• 可直接在站点页面中标记、修改文案

🏁 总结

简单来说，我自研的这个 i18n CLI 做到了：

• 自动化翻译，减少重复劳动
• 翻译复用，保证一致性
• 校对闭环，翻译不会丢失
• 开源、npm 即装即用、自由定制

有了它，团队在做多语言时就能轻松很多，开发、翻译、校对的协作成本都降下来了。

👉 如果你个人或者团队在做国际化站点，可以试试这个工具，真的很强！

Github: github.com/zdocapp/i18…
NPM: www.npmjs.com/package/@zd…

欢迎提 issue 或 PR，一起完善这个工具