Quick Start

This page demonstrates how to use hitf in an existing project to migrate source language text. Source code can be Chinese, English, or other non-English languages.

Installation

npm install -g @ansstory/hitf

Requires Node.js >= 18.

After installation, verify the command:

hitf -v
hitf --help

Initialize Configuration

Navigate to your business project directory:

# Initialize project translation settings
hitf setting
# Add .hitf to gitignore to prevent appId and secretKey from being committed
hitf gitignore

This generates or opens the project-level config .hitf/setting.json.

If you have translation service credentials, add them to the config:

{
  "translationSetting": {
    "translationService": "tencent",
    "services": {
      "tencent": {
        "secretId": "your_secret_id",
        "secretKey": "your_secret_key"
      }
    },
    "locales": ["zh-CN", "en-US"],
    "outDir": ".hitf/lang",
    "replaceOriginalFile": false
  }
}

If you don't have credentials, you can still migrate the structure. The tool writes source text to locale files, and you can add translations later.

If your source code is English, adjust the locales order to translate from English to other languages:

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

Translate a Single File

hitf tf src\views\demo\index.vue

By default, replaceOriginalFile is false, so translated file copies and locale files are written to the output directory specified by outDir. Set to true to replace the original file directly.

Typical output:

Translation output saved to: .hitf\lang\demo

You can also translate in bulk. Preview and save a report first:

hitf tfo src\views
# Preview mode
hitf tfo src\views demo -d -r .hitf\reports\demo.json

For interactive confirmation:

hitf tfo src\views demo -i

Import Company Translation Tables

If your company provides Chinese-English, Japanese, or other translation tables, import them into the cache first:

hitf tci .\.hitf\company.xlsx

Recommended format:

zh-CN	en-US	ja-JP
登录	Login	ログイン
正常状态	Normal Status	正常状態

After importing, hitf tf will prioritize existing translations from .hitf/.translation-cache.json.

Check Locale Files

After translation, verify that source references and locale files are consistent:

hitf tcheck src -r .hitf\reports\tcheck.json

It reports missing keys, unused keys, inconsistent keys across locale JSON files, and unparseable JSON files.