安裝

已發佈的套件為 僅 ESM。請在 Node.js 或您的建置工具中使用 import/import()；請勿使用 require('ai-i18n-tools')。該套件宣告了 engines.node >=22.16.0；舊版 Node.js 不受支援。npm tarball 僅在 docs/ 下包含英文檔案；位於 translated-docs/ 的地區設定專用副本位於 GitHub 儲存庫。

npm install ai-i18n-tools
# or
pnpm add ai-i18n-tools
# or
yarn add ai-i18n-tools

ai-i18n-tools 包含自己的字串提取器。如果您先前使用 i18next-scanner、babel-plugin-i18next-extract 或類似工具，遷移後可以移除這些開發相依性。

使用 CLI

在您的專案中安裝 ai-i18n-tools 作為依賴項或開發依賴項（請參閱上方的 安裝）。該套件宣告了一個 bin 條目，您的套件管理器會將其連結到 node_modules/.bin/ai-i18n-tools。該墊片（安裝套件內的 bin/ai-i18n-tools.mjs）會載入已編譯的 CLI。

要在互動式 shell 中輸入裸 ai-i18n-tools 指令，請設定下方其中一個選項。若未進行設定，即使完成本地安裝，shell 也無法找到該二進位檔案。

direnv — 在專案根目錄的 .envrc 中新增（bash/zsh；請參閱 direnv.net）：

PATH_add node_modules/.bin

在 direnv allow 之後，每當您 cd 進入專案時，裸指令即可使用。

手動 PATH — 請從專案根目錄（包含 node_modules/.bin 的目錄）執行這些指令。只要您保留該 PATH 項目，子目錄之後仍會繼續運作；從巢狀資料夾重新執行匯出會失敗，因為 $PWD 不再指向專案根目錄。

# bash/zsh — from the project root
export PATH="$PWD/node_modules/.bin:$PATH"
ai-i18n-tools sync

# Windows PowerShell — from the project root
$env:Path = "$PWD\node_modules\.bin;$env:Path"
ai-i18n-tools sync

全域安裝 — 安裝 CLI 一次後即可從任何目錄呼叫：

npm install -g ai-i18n-tools
# or
pnpm add -g ai-i18n-tools

使用 pnpm 時，如果遺漏全域指令，請在每台機器上執行一次 pnpm setup（並開啟新的 shell）— pnpm 需要將其全域 bin 目錄放在 PATH 上。全域安裝會使用全域鎖定的版本。若要針對個別專案鎖定版本，建議使用 direnv 或手動 PATH，讓 node_modules/.bin 解析至專案的依賴項目。

package.json 指令稿 — 當 npm 或 pnpm 執行指令稿時，會將 node_modules/.bin 前置到 PATH，因此在指令稿內部可以直接使用指令名稱而無需變更殼層的 PATH。建議使用 sync 而非手動串接翻譯步驟——手動執行時順序和功能旗標很容易出錯：

"scripts": {
  "i18n:extract": "ai-i18n-tools extract",
  "i18n:sync": "ai-i18n-tools sync",
  "i18n:translate:ui": "ai-i18n-tools translate-ui",
  "i18n:translate:svg": "ai-i18n-tools translate-svg",
  "i18n:translate:docs": "ai-i18n-tools translate-docs",
  "i18n:translate:json": "ai-i18n-tools translate-json",
  "i18n:dashboard": "ai-i18n-tools dashboard"
}

然後執行例如 pnpm run i18n:sync。請參閱建議的 package.json 指令稿以取得完整建議清單。

替代方案 — 若您不願調整 PATH：npx ai-i18n-tools … (npm) 或 pnpm exec ai-i18n-tools … (pnpm)。若要在沒有 package.json 項目的情況下進行零安裝的一次性執行：npx ai-i18n-tools <cmd> 或 pnpm dlx ai-i18n-tools <cmd>。

已複製的 ai-i18n-tools monorepo

在從 ai-i18n-tools 的完整複本開發套件或執行工作區 examples 時：

• 工作區範例（examples/console-app、examples/nextjs-app，以及 pnpm-workspace.yaml 中列出的其他套件）— 在儲存庫根目錄執行 pnpm install，然後執行 cd examples/<name>。使用範例的 pnpm run i18n:* 腳本，或設定 PATH（請參閱 使用 CLI）並直接執行 ai-i18n-tools …。工作區 overrides 會將 ai-i18n-tools 連結到你的本地檢出。
• 儲存庫根目錄 — pnpm 不會將根套件自身的 bin 連結到 node_modules/.bin。請改用 node bin/ai-i18n-tools.mjs … 或根 pnpm i18n:* 腳本（或 shell 別名 / pnpm add -g . — 請參閱 開發指南）。
• 獨立夾具 (multi-provider, test-markdown) — 從夾具資料夾中，使用 node ../../bin/ai-i18n-tools.mjs …。

變更 CLI 原始碼後，請在儲存庫根目錄執行 pnpm run build。請參閱開發指南以了解建置步驟與可選的全域安裝替代方案。

在 Linux、macOS 和 WSL 上，登錄檔安裝會自動為 CLI 指令碼設定可執行位元。在 Windows 上，套件管理器會產生 .cmd 和 .ps1 代理程式，明確叫用 Node。

翻譯指令 (translate-ui, translate-docs, translate-json, translate-svg, sync) 需要在 ai-i18n-tools.config.json 中進行 供應商設定，並為目前使用的供應商提供 API 金鑰。執行 ai-i18n-tools init [-P <provider>] 來建立預設的供應商區塊（省略時為 openrouter）；編輯 provider / providers 來切換預設值或模型 — 請參閱 LLM 供應商與模型。Ollama 是唯一不需要 API 金鑰的內建預設值。

設定與你目前使用的供應商相符的 API 金鑰（請參閱 預設值表格）：

# Default init (openrouter)
export OPENROUTER_API_KEY=sk-or-v1-your-key-here
# Example: init -P anthropic
# export ANTHROPIC_API_KEY=sk-ant-your-key-here

或在專案根目錄建立 .env 檔案：

OPENROUTER_API_KEY=sk-or-v1-your-key-here

工具使用者介面語言

CLI 會將其自身的說明文字、日誌摘要與翻譯儀表板進行本地化，這與您所翻譯的地區設定無關。預設情況下，它會遵循您的作業系統地區設定。請在設定中使用 -L pt-BR、export AI_I18N_LANG=es 或 "uiLanguage" 進行覆寫。請參閱工具介面語言。