Translation Cache Management

This page covers the complete translation cache workflow: export source texts, import company translation tables, and apply cache to locale files.

Export Source Texts

export-source (short command tes) extracts unique source texts from code and exports to XLSX.

Command

hitf export-source src\views

Execution Flow

1. Recursively scans all supported files (.vue, .js, .ts, .jsx, .tsx, .json) under the specified path
2. Extracts all translatable texts and deduplicates
3. Fills all locale columns based on locales configuration:
   • Source locale column: uses extracted text directly
   • Target locale columns: attempts translation via API
   • Columns are left empty (no error) when API is not configured
4. Outputs to .hitf/source-texts-<locale>.xlsx

Options

Option	Short	Description
-s, --source <locale>	-s	Source locale code, default uses configured source language
-o, --out <file>	-o	Output file path, default .hitf/source-texts-<locale>.xlsx

Export Translated Locale Files

export-translated (short command etr) reads texts from translated locale JSON files and exports to XLSX.

Command

hitf export-translated

When no file is specified, it automatically scans locale files under outDir:

• outDir is a string: reads namespace subdirectories under that path
• outDir is an object: shows project multi-select (e.g., main/web), merges selected projects' data

Execution Flow

1. Reads all locale JSONs (e.g., zh-CN.json, en-US.json, ja-JP.json)
2. Builds source text → { zh-CN: '...', en-US: '...', ja-JP: '...' } mapping
3. Missing target translations → attempts translation via API
4. API not configured → columns left empty
5. Incrementally merges with existing xlsx content

Options

Option	Short	Description
-s, --source <locale>	-s	Source locale code
-o, --out <file>	-o	Output file path, default .hitf/source-texts-<locale>.xlsx

Import Translation Tables

cache-import (short command tci) imports human-edited translation tables into .hitf/.translation-cache.json for reuse in subsequent translations.

Typical workflow: export XLSX with export-source / export-translated, manually edit or proofread translations, then import with this command.

Command

hitf cache-import .hitf/source-texts-zh-CN.xlsx

Or use the short command:

hitf tci .hitf/source-texts-zh-CN.xlsx

Recommended Format

.xlsx format. The first row contains language codes, and each subsequent row is one text entry.

zh-CN	en-US	ja-JP
登录	Login	ログイン
正常状态	Normal Status	正常状態
请输入用户名	Please Enter Username	ユーザー名を入力してください

This format is friendly for product, operations, and translation teams, and makes it easy to add language columns later.

Supported Formats

Format	Description
.xlsx	Recommended format
.xlsm	Compatible for import

Multilingual Write Method

The import tool writes each target language to the translation cache:

{
  "zh-CN|en-US": {
    "登录": "Login"
  },
  "zh-CN|ja-JP": {
    "登录": "ログイン"
  }
}

When translating from zh-CN to en-US or ja-JP, the cache is prioritized.

Common Options

Specify source language:

hitf tci .hitf/source-texts-zh-CN.xlsx -s zh-CN

Specify worksheet:

hitf tci .hitf/source-texts-zh-CN.xlsx -S Sheet1

Overwrite existing cache:

hitf tci .hitf/source-texts-zh-CN.xlsx -o

Option	Short	Description
-s, --source <locale>	-s	Source locale column, default uses zh-CN when present
-S, --sheet <name>	-S	XLSX worksheet name, default uses the first sheet
-o, --overwrite	-o	Overwrite existing cached translations when values differ

Use Cases

1. Export with export-source / export-translated, manually add translations, then import.
2. Import existing multilingual assets from your company.
3. Languages like Japanese and Korean need human translation for natural expression.
4. Multiple projects share the same business terminology.

Apply Cache to Locale Files

cache-apply (short command tca) writes translation results to locale JSON files under outDir.

Command

hitf tca

How it works

1. Uses the source-locale JSON (key → source text) as the lookup table
2. Cache hit → uses the cached translation directly
3. Cache miss → automatically calls the translation API, results are cached
4. JSON structure and all other key-value pairs are preserved; source files are never touched

Use cases

1. replaceOriginalFile: true mode: Source files have been rewritten to $t() calls, re-running tf / tfo can no longer extract Chinese text. cache-apply can re-translate from locale files.
2. Translation service switch: Changed translation API (e.g., from Baidu to OpenAI), need to re-translate uncached entries.
3. Post-network recovery: Previously failed translations due to network issues, now network is back, re-translate failed entries.
4. Post dictionary import: After importing new dictionary via cache-import, refresh locale files.

Common usage

# Process a single namespace only (a subdirectory under outDir)
hitf tca views

# Specify the project key when outDir is an object
hitf tca -p admin

Execution flow

1. Reads source-locale JSON (e.g., zh-CN.json) as key → source text lookup table
2. For each key, checks translation cache:
   • Hit → uses cached translation
   • Miss → calls translation API, caches the result
3. Updates target-locale JSON (e.g., en-US.json)
4. Re-running is idempotent — nothing is written when locale files are already up to date

Closed-Loop Workflow

The four commands form a complete loop:

# 1. Extract texts from source code
hitf export-source src\views

# 2. Supplement from translated locale files (optional, both commands share the same file with incremental merge)
hitf export-translated

# 3. Import to translation cache
hitf tci .hitf/source-texts-zh-CN.xlsx

# 4. Apply cache back to locale files
hitf tca