teletype-cli

多语言管理工具，支持导出本地词条、对比线上词条，以及导入线上词条。让你告别手动百度单词再编辑多语言 json 文件的痛苦。

安装

npm i teletype-cli -g
# 或
yarn global add teletype-cli

配置文件

在项目根目录创建 teletype-config.js：

module.exports = {
  teletypeDir: "client/static/locales", // 项目多语言存放地址
  pageDir: 'client/containers',         // 页面文件的地址
  srcLang: "zh",                       // 基础多语言类型
  distLangs: ["en"],                   // 所需要的翻译的类型
  exportHeaders: {                      // 导出成excel时表头
    zh: '简体中文',
    en: '英语',
  },
  googleApiKey: "",                     // 谷歌翻译的api key
  baiduApiKey: {                        // 百度翻译配置
    appId: "YOUR_APP_ID",
    appKey: "YOUR_APP_KEY"
  },
  baiduLangMap: {                       // 百度翻译的语言映射
    "en-US": "en",
    "zh-TW": "cht",
  },
  translateOptions: {                    // 翻译选项
    concurrentLimit: 10,
    requestOptions: {}
  },
  defaultTranslateKeyApi: "Baidu",      // 默认使用的翻译软件
  ignoreDir: "",
  ignoreFile: "",
  formatter: (v, extra) => `t('${v}'${extra ? extra : ''})`,  // t函数调用格式
  importI18N: `import { useTranslation } from '@/utils/i18n'`, // i18n导入语句
  useI18NTranslation: file => `const { t } = useTranslation(['${file}'])` // t函数初始化
}

功能说明

1. 导出功能

支持两种模式：全量导出和差异导出。

# 全量导出
teletype --export

# 差异导出
teletype --export online-messages.json

全量导出：

• 遍历 locales/zh 目录下所有 JSON 文件
• 导出所有中文词条
• 如果 locales/en 下有对应的英文翻译，会一并导出
• 导出文件为 i18n-diff.xlsx

差异导出：

• 对比本地词条与线上词条的差异
• 如果本地词条在线上不存在，会被导出
• 如果线上有对应的英文翻译，使用线上的英文
• 如果线上没有对应的英文翻译，英文字段为空

注意：teletype-cli 是以线上多语言为主，本地对线上已有 key 的修改不会被 diff 出来。

2. 导入功能

teletype --import online-messages.json

导入规则：

• 采用并集策略
• 如果 key 在本地和线上都存在，使用线上的内容覆盖本地
• 如果 key 只在本地存在，会保留本地内容
• 如果 key 只在线上存在，会添加到本地
• 会自动导入文件中包含的所有语言版本

线上 JSON 文件格式示例：

{
  "zh": {
    "common.submit": "提交",
    "common.cancel": "取消"
  },
  "en": {
    "common.submit": "Submit",
    "common.cancel": "Cancel"
  }
}

3. 提取翻译

teletype --extract [file]

这里的 file 是需要翻译的文件夹相对于项目根目录的地址。建议按文件夹翻译，因为 teletype 会：

• 整合文件夹下所有 JSON 文件
• 按照子文件创建对应的 key 名
• 便于微应用拆分
• 自动复用已存在的翻译，避免重复翻译相同的中文文本
• 保持翻译 key 的一致性，相同的中文文本会使用相同的 key

示例：

# 翻译 stock 文件夹内的所有中文
teletype --extract client/containers/borrow/stock

翻译 key 处理规则：

1. 当遇到新的中文文本时，会生成一个新的 key，格式为：目录.文件.翻译key
2. 当遇到已存在的中文文本时，会复用已有的 key，确保相同的中文文本使用相同的翻译
3. 这样可以：
   • 减少重复翻译
   • 保持翻译的一致性
   • 避免出现多个不同的 key 指向相同的翻译文本

获取翻译 API 密钥

如何获取百度翻译 API 密钥：

1. 注册百度翻译开发者：https://fanyi-api.baidu.com/manage/developer
2. 在开发者信息中查看 API ID 和密钥

目录结构

推荐的多语言文件结构：

locales/
  ├── zh/
  │   ├── common.json   # 公共词条
  │   ├── access.json   # 模块词条
  │   └── ...
  └── en/
      ├── common.json   # 英文翻译
      ├── access.json
      └── ...