Skip to content

快速入門 ​

本頁指引單一語言專案產生其第一個翻譯檔案。它適用於 JS/TS 應用程式、Python 應用程式、.NET 應用程式、網站或文件網站,或儲存庫的 README 及其他 Markdown 檔案。本頁假設:

  • Node.js >=22.16.0,或適用於 Python 或 .NET 專案的獨立執行檔。
  • LLM 供應商的 API 金鑰,或本機 Ollama 安裝。
  • 專案位於版本控制中,以便您檢閱工具所寫的內容。

不同專案之間有兩點差異:工具如何尋找您的文字,以及您的應用程式如何載入結果。下方的選擇您的路徑會將您導向適合的指南。

可執行範例 ​

偏好先查看已完成的專案嗎?您可以複製一個專案,而無需複製整個儲存庫:

bash
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。包含每個範例所展示內容的完整清單,請參閱範例頁面。

安裝 ​

bash
pnpm add -D ai-i18n-tools

npm 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)都需要以下兩者:

  1. 在 ai-i18n-tools.config.json 中至少有一個提供者:一個帶有 translationModels 的 providers.<name> 區塊,以及當設定了多個提供者時的一個頂層 provider 鍵。init -P <provider> 會建立該預設設定的骨架。若要新增提供者,請參閱 LLM 提供者。若要選擇模型清單,請參閱 AI 模型。
  2. 您環境中相符的 API 金鑰,或當尚未設定任何提供者 API 金鑰時,在 ai-i18n-tools.config.json 旁的 .env / .env.local 中。每個內建的預設設定都會從 預設設定表 讀取一個具名變數,例如 OPENROUTER_API_KEY 搭配 -P openrouter 或 OPENAI_API_KEY 搭配 -P openai。Ollama 使用本機端點,且不需要金鑰。
bash
export OPENROUTER_API_KEY=sk-or-v1-your-key-here

extract、status 及其他不呼叫 LLM 的指令則兩者皆不需要。關於環境檔案和 PATH 的更多資訊:安裝。

選擇您的路徑 ​

找出您擁有的專案類型,執行其區塊中的指令,然後繼續閱讀連結的指南。

JS/TS 應用程式 ​

您的按鈕和訊息在原始碼中仍是純文字,因此工具目前還找不到任何東西。必須先用 t() 將它們包裹起來,且應用程式需要一個小型的 i18next 設定檔。

bash
ai-i18n-tools init -P openrouter
ai-i18n-tools suggest-models --apply

接著請遵循為 JS/TS 應用程式新增 i18n 的說明。在執行 extract 和 translate-ui 之前,該指南會涵蓋包裹步驟,並提供一個代理提示。

Python 應用程式 ​

bash
ai-i18n-tools init -t ui-python -P openrouter
ai-i18n-tools suggest-models --apply

然後遵循將 i18n 加入 Python 應用程式。

Django 應用程式、使用 Flask-Babel 目錄的 Flask,或已呼叫 gettext 的應用程式會保留這些呼叫。改為使用 ui-python-django、ui-python-flask 或 ui-python-gettext 建立骨架,然後遵循將 i18n 加入 Django / Python gettext 應用程式。

一個 .NET 應用程式 ​

bash
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 Starlightui-starlight
Docusaurusui-docusaurus
VitePressui-vitepress
Nextraui-nextra
Fumadocsui-fumadocs
純 Astro 網站ui-astro-website
純 HTML 頁面ui-plain-html 或 docs-plain-html
bash
ai-i18n-tools init -t ui-vitepress -P openrouter

然後遵循將 i18n 加入網站或文件網站。它的代理提示會啟用框架的 i18n 路由。在審閱該工作後,您會執行 sync。

README 或 Markdown 文件 ​

大多數儲存庫會希望將此與應用程式放在一起:預設的 ui-markdown 範本已包含一個扁平的 README 區塊。對於任何其他範本,請新增 --with-readme。僅包含 Markdown 的儲存庫則使用 docs-markdown。

bash
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 應用程式。

其他項目 ​

完整的範本清單,包含所有 init 選項,可在 CLI 設定參考 中找到。

執行與檢查 ​

當您的專案準備就緒時:

bash
ai-i18n-tools doctor
ai-i18n-tools sync
ai-i18n-tools status

doctor 會檢查設定、路徑、提供者和環境是否已準備就緒。除非您傳遞 --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。

json
{
  "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 語言。

要同時翻譯多種類型的內容,例如應用程式字串和文件網站嗎?請參閱 結合管線。

下一步:請參閱 選擇您的路徑 下適合您路徑的指南。

採用 MIT 授權條款釋出。