快速入門
本頁指引單一語言專案產生其第一個翻譯檔案。它適用於 JS/TS 應用程式、Python 應用程式、.NET 應用程式、網站或文件網站,或儲存庫的 README 及其他 Markdown 檔案。本頁假設:
- Node.js
>=22.16.0,或適用於 Python 或 .NET 專案的獨立執行檔。 - LLM 供應商的 API 金鑰,或本機 Ollama 安裝。
- 專案位於版本控制中,以便您檢閱工具所寫的內容。
不同專案之間有兩點差異:工具如何尋找您的文字,以及您的應用程式如何載入結果。下方的選擇您的路徑會將您導向適合的指南。
可執行範例
偏好先查看已完成的專案嗎?您可以複製一個專案,而無需複製整個儲存庫:
npx degit wsj-br/ai-i18n-tools/examples/console-app console-app
cd console-app
pnpm install
pnpm run i18n:sync將 console-app 替換為任何其他 Node.js 範例。Python 和 .NET 範例沒有 package.json;請以相同方式複製它們。四個 Python 範例也位於 GitHub 發行版中的 ai-i18n-tools-python-examples.zip,而兩個 .NET 範例則位於 ai-i18n-tools-dotnet-examples.zip。包含每個範例所展示內容的完整清單,請參閱範例頁面。
安裝
pnpm add -D ai-i18n-toolsnpm install --save-dev ai-i18n-tools 和 yarn add --dev ai-i18n-tools 也適用。Python 和 .NET 專案會安裝獨立執行檔,且不需要 Node.js。Linux 和 macOS:curl -fsSL https://raw.githubusercontent.com/wsj-br/ai-i18n-tools/main/install.sh | bash。Windows PowerShell:irm https://raw.githubusercontent.com/wsj-br/ai-i18n-tools/main/install.ps1 | iex。其他安裝選項:安裝。
供應商與 API 金鑰
每個呼叫 LLM 的指令(translate-ui、translate-docs、translate-json、translate-svg 和 sync)都需要以下兩者:
- 在
ai-i18n-tools.config.json中至少有一個提供者:一個帶有translationModels的providers.<name>區塊,以及當設定了多個提供者時的一個頂層provider鍵。init -P <provider>會建立該預設設定的骨架。若要新增提供者,請參閱 LLM 提供者。若要選擇模型清單,請參閱 AI 模型。 - 您環境中相符的 API 金鑰,或當尚未設定任何提供者 API 金鑰時,在
ai-i18n-tools.config.json旁的.env/.env.local中。每個內建的預設設定都會從 預設設定表 讀取一個具名變數,例如OPENROUTER_API_KEY搭配-P openrouter或OPENAI_API_KEY搭配-P openai。Ollama 使用本機端點,且不需要金鑰。
export OPENROUTER_API_KEY=sk-or-v1-your-key-hereextract、status 及其他不呼叫 LLM 的指令則兩者皆不需要。關於環境檔案和 PATH 的更多資訊:安裝。
選擇您的路徑
找出您擁有的專案類型,執行其區塊中的指令,然後繼續閱讀連結的指南。
JS/TS 應用程式
您的按鈕和訊息在原始碼中仍是純文字,因此工具目前還找不到任何東西。必須先用 t() 將它們包裹起來,且應用程式需要一個小型的 i18next 設定檔。
ai-i18n-tools init -P openrouter
ai-i18n-tools suggest-models --apply接著請遵循為 JS/TS 應用程式新增 i18n 的說明。在執行 extract 和 translate-ui 之前,該指南會涵蓋包裹步驟,並提供一個代理提示。
Python 應用程式
ai-i18n-tools init -t ui-python -P openrouter
ai-i18n-tools suggest-models --applyDjango 應用程式、使用 Flask-Babel 目錄的 Flask,或已呼叫 gettext 的應用程式會保留這些呼叫。改為使用 ui-python-django、ui-python-flask 或 ui-python-gettext 建立骨架,然後遵循將 i18n 加入 Django / Python gettext 應用程式。
一個 .NET 應用程式
ai-i18n-tools init -t ui-dotnet -P openrouter
ai-i18n-tools suggest-models --apply然後依照 將 i18n 新增至 .NET 應用程式。已使用 ResourceManager 或 IStringLocalizer 的應用程式則改用 ui-dotnet-resx,然後 將 i18n 新增至 .NET ResourceManager 應用程式。migrate-dotnet-i18n 會將 T($"…") 重寫為編號的 {0} 呼叫。--wrap 會稽核未標記的 XAML 和 C# 標籤。報告會列出具名的 resx 索引鍵 (例如 Resources.LoginButton) 作為建議,但不會編輯這些行。
網站或文件站台
為您的框架挑選範本:
| 您的網站 | 範本 |
|---|---|
| Astro Starlight | ui-starlight |
| Docusaurus | ui-docusaurus |
| VitePress | ui-vitepress |
| Nextra | ui-nextra |
| Fumadocs | ui-fumadocs |
| 純 Astro 網站 | ui-astro-website |
| 純 HTML 頁面 | ui-plain-html 或 docs-plain-html |
ai-i18n-tools init -t ui-vitepress -P openrouter然後遵循將 i18n 加入網站或文件網站。它的代理提示會啟用框架的 i18n 路由。在審閱該工作後,您會執行 sync。
README 或 Markdown 文件
大多數儲存庫會希望將此與應用程式放在一起:預設的 ui-markdown 範本已包含一個扁平的 README 區塊。對於任何其他範本,請新增 --with-readme。僅包含 Markdown 的儲存庫則使用 docs-markdown。
ai-i18n-tools init -P openrouter
ai-i18n-tools init -t ui-python -P openrouter --with-readme
ai-i18n-tools init -t ui-dotnet -P openrouter --with-readme
ai-i18n-tools init -t docs-markdown -P openrouter然後依照 將 i18n 新增至您的 README 和 Markdown 文件。將語言清單標記貼到 sync 之前的 README.md 中。如果您有應用程式路徑,它仍然是 將 i18n 新增至 JS/TS 應用程式、將 i18n 新增至 Python 應用程式 或 將 i18n 新增至 .NET 應用程式。
其他項目
- 保持原樣的巢狀 i18next JSON:
ai-i18n-tools init -t ui-json-bundles -P openrouter,然後 JSON。 - 帶有文字標籤的 SVG 圖表:SVG 翻譯。
- 從 Intlayer 遷移:從 Intlayer 遷移。
- 保留 Intlayer 並僅填入其翻譯:就地翻譯 Intlayer。
完整的範本清單,包含所有 init 選項,可在 CLI 設定參考 中找到。
執行與檢查
當您的專案準備就緒時:
ai-i18n-tools doctor
ai-i18n-tools sync
ai-i18n-tools statusdoctor 會檢查設定、路徑、提供者和環境是否已準備就緒。除非您傳遞 --local,否則它也會與提供者驗證模型 ID。sync 會依序執行您的設定所啟用的每個步驟。status 會顯示每個地區設定已翻譯的內容。工具無法看到文字的專案首次執行時,會無錯誤地完成且不會寫入任何有用的內容,因此如果 status 沒有顯示任何字串,請返回您路徑的指南。
suggest-models 會根據已發佈的基準測試,對作用中提供者的聊天模型進行排名。suggest-models --apply 會取代 translationModels,並保留 uiModels 和 localeModels 不變。儀表板的 模型 標籤頁上也有相同的排名。關於排名如何運作,以及為何清單中包含多個模型,請參閱:AI 模型。指令參考:suggest-models。
保持翻譯更新
每當來源文字變更時,請重新執行 sync。SQLite 快取意味著只有新的或變更的文字會傳送至模型,因此重新執行成本低廉。在 CI 中執行 sync 可防止翻譯內容產生偏差。ai-i18n-tools dashboard 會開啟 翻譯儀表板 以檢閱和編輯快取的翻譯。
建議的 package.json 指令碼
在本機安裝套件後,指令碼會從 node_modules/.bin 解析 ai-i18n-tools,無需額外的 shell 設定。若要使用互動式 shell,請先設定 PATH:請參閱 使用 CLI。
{
"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:status": "ai-i18n-tools status",
"i18n:statistics": "ai-i18n-tools statistics",
"i18n:dashboard": "ai-i18n-tools dashboard",
"i18n:cleanup": "ai-i18n-tools cleanup"
}建議使用 sync,而非串連個別的翻譯指令碼。只有在需要單獨執行某個步驟時,才使用單一步驟的指令碼。
若要以另一種語言顯示 CLI 輸出和儀表板,請傳遞 -L <code> 或設定 AI_I18N_LANG:請參閱工具 UI 語言。
要同時翻譯多種類型的內容,例如應用程式字串和文件網站嗎?請參閱 結合管線。
下一步:請參閱 選擇您的路徑 下適合您路徑的指南。