Configuration & Setup

This page covers global configuration, project configuration, and IDE code snippet generation.

Global Configuration

hitf global-config generates a global config file for setting default translation services, API keys, etc.

Basic Command

hitf global-config

The global config file is located in the user directory:

text

~/.hitf/config.json

Configuration Structure

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

Priority

Global configuration serves as defaults; project configuration .hitf/setting.json overrides global configuration.

Project Configuration

hitf setting generates or opens the project-level configuration file.

Basic Command

hitf setting

The configuration file is located at the project root:

text

.hitf/setting.json

Configuration Structure

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

Configuration Fields

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

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.

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

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.

IDE Code Snippets

hitf codesnippets generates IDE code snippets for quickly inserting translation ignore comments.

Basic Command

hitf codesnippets           # Auto-detect IDE (.vscode / .idea / .cursor)
hitf codesnippets vscode    # Generate VS Code snippets
hitf codesnippets webstorm  # Generate WebStorm templates
hitf codesnippets cursor    # Generate Cursor snippets
hitf codesnippets sublime   # Generate Sublime Text snippets

Auto Detection

The command automatically detects the IDE type in your workspace:

Directory	Detection Result
`.vscode/`	VS Code
`.idea/`	WebStorm / IntelliJ
`.cursor/`	Cursor
No match	Default VS Code

Generated Snippets

Prefix	Purpose
`@hitf-i18n-ignore-next`	Ignore next extractable segment
`@hitf-i18n-ignore-start`	Ignore range start
`@hitf-i18n-ignore-end`	Ignore range end
`@hitf-i18n-ignore-file`	Ignore entire file
`@hitf-i18n-ignore:prop:<attrName>`	Ignore a specific static attribute in Vue templates (e.g. `<!-- @hitf-i18n-ignore:prop:placeholder -->`, auto-inserted by `-i` deselection)

Usage

VS Code / Cursor

Run hitf codesnippets vscode
Type @hitf-i18n-ignore-next in code
Press Tab to expand

WebStorm

Run hitf codesnippets webstorm
View in Settings > Editor > Live Templates

Sublime Text

Run hitf codesnippets sublime
Type @hitf-i18n-ignore-next in code
Press Tab to expand

Snippet Content

Each snippet includes bilingual descriptions, for example:

json

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

Service Setup Guide

hitf supports multiple translation services. Official signup links:

Service	Link
Tencent Translate	Sign up
Baidu Translate	Sign up
OpenAI	Sign up
Google Translate	Sign up

Configuration Example

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

Configuration & Setup ​

Global Configuration ​

Basic Command ​

Configuration Structure ​

Priority ​

Project Configuration ​

Basic Command ​

Configuration Structure ​

Configuration Fields ​

Language Direction ​

i18nCallTemplate Configuration ​

i18nImport Configuration ​

Key Strategy ​

Unused Key Cleanup ​

Multi-Project outDir Configuration ​

Output Directory ​

IDE Code Snippets ​

Basic Command ​

Auto Detection ​

Generated Snippets ​

Usage ​

VS Code / Cursor ​

WebStorm ​

Sublime Text ​

Snippet Content ​

Service Setup Guide ​

Configuration Example ​

Configuration & Setup

Global Configuration

Basic Command

Configuration Structure

Priority

Project Configuration

Basic Command

Configuration Structure

Configuration Fields

Language Direction

i18nCallTemplate Configuration

i18nImport Configuration

Key Strategy

Unused Key Cleanup

Multi-Project outDir Configuration

Output Directory

IDE Code Snippets

Basic Command

Auto Detection

Generated Snippets

Usage

VS Code / Cursor

WebStorm

Sublime Text

Snippet Content

Service Setup Guide

Configuration Example