為您的專案新增 i18n
本節為一系列逐步教學，適用於目前僅支援單一語言的專案。請從這裡開始。下方的每個頁面都會介紹一種專案類型，從設定到產出第一個翻譯檔案的完整過程。開始使用 頁面涵蓋了此工具的用途、安裝選項，以及供應商和模型。您可以開啟任一逐步教學，而無須先閱讀這些頁面。
您與工具的分工
| 您 | 工具 |
|---|---|
| 挑選要試用的語言、供應商和模型 | 擷取文字、進行翻譯、檢查結果，並寫入目錄或頁面 |
讓工具能看見文字：在應用程式碼中使用 t()、您網站框架的 i18n，或是在 README 中使用語言列表標記 | 快取每次翻譯，並在下次執行時重複使用 |
| 載入檔案並檢查其中一種語言 | 顯示進度，並讓您在 翻譯儀表板 中檢閱用字 |
逐步教學會說明哪些原始碼編輯需要由您完成。對於那些機械式的編輯，我們也提供了編碼代理提示。CLI 會寫入字詞庫和翻譯檔案。它不會安裝 i18next 或您網站框架的 i18n。
共通設定
每個逐步教學都遵循相同的順序。您所選的頁面會提供詳細資訊。
- 安裝 CLI 並設定您的供應商 API 金鑰。Ollama 不需要金鑰。請參閱 安裝 和 供應商與 API 金鑰。
- 使用該頁面指定的範本執行
init。這會寫入ai-i18n-tools.config.json。 - 準備專案，讓工具能看見文字。
- 執行
ai-i18n-tools sync，然後執行ai-i18n-tools status。 - 載入輸出，檢查一個目標語言，並在來源變更時重新執行
sync。快取只會將新增或變更的文字傳送給模型。
本節頁面
| 您的專案類型 | 頁面 | 該頁面涵蓋內容 |
|---|---|---|
| 一個 JS/TS 應用程式 (React、Next.js、Node、CLI)，其按鈕和訊息仍為純文字 | 為 JS/TS 應用程式新增 i18n | 安裝 i18next、新增啟動程式碼、用 t() 包裝字面值，然後執行 extract 和 translate-ui |
| 一個 Python 應用程式 (Streamlit、FastAPI、Flask、Django、gettext) | 為 Python 應用程式新增 i18n | 使用 t() 或 _() 包裝，或保留 GNU gettext。CLI 可透過獨立可執行檔執行，無需安裝 Node.js |
| 一個文件或行銷網站 (VitePress、Starlight、Docusaurus、Nextra、Fumadocs、Astro、純 HTML) | 為網站或文件站新增 i18n | 啟用框架自身的語言路由，然後翻譯頁面和主題標籤 |
| 一個儲存庫 README 和其他 Markdown 檔案，通常與應用程式放在一起 | 為您的 README 和 Markdown 文件新增 i18n | 每種語言一個檔案 (translated-docs/README.de.md)，並在 README 中加入一個語言列。init --with-readme 會將該區塊新增至任何範本 |
| 一個儲存庫中包含上述多種類型 | 結合管線 | 一個設定檔和一個 sync。常見的組合是應用程式 UI 字串加上 README |
| Intlayer 字典，且您想保留 Intlayer | 原地翻譯 Intlayer | translate-intlayer 會填補 *.content.ts 內遺失和過時的葉節點 |
| Intlayer 字典，且您正要從 Intlayer 遷移 | 從 Intlayer 遷移 | migrate-intlayer 會從字典植入字詞庫，並將安全的呼叫點重寫為 t() |
同時擁有 README 的應用程式，會同時使用應用程式頁面和 README 頁面。同時擁有 README 的網站，則會使用網站頁面，並透過 init … --with-readme 處理 README 區塊。
深入了解
逐步教學在串接好第一種語言後即告一段落。接下來的內容請參閱參考頁面：