Configuration

hitf uses project-level .hitf/setting.json to manage translation behavior.

Create Configuration

hitf setting

The config file is usually in your business project:

text

.hitf/setting.json

Translation Service Configuration

hitf supports multiple translation services, including Tencent Cloud, Baidu, OpenAI (GPT), and Google Translate.

Configuration Structure

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

Configuration Fields

Field	Description	Default
`translationService`	Current translation service	`tencent`
`servicePriority`	Fallback priority	`["tencent", "baidu", "openai", "google"]`
`services.openai.apiKey`	OpenAI API key	-
`services.openai.baseUrl`	Custom API endpoint	`https://api.openai.com`
`services.openai.model`	Model name	`gpt-3.5-turbo`
`services.google.apiKey`	Google Cloud Translation API key	-
`services.baidu.appId`	Baidu translation app ID	-
`services.baidu.secretKey`	Baidu translation secret key	-
`services.tencent.secretId`	Tencent Cloud secret ID	-
`services.tencent.secretKey`	Tencent Cloud secret key	-
`services.tencent.region`	Region	`ap-guangzhou`

Without credentials, the tool can still extract Chinese and generate locale files, but target languages may temporarily fall back to Chinese source text.

Language Direction

Source language is determined by the first item in the locales array; the rest are target languages.

json

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

If your source code is English and you want to generate Chinese and Japanese:

json

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

Now the source language is en-US, and target languages automatically become zh-CN and ja-JP.

Full Configuration Example

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

Field Description

Field	Default	Description
`locales`	`["zh-CN", "en-US"]`	`locales[0]` is source language, rest are target languages
`outDir`	`.hitf/lang`	Output directory for locale files and translated copies (string or object format)
`fallbackToKey`	`true`	Whether to fall back to source key when translation fails
`replaceOriginalFile`	`false`	Whether to overwrite source files directly
`translationSetting.translationService`	`tencent`	Current translation service: `baidu`, `tencent`, `openai`, or `google`
`translationSetting.servicePriority`	`["tencent", "baidu", "openai", "google"]`	Fallback priority
`translationSetting.services.openai.apiKey`	-	OpenAI API key
`translationSetting.services.openai.baseUrl`	`https://api.openai.com`	Custom API endpoint
`translationSetting.services.openai.model`	`gpt-3.5-turbo`	Model name
`translationSetting.services.google.apiKey`	-	Google Cloud Translation API key
`translationSetting.services.baidu.appId`	-	Baidu translation app ID
`translationSetting.services.baidu.secretKey`	-	Baidu translation secret key
`translationSetting.services.tencent.secretId`	-	Tencent Cloud secret ID
`translationSetting.services.tencent.secretKey`	-	Tencent Cloud secret key
`translationSetting.services.tencent.region`	`ap-guangzhou`	Region
`i18nCallTemplate`	`$t`	i18n call used when replacing source code, supports string or array format
`i18nImport`	`""`	Optional import statement; supports string or array format; works with Vue/JS/TS/JSX/TSX files
`extensions`	`[".vue", ".js", ".ts", ".jsx", ".tsx", ".json"]`	Custom scan extensions; empty array means all supported types
`capitalizeTranslations`	`false`	Whether to capitalize first letter of translations containing Latin characters
`capitalizeMaxWords`	`0`	Title Case threshold; only applies when `capitalizeTranslations` is `true`. `0` disables it (first word only); when `>0` and an English translation has ≤ that many words, every word is capitalized (English target locales only)
`pruneUnusedKeys`	`false`	Whether to remove old keys not referenced by current namespace
`keyStrategy.maxLength`	`40`	Maximum length for auto-generated keys
`keyStrategy.collision`	`number`	Key collision strategy: `number` or `hash`
`keyStrategy.hashLength`	`6`	Short hash length for hash collision strategy

i18nCallTemplate Configuration

i18nCallTemplate supports string or array format, used to specify the i18n call function when replacing source code.

String format:

json

{
  "i18nCallTemplate": "$t"
}

Array format (supports multiple call styles):

json

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

Supported call styles:

Format	Example
Simple function name	`$t`, `t`, `i18n`
With parentheses template	`i18n()`, `useI18n().t`
Array	`["$t", "t", "i18n"]`

The system automatically detects existing i18n calls in code to avoid duplicate wrapping.

i18nImport Configuration

i18nImport supports string or array format, used to automatically inject import statements during translation.

String format:

json

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

Array format (multi-line imports):

json

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

Supported file types:

File Type	Injection Location
`.vue`	After `<script>` tag
`.js` / `.ts`	After last import statement / file top
`.jsx` / `.tsx`	After last import statement / file top
`.json`	Not injected

Smart merge features:

Automatically detects existing import statements to avoid duplicate injection
Supports partial import scenarios (e.g., only import without initialization code)
Empty array or empty string will not inject anything

Key Strategy

Default uses translated English to generate snake_case keys, with sequence numbers appended on collision:

json

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

If you prefer stable key suffixes across multiple runs, switch to hash:

json

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

Unused Key Cleanup

By default, existing keys in locale files are preserved to avoid deleting manually maintained historical translations. Enable only when you want to clean up unreferenced keys in the current namespace:

json

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

Translation Cache

Cache file location:

text

.hitf/.translation-cache.json

Cache keys use language direction:

json

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

Recommended to import via hitf tci rather than manually editing the cache file.

Multi-Project outDir Configuration

outDir supports string or object format. Object format is useful for monorepo setups:

String format (default):

json

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

Object format (monorepo):

json

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

Use -p, --project to specify the project. Without it, the first key is used by default:

# Default uses "main" (first key in the object)
hitf tf apps/main/src/views/index.vue home

# Specify project
hitf tf apps/main/src/views/index.vue -p main
hitf tf apps/web/src/views/index.vue home -p web

# tfo also supports -p
hitf tfo apps/main/src/views views -p main

Output Directory

Translation results are typically written to the locale module directory:

text

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

Actual paths depend on your project configuration.

Configuration ​

Create Configuration ​

Translation Service Configuration ​

Configuration Structure ​

Configuration Fields ​

Language Direction ​

Full Configuration Example ​

Field Description ​

i18nCallTemplate Configuration ​

i18nImport Configuration ​

Key Strategy ​

Unused Key Cleanup ​

Translation Cache ​

Multi-Project outDir Configuration ​

Output Directory ​

Configuration

Create Configuration

Translation Service Configuration

Configuration Structure

Configuration Fields

Language Direction

Full Configuration Example

Field Description

i18nCallTemplate Configuration

i18nImport Configuration

Key Strategy

Unused Key Cleanup

Translation Cache

Multi-Project outDir Configuration

Output Directory