hltools

hltools 是一个面向前端项目的 i18n 翻译同步 CLI，用于把 Excel 或 Google Sheets 中的多语言表同步到项目语言文件。

当前支持：

• 读取本地 Excel 多语言表格
• 读取 Google Sheets 在线表格
• 生成或同步 Vue / TypeScript / JavaScript 多语言文件
• 复用已有 key，并在 key 为空时自动生成新 key

npm 包名：hltools-i18n

安装后的命令名：hltools

安装

全局安装：

npm install -g hltools-i18n

验证安装：

hltools --help
hltools --version

hltools --version 会显示当前已安装包的真实版本号。

升级：

npm update -g hltools-i18n

卸载：

npm uninstall -g hltools-i18n

快速上手

1. 配置 Google 凭证

首次使用 Google Sheets 前，先配置服务账号 JSON 凭证：

hltools config set --google-credentials D:/env/google-service-account.json

查看配置是否生效：

hltools config

2. 进入项目目录

在项目根目录或任意子目录执行命令。未传 -o / --out-dir 且配置中没有 excelToI18n.outDir 时，hltools 会从当前目录向上查找 src/language。

cd E:/project/demo

3. Google Sheets 同步

推荐短命令：

hltools gs "GoogleSheet链接或ID" -n mermaidTreasure

等价完整命令：

hltools google-sheet-to-i18n --sheet-id "GoogleSheet链接或ID" -n mermaidTreasure

需要指定输出目录时：

hltools gs "GoogleSheet链接或ID" -n mermaidTreasure -o D:/project/demo/src/language

4. 本地 Excel 同步

推荐短命令：

hltools x C:/Users/admin/Downloads/demo.xlsx -n mermaidTreasure

等价完整命令：

hltools excel-to-i18n --input C:/Users/admin/Downloads/demo.xlsx -n mermaidTreasure

需要指定 sheet：

hltools x C:/Users/admin/Downloads/demo.xlsx -n mermaidTreasure --sheet Sheet1

5. 常用配置命令

设置默认输出目录：

hltools config set --out-dir D:/project/demo/src/language

设置默认源语言：

hltools config set --source-locale en

设置默认 Google Sheet 链接：

hltools config set --google-sheet-id "GoogleSheet链接或ID"

如果设置了默认 Google Sheet 链接，可以省略链接：

hltools google-sheet-to-i18n -n mermaidTreasure

6. 交互式模式

如果给人工使用，可以直接运行交互式引导：

hltools

交互模式会引导选择：

• Google Sheet ID/链接
• Excel 文件路径
• 命名空间
• 输出目录
• key 列名
• 源语言列
• 输出格式
• Google 凭证路径

给 AI 或脚本调用

AI、CI 和自动化脚本应使用非交互式命令，并显式传入关键参数。不要让 AI 运行只包含 hltools 的交互式命令。

推荐：

hltools gs "GoogleSheet链接或ID" -n <namespace>

hltools x <excelPath> -n <namespace>

配置文件

hltools 现在使用 双层配置：

1. 默认配置：随 npm 包发布，位于安装目录中的 hltools.config.json
2. 用户配置：位于用户目录中的 ~/.hltools/config.json

运行时会按下面的优先级合并：

• 用户配置
• 默认配置

所以：

• 包升级后，默认配置可以更新
• 你自己的配置不会因为 npm i -g 被覆盖
• hltools config set 会写入用户配置，而不是安装目录

查看当前配置与两个配置文件路径：

hltools config

如果你只想看路径，可以直接：

hltools config path

如果需要手动编辑，优先修改用户配置文件：

• Windows 通常是：C:\Users\你的用户名\.hltools\config.json

默认配置示例：

{
  "excelToI18n": {
    "outDir": "D:/project/demo/src/language",
    "sourceLocale": "en",
    "outputFormat": "module",
    "localeHeaderMap": {
      "en": ["英文", "英语", "en"],
      "zh": ["中文", "简中", "zh"],
      "pt": ["葡语", "葡萄牙语", "pt"],
      "es": ["西语", "西班牙语", "es"],
      "ar": ["阿语", "阿拉伯语", "ar"],
      "hi": ["印地语", "hi"],
      "vi": ["越南语", "vi"],
      "th": ["泰语", "th"],
      "ru": ["俄语", "ru"],
      "tr": ["土耳其语", "tr"],
      "in": ["印尼语", "印尼", "id"],
      "id": ["印度语", "in"]
    }
  }
}

语言列映射

如果表头名称和多语言文件名不一致，可以在 hltools.config.json 中配置 localeHeaderMap：

• key：输出语言文件名（不包含后缀），例如 en、zh、pt
• value：该语言可匹配的表头名数组
• 优先级：localeHeaderMap 高于 “表头名直接等于语言文件名” 的默认规则
• 关系：一个文件名可以对应多个表头名，会按数组顺序取第一个命中的表头

这项映射同时会影响：

• 输出语言列识别
• sourceLocale 对应源语言列识别
• 旧 key 复用逻辑

命令行修改映射

设置单个语言映射

hltools config set --set-locale-alias "en=英文,英语,en"
hltools config set --set-locale-alias "pt=葡语,葡萄牙语,pt"

删除单个语言映射

hltools config set --remove-locale-alias en

整体覆盖 localeHeaderMap

hltools config set --locale-header-map "{\"en\":[\"英文\",\"英语\",\"en\"],\"zh\":[\"中文\",\"简中\",\"zh\"]}"

可选参数说明

excel-to-i18n 参数顺序

• x <input>：excel-to-i18n --input <pathOrGlob> 的短命令
• -i, --input <pathOrGlob>：Excel 文件路径/Glob，必填
• -n, --namespace <name>：命名空间，必填
• -o, --out-dir <dir>：输出目录；未传时先读取配置 excelToI18n.outDir，再从当前目录向上查找 src/language
• --range <range>：读取范围
• -s, --sheet <sheetName>：指定 sheet 名
• --key-column <columnName>：key 列名，默认 key
• --source-locale <locale>：源语言列，默认 en
• --locale-columns <items>：指定语言列，逗号分隔，如 zh,en,hi,pt
• --sheet-name-as-namespace：使用 sheet 名作为命名空间，默认 false
• --flat：输出扁平对象，默认 false
• --ignore-empty：忽略空翻译，默认 false
• --indent <size>：缩进空格数，默认 2
• --format <type>：输出格式，支持 json | module | ts-module | js-module，默认 module

google-sheet-to-i18n 参数顺序

• gs <sheetId>：google-sheet-to-i18n --sheet-id <idOrUrl> 的短命令
• --sheet-id <idOrUrl>：Google Sheet ID/完整链接，必填
• -n, --namespace <name>：命名空间，必填
• --range <range>：读取范围
• -o, --out-dir <dir>：输出目录；未传时先读取配置 excelToI18n.outDir，再从当前目录向上查找 src/language
• -s, --sheet <sheetName>：指定 sheet 名；不传时优先尝试从链接中的 gid 自动识别
• --key-column <columnName>：key 列名，默认 key
• --source-locale <locale>：源语言列，默认 en
• --locale-columns <items>：指定语言列，逗号分隔，如 zh,en,hi,pt
• --sheet-name-as-namespace：使用 sheet 名作为命名空间，默认 false
• --flat：输出扁平对象，默认 false
• --ignore-empty：忽略空翻译，默认 false
• --indent <size>：缩进空格数，默认 2
• --format <type>：输出格式，支持 json | module | ts-module | js-module，默认 module
• --credentials <path>：Google 服务账号 JSON 凭证路径；未传时可回退到配置默认值

Excel / Google 表格格式

推荐使用如下表头：

| key | zh | en | hi | pt | note | | ------- | ---- | ------- | ----------- | --------- | -------- | | confirm | 确认 | Confirm | पुष्टि करें | Confirmar | 按钮文案 | | cancel | 取消 | Cancel | रद्द करें | Cancelar | 按钮文案 |

说明：

• key 列为国际化 key，可为空
• 其他列会被视为 locale，例如 zh、en、hi、pt
• note、备注、description 等说明列会被自动忽略
• 若 key 为空：
  • 优先用 sourceLocale 文案匹配已有模块中的旧 key
  • 匹配不到时再自动生成新 key
• 必须传入 -n / --namespace
• 当输出为 module 时：
  • 会优先按目标目录里已存在的语言文件自动识别 .ts 或 .js
  • .ts 按 export default {} 读写
  • .js 按 module.exports = {} 读写
  • 不会自动新建不存在的语言文件
• 当输出为 ts-module 时：
  • 强制按 xx.ts 处理
• 当输出为 js-module 时：
  • 强制按 xx.js 处理

输出示例

命令执行后会输出处理结果，例如：

转换完成：sheet 1 个，key 51 条，复用旧 key 49 条，自动生成 key 2 条，locale 4 个
已输出：D:\project\demo\src\language\en.ts
已输出：D:\project\demo\src\language\hi.ts
已输出：D:\project\demo\src\language\pt.ts
已跳过：zh（目标语言文件不存在，或当前输出格式无法自动匹配）
[zh] 未写入｜总条数 51｜复用 49｜新增 2
[en] 已写入｜总条数 51｜复用 49｜新增 2
[hi] 已写入｜总条数 51｜复用 49｜新增 2
[pt] 已写入｜总条数 51｜复用 49｜新增 2

Google Sheets 额外说明

如果你要读取 Google 在线表格，请先准备：

• 已开启 Google Sheets API 的 Google Cloud 项目
• 服务账号 JSON 凭证文件
• 已将目标 Google Sheet 分享给服务账号 client_email

说明：

• --sheet-id 可以直接传 Google Sheets 完整链接，也可以只传 Spreadsheet ID
• 如果不传 --sheet，会优先尝试用链接里的 gid 自动匹配对应 sheet
• --range 用来限制读取区域，适合跳过在线文档里的无关文案，例如 A1:G100
• 如果既不传 --sheet，链接里也没有 gid，则默认读取所有 sheet

其他文档

• 开发说明：docs/DEVELOPMENT.md
• 发布说明：docs/PUBLISH.md