CLI 參考

為指令上的每個旗標執行 ai-i18n-tools <command> --help。下方的群組頁面提供了額外的上下文、關鍵選項以及主題指南的連結。

指令概覽

快速入門

指令	摘要
version	印出 CLI 版本與建置時間戳記。
init	寫入入門設定；-t 選擇骨架範本。
help	顯示子命令的說明。

模型與語言

指令	摘要
check-models	根據目前使用的供應商驗證已設定的模型 ID。
list-models	列出目前使用的供應商所提供的模型。
bench-models	在一個翻譯範本上對已設定的模型進行基準測試。
list-languages	列出內建的 UI 語言目錄。

介面字串

指令	摘要
extract	從來源字面值與 HTML 標記更新 strings.json。
mark-html	將 data-i18n* 標記插入 HTML 檔案中。
migrate-intlayer	匯入 Intlayer .content.ts 字典，並將簡單的 useIntlayer / getIntlayer 網站重寫為 t()。
generate-ui-languages	根據設定的語系寫入 ui-languages.json。
translate-ui	翻譯 UI 字串 (strings.json → 語系 JSON)。
sync-ui	擷取並翻譯 UI 字串。
proofread-ui	擷取並由 LLM 審查來源語系的 UI 字串。
export-ui-xliff	將 strings.json 匯出為 XLIFF 2.0。

文件

指令	摘要
translate-docs	翻譯 Markdown、MDX、.astro 與框架目錄。
write-heading-ids	在 ATX 標題前插入 HTML 錨點行。
check-markdown	掃描 Markdown/MDX 以找出分隔符號與強調語法的問題。

JSON 與 SVG

指令	摘要
translate-json	根據 json[] 設定區塊翻譯巢狀 JSON。
translate-svg	翻譯在 config.svg 中設定的 SVG 檔案。

工作流程與報表

命令	摘要
sync	在單一管線中執行擷取 + UI + SVG + 文件 + JSON。
status	列印 UI、文件與 JSON 翻譯覆蓋率。
statistics	列印快取與 strings.json 統計資料。
usage	列印已記錄的模型 API 呼叫代幣與成本。

快取維護

指令	摘要
cleanup	清理過時/孤立/未設定語系的快取列並重新填充 Markdown 問題。
clean-temp	尋找並刪除 *.log、*.tmp 與快取備份。
purge-locale	移除指定地區設定的快取列與產生的產物。

儀表板與詞彙表

命令	摘要
dashboard (dash)	啟動翻譯儀表板網頁介面。
glossary-generate	寫入空白的 glossary-user.csv 範本。

概要

ai-i18n-tools version
ai-i18n-tools init [-t ui-markdown|ui-docusaurus|ui-starlight|ui-vitepress|ui-nextra|ui-fumadocs|ui-astro-website|ui-json-bundles] [-o path] [-P <provider>] [--with-translate-ignore]
ai-i18n-tools help [command]
ai-i18n-tools check-models
ai-i18n-tools list-models
ai-i18n-tools bench-models [--model <ids>] [--text <text>|--file <path>] [--source <locale>] [--target <locale>]
ai-i18n-tools list-languages [search]
ai-i18n-tools extract
ai-i18n-tools mark-html [paths...] [--write]
ai-i18n-tools migrate-intlayer [paths...] [--write] [--report <path>] [--content-glob <glob>] [--t-import <specifier>]
ai-i18n-tools generate-ui-languages [--master path] [--dry-run]
ai-i18n-tools translate-ui …
ai-i18n-tools sync-ui …
ai-i18n-tools proofread-ui …
ai-i18n-tools export-ui-xliff …
ai-i18n-tools translate-docs …
ai-i18n-tools write-heading-ids …
ai-i18n-tools check-markdown [-p|--path <path>] [-f|--file <path>] [--json] [--no-cache]
ai-i18n-tools translate-json …
ai-i18n-tools translate-svg …
ai-i18n-tools sync …
ai-i18n-tools status …
ai-i18n-tools statistics …
ai-i18n-tools usage …
ai-i18n-tools cleanup …
ai-i18n-tools clean-temp …
ai-i18n-tools purge-locale -l <code> [-l <code> …] [--dry-run] [-y|--yes] [-f|--force] [--keep-files] [--backup <path>]
ai-i18n-tools dashboard …
ai-i18n-tools glossary-generate

根目錄和全域選項

選項	範圍	說明
-V / --version	根程式碼	輸出版本號和建置時間戳記（與 version 子命令的資訊相同）。
-h / --help	根程式	顯示根程式或與命令名稱一起使用的子命令的說明。
-c / --config <path>	每個命令	設定檔路徑（預設值：ai-i18n-tools.config.json）。
-v / --verbose	每個命令	詳細記錄。
-P / --provider <name>	每個指令	此執行緒的活躍 LLM 提供者；會覆寫組態 provider 鍵。必須在 providers 下進行組態。
-L / --ui-lang <code>	每個指令	工具自身 UI（CLI 說明、日誌/摘要、儀表板）的語言；最高優先級來源。請參閱工具 UI 語言。
-w / --write-logs [path]	選定的命令	將控制台輸出導向至 .log 檔案（預設路徑：在根目錄 cacheDir 下）。僅適用於 translate-docs、translate-json、translate-svg、translate-ui、sync-ui、sync 和 cleanup。
--debug-failed	翻譯指令	在根目錄 cacheDir 下為每次被捨棄的翻譯檢查（錯誤腳本、解析或品質）撰寫 FAILED-TRANSLATION 日誌，包含備用方案——不僅在所有模型失敗時才撰寫。供應商 API / 空請求體錯誤會在控制台印出（每個模型和錯誤訊息各一次），且不會寫入這些檔案。適用於 translate-ui、translate-docs、translate-json、translate-svg、sync-ui、sync 和 cleanup。

命令說明

用法	說明
ai-i18n-tools <command> --help	該命令的所有選項。
ai-i18n-tools help <command>	與 <command> --help 相同的輸出。

目標地區設定（-l / --locale）

命令	行為
translate-docs、translate-json、translate-svg、translate-ui、sync、sync-ui、export-ui-xliff	-l / --locale <codes> — 以逗號分隔的目標 BCP-47 代碼（例如 de,fr,pt-BR）。省略時，預設值來自設定（json[] 區塊也可以設定每個區塊的 targetLocales；UI 步驟使用 targetLocales 減去 sourceLocale）。
proofread-ui	-l / --locale <code> — 要審核的單一來源語言（預設：設定檔 sourceLocale）。