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/services.json 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

Translate a Folder

For bulk translation, preview and save a report first:

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

-d / --dry-run previews the translation plan only: in a TTY it opens a read-only tree (↑/↓ move, ←/→ collapse/expand, type to search, Enter to finish); in a non-TTY environment it falls back to a static tree printout. No translation is performed and no files are written.

For interactive selection:

hitf tfo src\views demo -i

-i / --interactive opens a tree checkbox to choose which texts to translate (Space toggles, Ctrl+A selects all, Ctrl+I inverts, Enter confirms). Deselected items get @hitf-i18n-ignore-* comments automatically and are skipped.

Learn More

• Translation Workflow - Translate files, folders, consistency check, rollback
• Cache Management - Export source texts, import company tables, apply cache
• Configuration & Setup - Global config, project config, IDE snippets
• FAQ - Frequently asked questions