配置与设置

本页介绍全局配置、项目配置和 IDE 代码片段生成。

全局配置

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

基本命令

hitf global-config

全局配置文件位于用户目录下：

text

~/.hitf/config.json

配置结构

json

{
  "translationSetting": {
    "translationService": "tencent",
    "servicePriority": ["tencent", "baidu", "openai", "google"],
    "services": {
      "tencent": {
        "secretId": "your_secret_id",
        "secretKey": "your_secret_key",
        "region": "ap-guangzhou"
      },
      "baidu": {
        "appId": "your_app_id",
        "secretKey": "your_secret_key"
      },
      "openai": {
        "apiKey": "your_api_key",
        "baseUrl": "https://api.openai.com",
        "model": "gpt-3.5-turbo"
      },
      "google": {
        "apiKey": "your_api_key"
      }
    }
  }
}

优先级

全局配置会作为默认值，项目配置 .hitf/setting.json 会覆盖全局配置。

项目配置

hitf setting 用于生成或打开项目级配置文件。

基本命令

hitf setting

配置文件位于项目根目录：

text

.hitf/setting.json

配置结构

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": "" }
    }
  }
}

配置字段说明

字段	默认值	说明
`locales`	`["zh-CN", "en-US"]`	`locales[0]` 为源语言，其余为目标语言
`outDir`	`.hitf/lang`	语言包和翻译副本输出目录，支持字符串或对象格式
`fallbackToKey`	`true`	翻译失败时是否回退到原文 key
`replaceOriginalFile`	`false`	是否直接覆盖源文件
`translationSetting.translationService`	`tencent`	当前使用的翻译服务：`baidu`、`tencent`、`openai` 或 `google`
`translationSetting.servicePriority`	`["tencent", "baidu", "openai", "google"]`	故障转移优先级
`translationSetting.services.openai.apiKey`	-	OpenAI API 密钥
`translationSetting.services.openai.baseUrl`	`https://api.openai.com`	自定义 API 端点
`translationSetting.services.openai.model`	`gpt-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.region`	`ap-guangzhou`	区域
`i18nCallTemplate`	`$t`	替换源码时使用的 i18n 调用，支持字符串或数组格式
`i18nImport`	`""`	可选导入语句；支持字符串或数组格式；适用于 Vue/JS/TS/JSX/TSX 文件
`extensions`	`[".vue", ".js", ".ts", ".jsx", ".tsx", ".json"]`	自定义扫描扩展名；空数组表示全部支持类型
`capitalizeTranslations`	`false`	是否把含拉丁字符的翻译结果首字母大写
`capitalizeMaxWords`	`0`	全词大写（Title Case）阈值，仅当 `capitalizeTranslations` 为 `true` 时生效
`pruneUnusedKeys`	`false`	是否移除当前命名空间未被源码引用的旧 key
`keyStrategy.maxLength`	`40`	自动生成 key 的最大长度
`keyStrategy.collision`	`number`	key 冲突策略：`number` 或 `hash`
`keyStrategy.hashLength`	`6`	hash 冲突策略的短 hash 长度

语言方向

源语言由 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。

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
  }
}

多项目 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：

# 默认使用 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

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

IDE 代码片段

hitf codesnippets 生成 IDE 代码片段，用于快速插入翻译忽略注释。

基本命令

hitf codesnippets           # 自动检测 IDE（.vscode / .idea / .cursor）
hitf codesnippets vscode    # 生成 VS Code 代码片段
hitf codesnippets webstorm  # 生成 WebStorm 模板
hitf codesnippets cursor    # 生成 Cursor 代码片段
hitf codesnippets sublime   # 生成 Sublime Text 片段

自动检测

命令会自动检测当前工作区的 IDE 类型：

目录	检测结果
`.vscode/`	VS Code
`.idea/`	WebStorm / IntelliJ
`.cursor/`	Cursor
无匹配	默认 VS Code

生成的代码片段

前缀	功能
`@hitf-i18n-ignore-next`	忽略下一段翻译
`@hitf-i18n-ignore-start`	忽略范围开始
`@hitf-i18n-ignore-end`	忽略范围结束
`@hitf-i18n-ignore-file`	忽略文件翻译
`@hitf-i18n-ignore:prop:<attrName>`	忽略 Vue 模板指定静态属性（如 `<!-- @hitf-i18n-ignore:prop:placeholder -->`，可由 `-i` 交互取消选中时自动插入）

使用方式

VS Code / Cursor

运行 hitf codesnippets vscode
在代码中输入 @hitf-i18n-ignore-next
按 Tab 展开

WebStorm

运行 hitf codesnippets webstorm
在 Settings > Editor > Live Templates 中查看

Sublime Text

运行 hitf codesnippets sublime
在代码中输入 @hitf-i18n-ignore-next
按 Tab 展开

代码片段内容

每个代码片段包含中文描述，例如：

json

{
  "忽略下一段翻译": {
    "prefix": "@hitf-i18n-ignore-next",
    "body": ["// @hitf-i18n-ignore-next", "$1"],
    "description": "忽略下一段翻译 (Ignore next extractable segment)"
  }
}

服务申请指南

hitf 支持多种翻译服务，各服务的官方申请入口：

服务	申请地址
腾讯翻译	去申请
百度翻译	去申请
OpenAI	去申请
Google Translate	去申请

配置示例

json

{
  "translationSetting": {
    "translationService": "tencent",
    "services": {
      "tencent": {
        "secretId": "YOUR_SECRET_ID",
        "secretKey": "YOUR_SECRET_KEY",
        "region": "ap-guangzhou"
      },
      "baidu": {
        "appId": "YOUR_APP_ID",
        "secretKey": "YOUR_SECRET_KEY"
      },
      "openai": {
        "apiKey": "YOUR_API_KEY",
        "baseUrl": "https://api.openai.com",
        "model": "gpt-4o-mini"
      },
      "google": {
        "apiKey": "YOUR_API_KEY"
      }
    }
  }
}

配置与设置 ​

全局配置 ​

基本命令 ​

配置结构 ​

优先级 ​

项目配置 ​

基本命令 ​

配置结构 ​

配置字段说明 ​

语言方向 ​

i18nCallTemplate 配置 ​

i18nImport 配置 ​

Key 策略 ​

未使用 key 清理 ​

多项目 outDir 配置 ​

输出目录 ​

IDE 代码片段 ​

基本命令 ​

自动检测 ​

生成的代码片段 ​

使用方式 ​

VS Code / Cursor ​

WebStorm ​

Sublime Text ​

代码片段内容 ​

服务申请指南 ​

配置示例 ​

配置与设置

全局配置

基本命令

配置结构

优先级

项目配置

基本命令

配置结构

配置字段说明

语言方向

i18nCallTemplate 配置

i18nImport 配置

Key 策略

未使用 key 清理

多项目 outDir 配置

输出目录

IDE 代码片段

基本命令

自动检测

生成的代码片段

使用方式

VS Code / Cursor

WebStorm

Sublime Text

代码片段内容

服务申请指南

配置示例