缓存导入

cache-import 用于把公司已有的翻译表导入 .hitf/.translation-cache.json，后续翻译时直接复用。

命令

hitf cache-import .\.hitf\company.xlsx

也可以使用短命令：

hitf tci .\.hitf\company.xlsx

推荐格式

最推荐使用 .xlsx，第一行是语言代码，后续每行是一条文案。

zh-CN	en-US	ja-JP
登录	Login	ログイン
正常状态	Normal Status	正常状態
请输入用户名	Please Enter Username	ユーザー名を入力してください

这种格式对产品、运营、翻译同事都比较友好，也方便后续继续补充语言列。

支持格式

格式	说明
.xlsx	推荐格式，适合公司内部维护
.xlsm / .xls	可兼容导入
.tsv / .txt	使用 Tab 分隔的纯文本表格

多语言写入方式

导入工具会把每个目标语言写入翻译缓存：

{
  "zh-CN|en-US": {
    "登录": "Login"
  },
  "zh-CN|ja-JP": {
    "登录": "ログイン"
  }
}

后续从 zh-CN 翻译到 en-US 或 ja-JP 时，会优先命中缓存。

常用选项

指定源语言：

hitf tci .\.hitf\company.xlsx -s zh-CN

指定工作表：

hitf tci .\.hitf\company.xlsx -S Sheet1

覆盖已有缓存：

hitf tci .\.hitf\company.xlsx -o

选项	简写	说明
-s, --source <locale>	-s	源语言列，默认使用 zh-CN
-S, --sheet <name>	-S	XLSX 工作表名称，默认使用第一个工作表
-o, --overwrite	-o	当译文不同时覆盖已有的缓存翻译

什么时候使用

建议在批量翻译前先导入公司词库，尤其是以下场景：

1. 登录、菜单、按钮、状态等短词需要统一大小写。
2. 公司已有多语言资产，不希望再次调用机器翻译。
3. 日语、韩语等语言需要人工翻译保证表达自然。
4. 多个项目共享同一套业务术语。

回写语言包（cache-apply）

cache-apply（短命令 tca）用于将翻译结果写入 outDir 下的语言包 JSON。

工作逻辑：

1. 以源语言 JSON（key → 原文）为对照表，逐 key 查翻译缓存
2. 缓存命中 → 直接使用缓存译文
3. 缓存未命中 → 自动调用翻译 API 翻译，结果写入缓存
4. JSON 结构、其余键值原样保留，不会触碰源文件

hitf tca

使用场景：

1. replaceOriginalFile: true 模式：源文件已被 $t() 调用替换，重跑 tf / tfo 已提取不到中文原文，cache-apply 可从语言包重新翻译
2. 翻译服务商切换：换了翻译 API（如从百度切到 OpenAI），需要重新翻译未缓存的条目
3. 网络恢复后补翻：之前因网络问题翻译失败，现在网络恢复，重新翻译失败的条目
4. 导入词库后刷新：通过 cache-import 导入新词库后，刷新语言包

常用用法：

# 只处理指定命名空间（outDir 下的子目录名）
hitf tca views

# outDir 为对象格式时指定项目 key
hitf tca -p admin

执行流程：

1. 读取源语言 JSON（如 zh-CN.json）作为 key → 原文对照表
2. 逐 key 查翻译缓存：
   • 命中 → 使用缓存译文
   • 未命中 → 调用翻译 API 翻译，结果写入缓存
3. 更新目标语言 JSON（如 en-US.json）
4. 重复执行是幂等的，语言包已是最新时不做任何写入