安裝
本頁面將說明如何安裝 CLI,並讓基本的 ai-i18n-tools 指令能夠運作。已經安裝了嗎?請前往 快速入門。
已發佈的套件僅支援 ESM。在 Node.js 或您的打包器中使用 import 或 import();請勿使用 require('ai-i18n-tools')。該套件宣告了 engines.node >=22.16.0;不支援較舊的 Node.js 版本。npm tarball 包含位於 docs/ai-i18n-tools-context.md 的消費者上下文和完整的 skills/ 樹,而非完整的說明文件網站;translated-docs/ 下的地區設定特定副本位於 GitHub 儲存庫。
npm install ai-i18n-tools
# or
pnpm add ai-i18n-tools
# or
yarn add ai-i18n-tools獨立執行檔
GitHub 發行版附帶一個 Node.js 單一執行檔建置。當專案不在 Node.js 上執行時,請使用該二進位檔。Python 和 .NET 專案可從中執行相同的 CLI,包括 extract、translate-ui 和 suggest-models,無需安裝 Node.js。
Linux 和 macOS:
curl -fsSL https://raw.githubusercontent.com/wsj-br/ai-i18n-tools/main/install.sh | bashWindows (PowerShell):
irm https://raw.githubusercontent.com/wsj-br/ai-i18n-tools/main/install.ps1 | iex安裝程式會偵測系統,下載符合的可執行檔的 gzip 壓縮檔,檢查 SHA256SUMS.txt,解壓縮,將指令安裝為 ai-i18n-tools (在 Windows 上為 ai-i18n-tools.exe),並將安裝目錄新增至 PATH。Linux 和 macOS 使用 gzip 解壓縮。Windows PowerShell 使用 .NET gzip 讀取器解壓縮,該讀取器已是 Windows 的一部分。預設目錄是 ~/.local/bin。如果尚未找到指令,請開啟新的終端機。設定 AI_I18N_VERSION (例如 v1.11.0) 以釘選發行版本,或設定 AI_I18N_INSTALL_DIR 以選擇另一個目錄。在 gzip 壓縮檔之前發行的版本仍包含原始可執行檔,且安裝程式接受該檔案。
這些二進位檔未經公證或 Authenticode 簽署。macOS 可能會要求您批准未簽署的程式。Windows SmartScreen 可能會顯示警告。macOS 安裝程式會在校驗和匹配後清除隔離旗標。
每個發行版也附帶 SHA256SUMS.txt、ai-i18n-tools-python-examples.zip(四個 Python 範例)和 ai-i18n-tools-dotnet-examples.zip(dotnet-console、dotnet-resx 以及這些專案編譯的 assets/dotnet 輔助程式)。在 .NET 封存檔之前發佈的發行版不包含它。從新增技能封存檔的發行版開始,同一頁面包含 ai-i18n-tools-skill.zip,即每個編碼代理技能目錄。在該技能壓縮檔之前發佈的發行版不包含它,且第一個技能壓縮檔僅包含 ai-i18n-tools/。install.sh 和 install.ps1 留在儲存庫根目錄,且上述指令從那裡下載它們。npm tarball 和執行檔不包含範例封存檔或技能壓縮檔。範例留在儲存庫中。技能目錄位於 npm tarball 內部。請參閱 編碼代理技能。
手動安裝 ai-i18n-tools 可執行檔的說明
| 平台 | 資產 |
|---|---|
| Linux x64 | ai-i18n-tools-linux-x64.gz |
| Linux arm64 | ai-i18n-tools-linux-arm64.gz |
| macOS arm64 | ai-i18n-tools-macos-arm64.gz |
| macOS x64 | ai-i18n-tools-macos-x64.gz |
| Windows x64 | ai-i18n-tools-win-x64.exe.gz |
- 從 GitHub 發行版本 頁面下載符合機器的資產和
SHA256SUMS.txt。 - 檢查 gzip 壓縮檔的總和檢查碼。在 Linux 上,
grep ' ai-i18n-tools-linux-x64.gz$' SHA256SUMS.txt | sha256sum -c -(使用您下載的資產名稱)。在 macOS 上,使用shasum -a 256 -c -的相同行。在 Windows 上,(Get-FileHash -Algorithm SHA256 .\ai-i18n-tools-win-x64.exe.gz).Hash並將其與SHA256SUMS.txt中的雜湊值進行比較。 - 解壓縮檔案並將指令放在
PATH。
Linux 和 macOS,以 Linux x64 資產為例 (請替換為您下載的資產):
mkdir -p "$HOME/.local/bin"
gzip -dc ai-i18n-tools-linux-x64.gz > "$HOME/.local/bin/ai-i18n-tools"
chmod +x "$HOME/.local/bin/ai-i18n-tools"如果 $HOME/.local/bin 尚未在 PATH 中,請將以下內容新增至您的 shell 設定檔 (.bashrc、.bash_profile、.profile 或 .zshrc),並開啟一個新的終端機:
export PATH="$HOME/.local/bin:$PATH"Windows (PowerShell)。GZipStream 是 Windows PowerShell 的一部分;無需單獨安裝 gzip:
New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.local\bin" | Out-Null
Add-Type -AssemblyName System.IO.Compression
$gz = [System.IO.File]::OpenRead("$PWD\ai-i18n-tools-win-x64.exe.gz")
$outPath = "$env:USERPROFILE\.local\bin\ai-i18n-tools.exe"
try {
$gzipStream = New-Object System.IO.Compression.GZipStream($gz, [System.IO.Compression.CompressionMode]::Decompress)
try {
$out = [System.IO.File]::Create($outPath)
try { $gzipStream.CopyTo($out) } finally { $out.Dispose() }
} finally { $gzipStream.Dispose() }
} finally { $gz.Dispose() }
$installDir = "$env:USERPROFILE\.local\bin"
$userPath = [Environment]::GetEnvironmentVariable("Path", "User")
if ([string]::IsNullOrEmpty($userPath)) {
[Environment]::SetEnvironmentVariable("Path", $installDir, "User")
} elseif ($userPath -notlike "*${installDir}*") {
[Environment]::SetEnvironmentVariable("Path", "$installDir;$userPath", "User")
}開啟一個新的終端機並執行 ai-i18n-tools --version。在所有平台上,指令名稱都是 ai-i18n-tools。
設定作用中提供者的 API 金鑰,與 npm 安裝相同(請參閱下方)。然後為專案選擇 init 範本並進行翻譯。Python 專案使用 -t ui-python。.NET 專案使用 -t ui-dotnet。已經使用 ResourceManager 或 IStringLocalizer 載入字串的應用程式使用 -t ui-dotnet-resx。執行一行 init:
# Python
ai-i18n-tools init -t ui-python -P cheaperinference
# .NET
# ai-i18n-tools init -t ui-dotnet -P cheaperinference
# .NET ResourceManager or IStringLocalizer
# ai-i18n-tools init -t ui-dotnet-resx -P cheaperinference
ai-i18n-tools suggest-models --apply
ai-i18n-tools sync僅將 init 用於新配置:它會覆寫選定的設定檔。對於現有專案,請改為編輯配置。sync 處理所有已配置/已啟用的翻譯管道,包括 UI 提取。
逐步解說:將 i18n 新增至 Python 應用程式、將 i18n 新增至 .NET 應用程式 以及 將 i18n 新增至 .NET ResourceManager 應用程式。指令參考:suggest-models。
設定 API 金鑰
翻譯指令 (translate-ui、translate-docs、translate-json、translate-svg、sync) 需要在 ai-i18n-tools.config.json 中設定供應商,並提供現用供應商的 API 金鑰。執行 ai-i18n-tools init -P <provider> 以建立該預設設定。供應商預設設定與 API 金鑰:LLM 供應商。init 中的模型清單是一個起點。請從 AI 模型 取得模型,並使用 suggest-models 或儀表板的 模型 索引標籤來取代它。Ollama 是唯一不需要 API 金鑰的內建預設設定。
設定與您傳遞給 init 的供應商相符的金鑰 (請參閱 預設設定表):
# init -P openrouter
export OPENROUTER_API_KEY=sk-or-v1-your-key-here
# init -P openai
# export OPENAI_API_KEY=sk-your-key-here或者在 ai-i18n-tools.config.json 旁邊建立一個 .env 或 .env.local 檔案。這些檔案僅在尚未設定提供者 API 金鑰時才會讀取:
OPENROUTER_API_KEY=sk-or-v1-your-key-here使用 CLI
將 ai-i18n-tools 作為依賴項或開發依賴項安裝到您的專案中(請參閱本頁頂部)。如果應用程式程式碼匯入 ai-i18n-tools/runtime,請確保它在生產運行時/建置環境中可用;全域 CLI 或獨立二進位檔無法滿足該匯入。該套件宣告了一個 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 項目,之後子目錄仍可正常運作;從巢狀資料夾重新執行 export 會失敗,因為 $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 解析至專案的依賴項目。
使用 ai-i18n-tools upgrade 升級現有安裝。此命令會印出新版本並等待 y。--yes 會跳過提示。專案依賴項會在 package.json 中更新,並使用 npm、pnpm、yarn 或 bun 進行安裝。全域 Node.js 安裝會使用該套件管理器的全域安裝。獨立可執行檔會在 SHA256 總和檢查碼相符後,替換為適用於目前作業系統和架構的 GitHub Release 版本。請參閱 升級。
package.json 指令碼 — 當 npm 或 pnpm 執行指令碼時,它會將 node_modules/.bin 加到 PATH 的開頭,因此,不需變更 shell 的 PATH,基本的指令名稱就能在指令碼中運作:
"scripts": {
"i18n:extract": "ai-i18n-tools extract",
"i18n:sync": "ai-i18n-tools sync",
"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>。
編碼代理程式技能
安裝 npm 套件或獨立可執行檔不會向代理程式註冊技能。安裝方法、原生目錄以及沒有技能資料夾的代理程式位於 編碼代理程式技能。
無需複製此儲存庫即可取得每個技能目錄,每個目錄都是一個包含 SKILL.md 的資料夾:
- Node.js 22.20 或更高版本:
npx skills add wsj-br/ai-i18n-tools --all -y會將這些目錄安裝到代理程式的技能資料夾中。 - 套件已安裝:將
node_modules/ai-i18n-tools/skills/.複製到該資料夾中。 - 沒有 Node.js:從 npm tarball 中提取
package/skills/,以獲取ai-i18n-tools --version中的版本。從新增該內容的發行版開始,該 GitHub 發行版上的ai-i18n-tools-skill.zip包含相同的目錄。在該 zip 檔之前發佈的發行版不包含它。第一個 zip 檔僅包含ai-i18n-tools/。
命令和代理程式資料夾位於 編碼代理程式技能。
已複製的 monorepo
從 ai-i18n-tools 的完整複製版本開發套件或執行工作區範例時:
- 工作區範例 (
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。此簽出版本的.envrc會將bin/新增至PATH,如此一來,在direnv allow之後,已提交的bin/ai-i18n-tools包裝器 (位於已發佈的bin/ai-i18n-tools.mjs填充碼旁) 即可讓您直接執行指令。若未使用 direnv,請使用node bin/ai-i18n-tools.mjs …、./bin/ai-i18n-tools …或根目錄的pnpm i18n:*指令碼 (或 shell 別名 /pnpm add -g .)。 - 獨立的 fixtures (
multi-provider、test-markdown) — 從 fixture 資料夾中,使用node ../../bin/ai-i18n-tools.mjs …。
變更 CLI 原始碼後,請在儲存庫根目錄執行 pnpm run build。請參閱開發指南以了解建置步驟與可選的全域安裝替代方案。
在 Linux、macOS 和 WSL 上,登錄檔安裝會自動為 CLI 指令碼設定可執行位元。在 Windows 上,套件管理器會產生 .cmd 和 .ps1 代理程式,明確叫用 Node。
下一步:快速入門。