CLI — 開始使用
version
概要: ai-i18n-tools version
印出 CLI 版本與建置時間戳記(與根程式上的 -V / --version 資訊相同)。
upgrade
概要: ai-i18n-tools upgrade [--yes]
將正在執行的安裝升級到最新發佈的版本。該命令會列印已安裝的版本和新版本,然後等待 y。--yes 會回應提示,包括當標準輸入不是終端機時。任何其他答案都會使安裝保持不變。沒有 --yes 的非互動式標準輸入會以錯誤結束,並且不進行任何更改。當安裝已是最新版本,或比發佈版本更新時,該命令會列印此訊息且不提示。
Node.js 安裝會從 npm 登錄檔讀取 latest dist-tag。專案依賴項會在 package.json 中更新(保留現有的 ^、~ 或精確運算子),並使用 npm、pnpm、yarn 或 bun 進行安裝,這些工具是從 packageManager 欄位或鎖定檔中選擇的。全域 Node.js 安裝會執行該套件管理器的全域安裝,並且不會編輯目前目錄中的 package.json。workspace:、file:、link: 和 git 規範符號保持不變,命令停止。拒絕此儲存庫的原始碼檢出。
獨立可執行檔會讀取最新的 GitHub 發行版,下載適用於目前作業系統和架構的 gzip 壓縮檔,檢查 SHA256SUMS.txt,並替換正在執行的檔案。已發佈的壓縮檔包括 Linux x64、Linux arm64、macOS arm64、macOS x64 和 Windows x64。
ai-i18n-tools upgrade
ai-i18n-tools upgrade --yesinit
綱要: ai-i18n-tools init -P <provider> [-t <template>] [-o <path>] [--with-readme] [--with-translate-ignore]
撰寫入門設定檔(包含 provider / providers、concurrency、uiBatchConcurrency、batchConcurrency、batchSize、maxBatchChars 與 docs[].addFrontmatter)。呼叫 LLM 的翻譯指令需要在環境變數或 .env 中提供目前供應商的 API 金鑰(Ollama 除外)— 請參閱供應商與 API 金鑰。
主要選項: -P / --provider(必要)、-t / --template、-o / --output、--with-readme、--with-translate-ignore
-P / --provider 為必填項。它用於選擇要建立骨架的 內建預設。必須是以下其中一項:openrouter、openai、anthropic、gemini、deepseek、cerebras、groq、mistral、xai、nvidia、alibaba、apikeyfan、cheaperinference、ollama。
範本(-t):
| 值 | 產生的結構 |
|---|---|
ui-markdown | UI 字串加上 README(扁平輸出、語言清單) |
ui-docusaurus | Docusaurus UI + 文件 |
ui-starlight | Starlight 文件 |
ui-vitepress | VitePress 文件(docsOutput.style: "vitepress")加上主題字串的 vitepressThemeCatalog |
ui-nextra | Nextra 文件(docsOutput.style: "nextra")加上主題字典的 nextraDictionaryPath(側邊欄 _meta.ts 會自動收集) |
ui-fumadocs | Fumadocs 文件(docsOutput.style: "fumadocs")加上 UI 覆寫的 fumadocsUiCatalog(側邊欄 meta.json 會自動收集) |
ui-astro-website | Astro 網站 UI 字串 |
ui-plain-html | 純 HTML 目錄(data-i18n* 標記、扁平化語系 JSON) |
docs-plain-html | 純 HTML 文件(每個語系一個檔案、語言清單、hreflang) |
docs-markdown | Markdown 文件:README 與 .md 檔案、扁平輸出、語言清單 |
ui-json-bundles | JSON(僅 json[]) |
ui-python | Python UI 字串、以來源語言字串為鍵的扁平 JSON,以及 i18n.py |
ui-python-gettext | 包含扁平化 JSON 與 GNU .po / .mo 的 Python UI 字串,外加 i18n.py |
ui-python-django | Django gettext / {% blocktrans %} 目錄(flatOutput: false、網域 django,無 i18n.py) |
ui-python-flask | translations/ 下的 Flask / Jinja 目錄(flatOutput: false)外加 i18n.py |
ui-dotnet | .NET UI 字串、以來源語言字串為鍵的平面 JSON,以及 I18n.cs |
ui-dotnet-resx | .NET UI 字串作為 .resx 附屬組件 (flatOutput: false),以及 I18nResx.cs |
--with-readme 會附加一個 README.md 文件區塊(outputDir translated-docs、docsOutput.style "flat"、一個 languageListBlock),並將 features.translateDocs 設定為 true。當文件區塊已列出 README.md 時,此指令不會執行任何動作,ui-markdown 與 docs-markdown 即是這種情況。此指令只會寫入設定檔。此指令會印出標記行以便貼到 README.md 中,並在該檔案遺失時發出警告。指南:將 i18n 新增至您的 README 與 Markdown 文件。
ai-i18n-tools init -t docs-markdown -P openrouter
ai-i18n-tools init -t ui-python -P openrouter --with-readme--with-translate-ignore 會建立一個啟動器 .translate-ignore(包含 Python 虛擬環境與快取目錄)。
init 也會在工作目錄中建立 .gitignore,或附加到其中。新增的行是 .translation-cache/*、!.translation-cache/cache.db、benchmark-scores.json、.env、.env.local、.env.*.local、*.tmp 和 *.backup.*,每一行都帶有簡短註解。已存在的行會保持不變,第二次執行也不會重複新增。
ui-python、ui-python-gettext 和 ui-python-flask 也會在該檔案遺失時寫入 i18n.py。Django 專案會保留 Django 自己的 gettext 執行階段,因此 ui-python-django 不會寫入 i18n.py。ui-dotnet 會在該檔案遺失時寫入 I18n.cs,並列印要新增至 .csproj 的 EmbeddedResource 項目。ui-dotnet-resx 則會寫入 I18nResx.cs,並將 ui.resx 指向 Resources/SharedResource.<culture>.resx。--namespace 會覆寫 C# 命名空間。指南:.NET 應用程式 和 將 i18n 新增至 .NET ResourceManager 應用程式。
migrate-python-i18n 會將不安全的預先評估呼叫 (_(f"...")、_("..." % expr)、_("...".format(...))) 重寫為先查詢後格式化的呼叫。預設為模擬執行。傳遞 --write 以編輯檔案,並閱讀 migrate-python-i18n-report.md 以取得審閱備註。當複雜表達式穩定時,會從該表達式命名 (start.isoformat() 變成 {start},len(rows) 變成 {rows_count})。剩餘的 {value_1} 會被報告,以便重新命名。產生的 i18n.py 檔案會被跳過。乾淨的報告不代表未包裝的 f-string 已被涵蓋。
migrate-dotnet-i18n 對於 T() 內部的 T($"...")、串聯以及 string.Format 執行相同的處理。--wrap 也會標記未標記的 XAML 標籤和高可信度 C# 接收器;如果沒有 --write,這將是一次審計。報告為 migrate-dotnet-i18n-report.md。生成的 I18n.cs 和 I18nResx.cs 會被跳過。指南:.NET 應用程式。
doctor
概要: ai-i18n-tools doctor [--local] [--strict] [--json] [--fix-gitignore]
檢查專案是否已準備好進行翻譯。報告涵蓋配置語法和結構描述、業務規則、已安裝版本、來源和輸出路徑、UI 目錄檔案、這些目錄中的預留位置不符、快取統計資料、已配置的提供者、已設定的支援環境變數以及模型 ID。包含已重新命名、已移除或已重寫預留位置的目錄會發出警告,並列出一個範例。提供者區段僅列出配置檔案中命名的提供者(包括一個舊版頂層 openrouter 區塊)。內建的 OpenRouter 預設值僅在檔案未命名提供者時列出。
依預設,doctor 也會根據作用中提供者的目錄檢查已配置的模型 ID,並將已安裝的版本與最新的 GitHub 版本進行比較。--local 會跳過這兩個網路呼叫。較新的版本,或失敗的 GitHub 請求,會產生警告。遺失或過期的模型 ID 會導致命令失敗。當任何檢查發出警告時,--strict 會以錯誤結束。
API 金鑰值絕不列印。已設定的變數會依字母順序列出,如 Configured variables: NAME, ... 所示。非 API 金鑰的變數會包含其值。
遺失的輸入路徑會導致失敗。遺失的輸出目錄僅為備註,因為首次翻譯執行會建立它們。doctor 不會重寫組態、建立目錄或將原始文字傳送至模型。--fix-gitignore 會附加遺失的 .gitignore 行,並保留所有其他檔案不變。
當組態旁的 .gitignore 遺失必要的模式時,doctor 會發出警告。該警告會指示您執行 ai-i18n-tools doctor --fix-gitignore。當 .gitignore 已存在時,它會附加一個空白行、註解 # ai-i18n-tools doctor fix,以及僅限遺失的行。它不會重複已存在的行。遺失的檔案會以 init 寫入的相同區塊建立。這兩個快取模式遵循已設定的 cacheDir,因此 .i18n-cache 需要 .i18n-cache/* 和 !.i18n-cache/cache.db,而不是預設的 .translation-cache 行。其他模式為 benchmark-scores.json、.env、.env.local、.env.*.local、*.tmp 和 *.backup.*。忽略快取目錄本身的行,例如 .i18n-cache/,也是一個警告,因為 Git 不會在被忽略的目錄下追蹤 cache.db。--fix-gitignore 不會移除該行。該警告僅在搭配 --strict 時才會使命令失敗。
主要選項: --local、--strict、--json、--fix-gitignore
ai-i18n-tools doctor
ai-i18n-tools doctor --local
ai-i18n-tools doctor --fix-gitignorehelp
概要: ai-i18n-tools help [command]
顯示子命令的說明(輸出與 ai-i18n-tools <command> --help 相同)。