多语言维护太痛苦？我自研了一个翻译自动化 CLI 工具

大家好，我最近折腾了一个小工具 ------ i18n CLI 。

做这个东西的原因其实很简单：项目要上多语言了，手工维护翻译真的太痛苦了。

🌍 它能做什么

它只做一件事：自动化翻译你项目中的语言包

假设你的项目里有一个语言包文件：en.json 需要翻译成其它语言

只需要执行 i18n run 即可生成 zh.json， es.json...

🤯 遇到的问题

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

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

当文案一多，维护成本指数级上升。于是我萌生了一个想法：

👉 能不能搞一套 自动化翻译 + 缓存复用 + 校对闭环 的方案？

🎯 我的设计目标

我给自己定了几个原则：

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

🛠️ 整体架构

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

scss 复制代码

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

CLI 主要干三件事：

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

✨ 特性亮点

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

✅ 开源 & npm 包发布：一条命令安装，开箱即用
✅ 支持任何 OpenAI 兼容大模型：不管你用的是 OpenAI、DeepSeek 还是本地兼容接口，都能跑。
✅ 自定义提示词：提示词模板写在配置里，可以随意调整，想让模型更口语化/更正式都行。
✅ 专业术语保护：比如产品名、品牌名，标记后就不会被翻译。
✅ 固定翻译：一些业务词汇可以强制固定，比如：
- Buy → 买入
- Sell → 卖出
✅ 导出 Excel：可导出 Excel，方便非技术同学参与校对。
✅ key 压缩（可选）：用数字代替 key，节省 token，提高效率。

🔑 核心功能

常用命令：

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

整个流程就是：

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

📦 配置文件长什么样？

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

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

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 界面文案翻译。\n\n# 翻译任务\n将以下 JSON 对象中的界面文案翻译成{{language}}，用于网页显示\n\n# 必须遵守的规则\n- 保持所有 key 完全不变\n- 准确翻译 value 部分为目标语言：{{language}}\n- 保留所有动态占位符及其原始格式，如：{xxx}\n- 空字符串、纯数字、URL、HTML 标签、CSS 类名等非文本内容保持原样\n- 针对按钮文本、菜单项、标签、提示语等界面元素，使用简洁明了的表达\n- 确保翻译后的文本长度适合界面布局，避免过长影响显示\n{{glossary}}\n{{nonTranslatable}}\n\n# 输出要求\n- 只输出完整且合法的 JSON 对象\n- 不要包含任何额外文本、注释或说明\n- 保持与输入完全相同的 JSON 结构和格式\n\n# 网页文案翻译指南\n- 按钮文本：使用动词或动作短语，保持简短\n- 菜单项：使用名词或动宾短语\n- 标签和标题：保持清晰准确\n- 提示信息：符合当地语言习惯\n- 错误信息：提供明确的操作指引\n\n# 输入示例\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}\n\n# 输出示例（目标语言：简体中文）\n{\n  \"button.submit\": \"提交\",\n  \"menu.dashboard\": \"控制面板\",\n  \"title.welcome\": \"欢迎，{username}！\",\n  \"error.required\": \"此字段为必填项\",\n  \"tooltip.search\": \"搜索商品\"\n}\n\n现在请翻译以下 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，一起完善这个工具