多语言翻译工具，实现 自动翻译 + 翻译复用 + 校对闭环，降低多语言维护成本。
- 自动翻译：新增/修改文案自动生成目标语言内容
- 增量更新：仅翻译新增或修改文案，保证文案的一致性
- 校对闭环：修数据 + 运行导出（i18n.db.json → i18n run → 各语言包）
- 多语言支持：支持任意目标语言，可扩展术语表(无需翻译的术语)，词汇表(特定翻译的术语)
- 大模型支持：支持任意OpenAI兼容大模型
npm install -g @zdoc.app/i18n-clii18n init会在当前目录生成 i18n.config.json，需要根据项目情况调整配置：
export const defaultConfig: I18nConfig = {
source_file: 'src/locale/en-US.json', // 主语言文件, 相对于执行命令的路径，需要根据实际情况修改
source_lang: 'en-US', // 主语言
target_langs: ['zh-CN'], // 需要翻译的目标语言列表, 可配置多个
db_file: 'i18n.db.json', // 翻译缓存文件, 默认在当前目录生成，一般不需要修改
service: {
provider: 'deepseek', // 该字段在程序中未使用，可忽略
model: 'deepseek-chat', // 大模型名称，需要根据实际使用的服务商修改
base_url: 'https://api.deepseek.com', // API 请求地址，需要根据实际使用的服务商修改
api_key: '{{OPENAI_API_KEY}}', // API Key，支持使用环境变量 {{VAR_NAME}} 的形式, 也可直接写入实际的 key
temperature: 0.3, // https://api-docs.deepseek.com/zh-cn/quick_start/parameter_settings
max_tokens: 4000, // 程序目前按照 1000 tokens 拆分请求，max_tokens 保持 4000 即可
compress_keys: false, // 开启后，在将语言数据提交到大模型前，会将 key 替换为递增数字，节约 token, 但会丢失 key 部分的语义信息，可能会影响翻译效果
},
/**
* 特定翻译的词汇表
* ```json
* e.g: {
* "zh-CN": [{ "Crypto": "加密货币" }],
* "ja": [{ "Crypto": "暗号通貨" }]
* }
* ```
*/
glossary: {},
/** 无需翻译的词汇、术语 */
non_translatable: [],
output: {
format: 'nested', // nested | flat 输出的语言包风格，需要和主语言包一致（注意 key 不要使用英文句号， 否则可能会导致导出的语言包结构出现异常）
indent: 2, // JSON 缩进
},
/**
* 提示词模版-可根据自身需要随意调整提示词模版
*
* 以下固定占位符会在构建提示词阶段替换为实际值，可根据需要调整位置，不要修改名称：
* {{language}}
* {{glossary}}
* {{nonTranslatable}}
*/
prompt_template: `你是一名专业的前端本地化(i18n)翻译专家，专门处理 Web 界面文案翻译。
# 翻译任务
将以下 JSON 对象中的界面文案翻译成{{language}}，用于网页显示
# 必须遵守的规则
- 保持所有 key 完全不变
- 准确翻译 value 部分为目标语言：{{language}}
- 保留所有动态占位符及其原始格式，如：{xxx}
- 空字符串、纯数字、URL、HTML 标签、CSS 类名等非文本内容保持原样
- 针对按钮文本、菜单项、标签、提示语等界面元素，使用简洁明了的表达
- 确保翻译后的文本长度适合界面布局，避免过长影响显示
{{glossary}}
{{nonTranslatable}}
# 输出要求
- 只输出完整且合法的 JSON 对象
- 不要包含任何额外文本、注释或说明
- 保持与输入完全相同的 JSON 结构和格式
# 网页文案翻译指南
- 按钮文本：使用动词或动作短语，保持简短
- 菜单项：使用名词或动宾短语
- 标签和标题：保持清晰准确
- 提示信息：符合当地语言习惯
- 错误信息：提供明确的操作指引
# 输入示例
{
"button.submit": "Submit",
"menu.dashboard": "Dashboard",
"title.welcome": "Welcome, {username}!",
"error.required": "This field is required",
"tooltip.search": "Search for products"
}
# 输出示例（目标语言：简体中文）
{
"button.submit": "提交",
"menu.dashboard": "控制面板",
"title.welcome": "欢迎，{username}！",
"error.required": "此字段为必填项",
"tooltip.search": "搜索商品"
}
现在请翻译以下 JSON 内容：
`,
};i18n run- 解析主语言包
- 对比缓存
- 生成或复用翻译
- 输出目标语言包（如
zh-CN.json、es.json）
i18n check- 检查文案条数是否一致
- 确认每条主语言文案都有译文
i18n.db.json 保存原文、翻译， 作为语言包数据来源：
{
"sourceLang": "en-US",
"entries": {
"key1": { "en-US": "Log in", "zh-CN": "登录", "last_update": "2025-09-16T16:28:00Z" }
}
}| 命令 | 功能 |
|---|---|
i18n init |
初始化配置 |
i18n run |
翻译 & 导出语言包 |
i18n check |
校验语言包完整性 |
i18n export |
将语言数据导出为 excel |
i18n import |
从 excel 导入数据，更新数据文件 i18n.db.json |
- 开发新增文案 → 执行
i18n run - 校对修改
i18n.db.json - 再次执行
i18n run→ 更新语言包
已支持导出 excel 文件，校对人员可基于 excel 文件修改文案，修改后再由开发者导入到数据文件后重新执行 run 即可：
i18n export导出为 excel- 校对&修改
i18n import -s i18n.xlsx导入数据i18n run重新导出语言包
完整列表查看：src/constants/languages.ts
/**
* 支持的语言列表, 主要用于构建 prompt
*
* config.source_lang & config.target_langs 中的语言代码必须在此列表中有对应项
*
* key: 语言代码，可使用 iso 639 1 标准，如： en, zh, fr 等。如需支持其它格式语言代码（如 IETF BCP 47），可补充相关映射，如： zh-CN, zh-TW, pt-BR 等
* value: 语言名称（中文 + 该语言自称）- 非严格规范，主要用于大模型理解目标语言。
*/
export const languages = {
zh: '简体中文',
'zh-CN': '简体中文',
'zh-TW': '繁体中文-台湾 (繁體中文-台湾)',
en: '英语 (English)',
'en-US': '英语 (English)',
es: '西班牙语 (Español)',
fr: '法语 (Français)',
ru: '俄语 (Русский)',
pt: '葡萄牙语 (Português)',
};- 不会重复翻译未变化内容
- 增量翻译新增内容
- 主动修改译文后(修改 db)，可以导出正确的语言包
- 修改主语言文案，重新同步，译文会更新
- 修改主语言 key，语言包可以正确更新
- 支持压缩 key：使用数字替换，更稳定 & 节约 token （会丢失掉 key 部分的上下文）
- 支持专业术语-无需翻译的术语、特定用法
- 支持固定翻译-自定义某些词语的翻译，以便更贴合业务场景
- 语言包校对：文案条目数量一致
- 语言包校对：每条文案都有对应的译文
- 将提示词迁移至配置文件
- api_key 支持使用环境变量
- 导出 excel
- 导入 excel 更新翻译数据 i18n.db.json