為網站或文件網站新增 i18n
本頁面適用於單一語言的文件網站 (Markdown 或 MDX) 或行銷與靜態網站 (Astro 網站或純 HTML)。此工具會使用您 LLM 供應商的模型來翻譯您的頁面內容，並為每種語言寫入一份本地化副本。您的網站框架負責提供這些副本及語言切換器。
若應用程式的 UI 字串存於 t() 呼叫中，請改用 為 JS/TS 應用程式新增 i18n 或 為 Python 應用程式新增 i18n。
您的情況是？
| 你的網站 | 初始化範本 | 從這裡開始 |
|---|---|---|
| Astro Starlight 或純 Astro | ui-starlight / 混合 UI 字串 | Astro |
| Docusaurus | ui-docusaurus | Docusaurus |
| VitePress | ui-vitepress | VitePress |
| Nextra 4 (Next.js App Router) | ui-nextra | Nextra |
| Fumadocs 4 (Next.js App Router) | ui-fumadocs | Fumadocs |
| 純 HTML 頁面 | ui-plain-html 或 docs-plain-html | 純 HTML 應用程式 |
| 沒有網站框架，只有 README 和 Markdown 檔案 | docs-markdown，或任何範本加上 --with-readme | 為您的 README 和 Markdown 文件新增 i18n |
Agent 提示
步驟
每個框架的作法大同小異；詳細資訊請見上方連結的框架指南。
- 安裝 CLI 並設定 API 金鑰：安裝、供應商與 API 金鑰。
- 建立骨架：
ai-i18n-tools init -t <template> -P <provider>。 - 設定
sourceLocale、targetLocales和docs[].contentPaths（以您的來源語言撰寫的頁面和資料夾）。sourceLocale可以是任何語言。框架指南會顯示正確的docsOutput.style。 - 啟用您框架自己的 i18n，以便它提供並連結本地化頁面。每個指南都有一個「在現有網站中啟用 i18n」的章節：VitePress、Docusaurus、Nextra、Fumadocs、Astro。
- 執行
ai-i18n-tools sync（或translate-docs），然後建置網站。 - 在瀏覽器中檢查本地化路由。框架自己的語系下拉式選單就是切換器。對於像 README 這樣的單一 markdown 檔案，請使用 languageListBlock 新增一個連結列。
翻譯的內容
頁面主體一律會通過 文件 管線處理。框架外觀（導覽、側邊欄、佈景主題標籤）會在框架支援的情況下，於同一次執行中處理，而不是透過獨立的 JSON 管線。
| 框架 | Shell 和佈景主題字串 | 方法 |
|---|---|---|
| Docusaurus | write-translations 目錄 ({ message, description }) | docs[].docusaurusCatalogDir 加上 translate-docs |
| VitePress | 佈景主題、導覽和側邊欄目錄 | docsOutput.vitepressThemeCatalog 加上 translate-docs |
| Nextra | _meta.ts 側邊欄標籤 | 使用 style: "nextra" 自動處理 |
| Nextra | 佈景主題字典 .ts | docs[].nextraDictionaryPath |
| Fumadocs | meta.json 側邊欄標籤 | 使用 style: "fumadocs" 自動處理 |
| Fumadocs | UI 覆寫目錄 | docsOutput.fumadocsUiCatalog |
| Astro Starlight | 內建多種語系的 UI 字串 | 僅限頁面 |
translate-docs 不會翻譯圖片與螢幕擷取畫面。關於特定語系的檔案，請參閱圖片與螢幕擷取畫面。
純 HTML
有兩種選項，取決於頁面的應有行為：
- 在瀏覽器中切換語言的單一頁面：使用
data-i18n*屬性標記文字，並使用 UI 字串執行階段 (ui-plain-html)。請參閱純 HTML 應用程式。 - 每個語系一個已翻譯的 HTML 檔案：使用文件管線 (
docs-plain-html)。請參閱HTML 頁面。
一個檔案屬於一個路徑。
情況不同？
- 應用程式 UI 字串：為 JS/TS 應用程式新增 i18n 或 為 Python 應用程式新增 i18n。
- 網站旁的儲存庫 README，或沒有網站框架的 Markdown 檔案：為您的 README 與 Markdown 文件新增 i18n。
init … --with-readme會在網站範本旁新增該區塊。 - 獨立的巢狀語系 JSON：JSON。
- 同時翻譯網站與應用程式字串：結合管線。
關於共用選項與各框架差異的參考資料：整合。