翻译缓存管理

本页介绍翻译缓存的完整工作流：导出源语言文本、导入公司翻译表、应用缓存到语言包。

导出源语言文本

export-source（短命令 tes）从源码提取唯一源语言文本并导出为 XLSX。

命令

hitf export-source src\views

执行流程

1. 递归扫描指定路径下所有支持的文件（.vue、.js、.ts、.jsx、.tsx、.json）
2. 提取所有可翻译文本并去重
3. 根据 locales 配置填充多列：
   • 源语言列：直接使用提取的文本
   • 目标语言列：尝试调用翻译 API 补全
   • API 未配置时对应列留空，不报错
4. 输出到 .hitf/source-texts-<locale>.xlsx

选项

选项	简写	说明
-s, --source <locale>	-s	源语言代码，默认使用配置中的源语言
-o, --out <file>	-o	输出文件路径，默认 .hitf/source-texts-<locale>.xlsx

导出已翻译语言包

export-translated（短命令 etr）从已翻译的语言包 JSON 读取文本并导出为 XLSX。

命令

hitf export-translated

不指定文件时，自动扫描 outDir 下的语言包：

• outDir 为字符串：直接读取该路径下的 namespace 子目录
• outDir 为对象：弹出项目多选（如 main/web），合并选中项目的数据

执行流程

1. 读取所有 locale JSON（如 zh-CN.json、en-US.json、ja-JP.json）
2. 构建 源文本 → { zh-CN: '...', en-US: '...', ja-JP: '...' } 映射
3. 缺失的目标语言翻译 → 调用翻译 API 补全
4. API 未配置 → 对应列留空
5. 增量合并已有 xlsx 内容

选项

选项	简写	说明
-s, --source <locale>	-s	源语言代码
-o, --out <file>	-o	输出文件路径，默认 .hitf/source-texts-<locale>.xlsx

导入翻译表

cache-import（短命令 tci）用于将人工编辑后的翻译表导入 .hitf/.translation-cache.json，后续翻译时直接复用。

典型流程：先用 export-source / export-translated 导出 XLSX，人工补充或校对译文后，再通过本命令导入缓存。

命令

hitf cache-import .hitf/source-texts-zh-CN.xlsx

也可以使用短命令：

hitf tci .hitf/source-texts-zh-CN.xlsx

推荐格式

.xlsx 格式，第一行是语言代码，后续每行是一条文案。

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

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

支持格式

格式	说明
.xlsx	推荐格式
.xlsm	可兼容导入

多语言写入方式

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

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

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

常用选项

指定源语言：

hitf tci .hitf/source-texts-zh-CN.xlsx -s zh-CN

指定工作表：

hitf tci .hitf/source-texts-zh-CN.xlsx -S Sheet1

覆盖已有缓存：

hitf tci .hitf/source-texts-zh-CN.xlsx -o

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

使用场景

1. export-source / export-translated 导出后，人工补充译文再导入。
2. 公司已有多语言资产，直接导入复用。
3. 日语、韩语等需要人工翻译保证表达自然。
4. 多个项目共享同一套业务术语。

应用缓存到语言包

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

命令

hitf tca

工作逻辑

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

使用场景

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. 重复执行是幂等的，语言包已是最新时不做任何写入

闭环工作流

四个命令形成完整闭环：

# 1. 从源码提取文本
hitf export-source src\views

# 2. 从已翻译语言包补充（可选，两次命令共享同一文件，增量合并）
hitf export-translated

# 3. 导入到翻译缓存
hitf tci .hitf/source-texts-zh-CN.xlsx

# 4. 缓存回写到语言包
hitf tca