@ansstory/hitf

hitf

English | 简体中文

CLI 国际化工具链，支持从 Vue/React/uni-app 源码中自动提取中文文本，通过百度/腾讯/OpenAI/Google 翻译 API 生成多语言文件，并提供项目脚手架、翻译缓存管理、IDE 代码片段生成等功能。

安装

npm install -g @ansstory/hitf

命令一览

通用参数

翻译工作流

翻译单个文件

hitf tf src/views/Home.vue

• 自动提取 <template>、<script> 中的中文文本
• 调用翻译 API 生成目标语言
• 在 .hitf/lang/ 下生成语言包 JSON
• 将源码中的中文替换为 $t('key') 调用

翻译整个文件夹

hitf tfo src --exclude "**/*.test.js"

递归处理目录下所有 .vue、.js、.ts、.jsx、.tsx、.json 文件。

预览模式（-d / --dry-run）

仅预览翻译计划，不调用翻译、不写入任何文件。

单文件 tf 逐项列出提取的文本及其源码位置（文件:行:列），并附被跳过（未提取）的字符串及原因：

hitf tf src/App.vue -d

  合适 → src/App.vue:2:21
  测试 → src/App.vue:3:21

文件夹 tfo 以只读树形界面展示「目录 > 文件 > 文本」三级翻译计划（叶子带 [译] 标记，默认全部翻译）：

hitf tfo src -d

树形浏览按键：↑/↓ 移动 · ←/→ 展开/折叠 · 输入字符搜索 · Enter 结束。结束后输出将翻译的总条数及各处被跳过的字符串明细。

非 TTY 环境（脚本 / CI / 管道）下 tfo -d 不弹交互界面，自动回退为静态树形打印，预览结果同样完整输出。

交互式选择（-i / --interactive）

以树形多选框选择需要翻译的文本，只有选中的项会参与翻译并生成 key；未选中的项就地标记为忽略，下次提取自动跳过：

hitf tf src/App.vue -i
hitf tfo src -i

按键操作：

确认后仅翻译选中的项，未选中的项会提示「已跳过 N 个文本（将添加忽略注释）」，并在源码中自动插入忽略注释：

• JS / TS：/* @hitf-i18n-ignore-start */ … /* @hitf-i18n-ignore-end */
• Vue 模板文本：<!-- @hitf-i18n-ignore-start --> … <!-- @hitf-i18n-ignore-end -->
• JSX：{/* @hitf-i18n-ignore-start */} … {/* @hitf-i18n-ignore-end */}
• Vue 模板静态属性：<!-- @hitf-i18n-ignore:prop:<attrName> -->（置于目标标签正上方）
• JSON 文件：不插入注释，而是记录到 .hitf/i18n-ignore.json，后续提取自动过滤

交互中断（如 Ctrl+C）会中止翻译，不产生任何写入。

检查一致性

hitf tcheck src

检查源码中的 i18n 引用与语言包文件的一致性，输出缺失/未使用/不一致的 key 及位置。

Translation check summary
  missing: 2
  missing hello
    src/App.vue:2:11
  missing welcome
    src/App.vue:3:9

回滚操作

hitf rollback -l          # 查看可用备份
hitf rollback              # 回滚最近一次
hitf rollback -n xxx       # 回滚指定备份
hitf rollback -k 5         # 仅保留最近 5 个备份

翻译缓存管理

导出源语言文本

hitf export-source src/views      # 从源码提取
hitf export-translated            # 从已翻译语言包读取

两个命令共享同一输出文件 source-texts-<locale>.xlsx，增量合并去重。根据 locales 配置自动填充多列，缺失翻译的列会尝试调用翻译 API 补全（API 未配置则留空）。输出格式兼容 cache-import。

导入公司翻译表

hitf cache-import translations.xlsx -s zh-CN

支持 .xlsx 格式，导入后本地缓存可直接复用，无需重复调用 API。

应用缓存到语言包

hitf cache-apply

将缓存中的最新译文写回 .hitf/lang/ 下的语言包 JSON 文件。

配置与设置

全局配置

hitf global-config

生成全局配置文件，用于设置默认翻译服务、API 密钥等。

项目配置

hitf setting

在项目根目录生成 .hitf/setting.json：

{
  "$schema": "https://www.schemastore.org/hias-hitf.json",
  "translationSetting": {
    "locales": ["zh-CN", "en-US"],
    "outDir": ".hitf/lang",
    "i18nCallTemplate": "$t",
    "i18nImport": "import i18n from '@/i18n'",
    "translationService": "tencent",
    "servicePriority": ["tencent", "baidu", "openai", "google"],
    "services": {
      "tencent": { "secretId": "", "secretKey": "", "region": "ap-guangzhou" },
      "baidu": { "appId": "", "secretKey": "" },
      "openai": { "apiKey": "", "baseUrl": "https://api.openai.com", "model": "gpt-3.5-turbo" },
      "google": { "apiKey": "" }
    }
  }
}

配置项说明

翻译服务配置

腾讯翻译

申请步骤：

1. 打开 腾讯云控制台，登录你的腾讯云账号
2. 点击【新建密钥】，创建一对 SecretId 和 SecretKey
3. 复制 SecretId 和 SecretKey 填入配置文件

{
  "tencent": {
    "secretId": "YOUR_SECRET_ID",
    "secretKey": "YOUR_SECRET_KEY",
    "region": "ap-guangzhou"
  }
}

价格： 每月前 500 万字符免费，超出部分 58 元/百万字符。

百度翻译

申请步骤：

1. 打开 百度翻译开放平台，登录百度账号
2. 点击【管理控制台】，注册成为开发者（选择「个人开发者」）
3. 开通「通用翻译服务」，选择标准版
4. 在控制台底部获取 APP ID 和密钥

{
  "baidu": {
    "appId": "YOUR_APP_ID",
    "secretKey": "YOUR_SECRET_KEY"
  }
}

价格： 标准版每月 5 万免费字符；完成个人认证后可切换高级版，每月 100 万免费字符。超出部分 49 元/百万字符。

OpenAI

申请步骤：

1. 访问 OpenAI 官网 注册账号
2. 打开 API Keys 页面
3. 点击【Create new secret key】创建密钥
4. 复制密钥填入配置文件

注意：OpenAI 无法从国内直接访问，需要配置网络环境。无免费额度，需绑定国外信用卡使用。

{
  "openai": {
    "apiKey": "YOUR_API_KEY",
    "baseUrl": "https://api.openai.com",
    "model": "gpt-3.5-turbo"
  }
}

推荐模型与价格：

Google Translate

申请步骤：

1. 打开 Google Cloud Console
2. 创建一个新项目或选择已有项目
3. 启用 Cloud Translation API
4. 创建 API Key 并复制

{
  "google": {
    "apiKey": "YOUR_API_KEY"
  }
}

价格： 每月前 50 万字符免费，超出部分 $20/百万字符。

IDE 代码片段

hitf codesnippets        # 自动检测 IDE
hitf codesnippets vscode # 手动指定

支持 VS Code、WebStorm、Cursor、Sublime Text。

忽略注释

在源码中添加注释可跳过特定文本的提取；使用 -i 交互取消选中时，也会自动插入这些注释：

<!-- @hitf-i18n-ignore-next -->
<div>{{ brandName }}</div>

<!-- @hitf-i18n-ignore-start -->
<div>
  <span>不翻译</span>
  <span>也不翻译</span>
</div>
<!-- @hitf-i18n-ignore-end -->

// @hitf-i18n-ignore-file
const msg = '整个文件跳过翻译'

指令说明：

其中 start / end / prop 指令可由 -i 交互取消选中时自动插入；JSON 文件不支持注释，取消选中项会记录到 .hitf/i18n-ignore.json，后续提取自动过滤。

CLI 语言切换

hitf lang -l         # 查看当前语言
hitf lang zh-CN      # 切换为中文
hitf lang en         # 切换为英文

License

MIT