Cache Import

cache-import imports your company's existing translation tables into .hitf/.translation-cache.json for reuse in subsequent translations.

Command

hitf cache-import .\.hitf\company.xlsx

Or use the short command:

hitf tci .\.hitf\company.xlsx

Recommended Format

.xlsx is recommended. 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, suitable for company maintenance
.xlsm / .xls	Compatible for import
.tsv / .txt	Tab-separated plain text tables

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\company.xlsx -s zh-CN

Specify worksheet:

hitf tci .\.hitf\company.xlsx -S Sheet1

Overwrite existing cache:

hitf tci .\.hitf\company.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

When to Use

Import your company's glossary before batch translation, especially in these scenarios:

1. Short words like login, menu, button, and status need consistent capitalization.
2. Your company already has multilingual assets and you don't want to call machine translation again.
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)

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

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

hitf tca

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