hitf

简体中文

English

简体中文

English

Appearance

配置说明 ​

hitf 使用项目级 .hitf/setting.json 管理翻译行为。

创建配置 ​

sh
hitf setting

配置文件通常位于当前业务项目：

text
.hitf/setting.json

翻译服务配置 ​

hitf 支持多种翻译服务，包括腾讯云、百度、OpenAI (GPT) 和谷歌翻译。

配置结构 ​

json
{
  "translationSetting": {
    "translationService": "tencent",
    "servicePriority": ["tencent", "baidu", "openai", "google"],
    "services": {
      "openai": {
        "apiKey": "sk-xxxxxxxx",
        "baseUrl": "https://api.openai.com",
        "model": "gpt-3.5-turbo"
      },
      "google": {
        "apiKey": "your-google-api-key"
      },
      "baidu": {
        "appId": "your-app-id",
        "secretKey": "your-secret-key"
      },
      "tencent": {
        "secretId": "your-secret-id",
        "secretKey": "your-secret-key",
        "region": "ap-guangzhou"
      }
    }
  }
}

配置字段说明 ​

字段说明默认值
translationService当前使用的翻译服务tencent
servicePriority故障转移优先级["tencent", "baidu", "openai", "google"]
services.openai.apiKeyOpenAI API 密钥-
services.openai.baseUrl自定义 API 端点https://api.openai.com
services.openai.model模型名称gpt-3.5-turbo
services.google.apiKeyGoogle Cloud Translation API 密钥-
services.baidu.appId百度翻译应用 ID-
services.baidu.secretKey百度翻译密钥-
services.tencent.secretId腾讯云密钥 ID-
services.tencent.secretKey腾讯云密钥-
services.tencent.region区域ap-guangzhou

没有密钥时，工具仍可提取中文并生成语言包，只是目标语言可能暂时回退为中文原文。

语言方向 ​

源语言由 locales 数组的第一项决定，其余为目标语言。

json
{
  "translationSetting": {
    "locales": ["zh-CN", "en-US", "ja-JP"]
  }
}

如果源码是英文，希望生成中文和日文：

json
{
  "translationSetting": {
    "locales": ["en-US", "zh-CN", "ja-JP"]
  }
}

此时源语言为 en-US，目标语言自动变成 zh-CN 和 ja-JP。

完整配置示例： ​

json
{
  "translationSetting": {
    "locales": ["zh-CN", "en-US"],
    "outDir": ".hitf/lang",
    "fallbackToKey": true,
    "replaceOriginalFile": false,
    "translationService": "tencent",
    "servicePriority": ["tencent", "baidu", "openai", "google"],
    "services": {
      "openai": {
        "apiKey": "",
        "baseUrl": "https://api.openai.com",
        "model": "gpt-3.5-turbo"
      },
      "google": {
        "apiKey": ""
      },
      "baidu": {
        "appId": "",
        "secretKey": ""
      },
      "tencent": {
        "secretId": "",
        "secretKey": "",
        "region": "ap-guangzhou"
      }
    },
    "i18nCallTemplate": "$t",
    "i18nImport": "",
    "extensions": [".vue", ".js", ".ts", ".jsx", ".tsx", ".json"],
    "capitalizeTranslations": false,
    "capitalizeMaxWords": 0,
    "pruneUnusedKeys": false,
    "keyStrategy": {
      "maxLength": 40,
      "collision": "number",
      "hashLength": 6
    }
  }
}

字段说明 ​

字段默认值说明
locales["zh-CN", "en-US"]locales[0] 为源语言，其余为目标语言
outDir.hitf/lang语言包和翻译副本输出目录，支持字符串或对象格式
fallbackToKeytrue翻译失败时是否回退到原文 key
replaceOriginalFilefalse是否直接覆盖源文件
translationSetting.translationServicetencent当前使用的翻译服务：baidu、tencent、openai 或 google
translationSetting.servicePriority["tencent", "baidu", "openai", "google"]故障转移优先级
translationSetting.services.openai.apiKey-OpenAI API 密钥
translationSetting.services.openai.baseUrlhttps://api.openai.com自定义 API 端点
translationSetting.services.openai.modelgpt-3.5-turbo模型名称
translationSetting.services.google.apiKey-Google Cloud Translation API 密钥
translationSetting.services.baidu.appId-百度翻译应用 ID
translationSetting.services.baidu.secretKey-百度翻译密钥
translationSetting.services.tencent.secretId-腾讯云密钥 ID
translationSetting.services.tencent.secretKey-腾讯云密钥
translationSetting.services.tencent.regionap-guangzhou区域
i18nCallTemplate$t替换源码时使用的 i18n 调用，支持字符串或数组格式
i18nImport""可选导入语句；支持字符串或数组格式；适用于 Vue/JS/TS/JSX/TSX 文件
extensions[".vue", ".js", ".ts", ".jsx", ".tsx", ".json"]自定义扫描扩展名；空数组表示全部支持类型
capitalizeTranslationsfalse是否把含拉丁字符的翻译结果首字母大写
capitalizeMaxWords0全词大写（Title Case）阈值，仅当 capitalizeTranslations 为 true 时生效。0 表示关闭（仅首词大写）；>0 且英语译文单词数 ≤ 该值时，每个单词首字母大写（仅限英语目标语言）
pruneUnusedKeysfalse是否移除当前命名空间未被源码引用的旧 key
keyStrategy.maxLength40自动生成 key 的最大长度
keyStrategy.collisionnumberkey 冲突策略：number 或 hash
keyStrategy.hashLength6hash 冲突策略的短 hash 长度

i18nCallTemplate 配置 ​

i18nCallTemplate 支持字符串或数组格式，用于指定替换源码时使用的 i18n 调用函数。

字符串格式：

json
{
  "i18nCallTemplate": "$t"
}

数组格式（支持多种调用形式）：

json
{
  "i18nCallTemplate": ["$t", "t", "i18n"]
}

支持的调用形式：

格式示例
简单函数名$t、t、i18n
带括号模板i18n()、useI18n().t
数组["$t", "t", "i18n"]

系统会自动识别代码中已存在的 i18n 调用，避免重复包裹。

i18nImport 配置 ​

i18nImport 支持字符串或数组格式，用于在翻译时自动注入导入语句。

字符串格式：

json
{
  "i18nImport": "import { useI18n } from 'vue-i18n'"
}

数组格式（多行导入）：

json
{
  "i18nImport": [
    "import { useI18n } from 'vue-i18n'",
    "const { t } = useI18n()"
  ]
}

支持的文件类型：

文件类型注入位置
.vue<script> 标签后
.js / .ts最后一个 import 语句后 / 文件顶部
.jsx / .tsx最后一个 import 语句后 / 文件顶部
.json不注入

智能合并特性：

  • 自动检测已存在的导入语句，避免重复注入
  • 支持部分导入场景（如只有 import 没有初始化代码）
  • 空数组或空字符串不会注入任何内容

Key 策略 ​

默认使用翻译后的英文生成 snake_case key，并在冲突时追加序号：

json
{
  "translationSetting": {
    "keyStrategy": {
      "maxLength": 40,
      "collision": "number",
      "hashLength": 6
    }
  }
}

如果你更希望多次运行时 key 后缀稳定，可以改为 hash：

json
{
  "translationSetting": {
    "keyStrategy": {
      "collision": "hash"
    }
  }
}

未使用 key 清理 ​

默认会保留语言包中已有 key，避免删除人工维护的历史翻译。确认要清理当前命名空间未引用 key 时，再开启：

json
{
  "translationSetting": {
    "pruneUnusedKeys": true
  }
}

翻译缓存 ​

缓存文件位于：

text
.hitf/.translation-cache.json

缓存 key 使用语言方向：

json
{
  "zh-CN|en-US": {
    "登录": "Login"
  }
}

推荐通过 hitf tci 导入，而不是手写缓存文件。

多项目 outDir 配置 ​

outDir 支持字符串或对象格式。对象格式适用于 monorepo 多项目场景：

字符串格式（默认）：

json
{
  "translationSetting": {
    "outDir": ".hitf/lang"
  }
}

对象格式（monorepo）：

json
{
  "translationSetting": {
    "outDir": {
      "main": "apps/main/src/locale/module",
      "web": "apps/web/src/locale/module"
    }
  }
}

使用 -p, --project 参数指定项目。不指定时默认使用对象中第一个 key：

sh
# 默认使用 main（对象中第一个 key）
hitf tf apps/main/src/views/index.vue home

# 指定项目
hitf tf apps/main/src/views/index.vue -p main
hitf tf apps/web/src/views/index.vue home -p web

# tfo 同样支持
hitf tfo apps/main/src/views views -p main

输出目录 ​

翻译结果通常写入 locale module 目录，例如：

text
src\locale\module\demo
.hitf\locale\module\demo

实际路径以项目配置为准。

Released under the MIT License.

Copyright © AnsStory