Astro 整合

ai-i18n-tools 可與 Astro 搭配使用，有兩種常見設定：Astro Starlight 文件網站和純 Astro 行銷或應用程式網站。兩者都使用文件 (translate-docs) 作為頁面內容；純 Astro 網站通常將其與 UI 字串 (extract / translate-ui) 結合，用於 frontmatter 和共享資料中的 t() 字串。

另請參閱使用者介面字串、文件以及下面的可執行範例。

Astro Starlight

將 init -t ui-starlight 和 docsOutput.style: "astro-starlight" 用於 Astro Starlight 文件網站。預設值是 doc-system 的別名，帶有空的 localeSubpath — 翻譯頁面會落在英文原始碼樹旁的 src/content/docs/<locale>/ 下。

快速入門

ai-i18n-tools init -t ui-starlight [-P <provider>]
# edit ai-i18n-tools.config.json (targetLocales, providers, contentPaths)
pnpm run i18n:sync   # or: ai-i18n-tools sync
pnpm dev             # Starlight dev server (project-specific script)

頁面佈局

英文 Markdown 和 MDX 位於 Starlight 內容根目錄（通常是 src/content/docs/）。翻譯副本寫在原始碼樹旁：

src/content/docs/quick-start.md     →  src/content/docs/de/quick-start.md
src/content/docs/guide/setup.mdx    →  src/content/docs/fr/guide/setup.mdx

設定一個 docs[] 區塊：

{
  "contentPaths": ["src/content/docs/"],
  "outputDir": "src/content/docs",
  "docsOutput": {
    "style": "astro-starlight",
    "docsRoot": "src/content/docs"
  }
}

將 contentPaths 指向您的英文 .md / .mdx 檔案和目錄。將 docsRoot 設定為 Starlight 用作其內容根目錄的相同資料夾。

Starlight UI 覆寫可以在需要時於獨立的 docs[] 區塊中使用 src/content/i18n/en.json 搭配 jsonPathTemplate — 請參閱文件 — 初始化文件。

Starlight 內建了許多地區設定的 UI 字串（導覽標籤、搜尋預留位置、目錄等等）。沒有單獨的 shell/主題管線需要設定 — 僅將 translate-docs 用於頁面內容。至於其他框架，請參閱框架 shell 翻譯。

範例專案

examples/astro-docs — 英文原始碼位於 src/content/docs/，已提交的翻譯位於 src/content/docs/<locale>/，RTL 語系 (ar)，以及詞彙表驅動的翻譯。在連接埠 3050 上執行 pnpm dev。

純 Astro（行銷和應用程式網站）

對於靜態 Astro 行銷或應用程式網站（非 Starlight），請將 Astro 內建的 i18n 路由 與 ai-i18n-tools 結合使用。參考實作是 examples/astro-website：英文位於 /，目標語系位於 /{locale}/。

大多數團隊在同一頁面上使用兩種管道的混合：

管道	用途	命令	輸出
頁面 HTML	範本主體中的標題、段落、導覽標籤、內嵌陣列	translate-docs	每種語言 src/pages/{locale}/index.astro
UI 字串 (t())	前端資料、索引標籤、共用陣列	extract → translate-ui	public/locales/{locale}.json（以英文來源為鍵）

快速入門

ai-i18n-tools init -t ui-astro-website [-P <provider>]
# enable features.translateDocs and add a docs[] block for page HTML (see below)
pnpm run i18n:sync
pnpm dev

使用 init -t ui-astro-website 建立 UI 提取，然後在您也翻譯頁面 HTML 時合併 docs[] 區塊：

{
  "features": {
    "translateUIStrings": true,
    "translateDocs": true
  },
  "ui": {
    "sourceRoots": ["src/"],
    "stringsJson": "public/locales/strings.json",
    "flatOutputDir": "public/locales/"
  },
  "docs": [{
    "contentPaths": ["src/pages/index.astro"],
    "outputDir": "src/pages",
    "docsOutput": {
      "style": "astro-starlight",
      "docsRoot": "src/pages"
    },
    "addFrontmatter": false
  }]
}

當您新增或移除語言時，請保持三個清單對齊：targetLocales 在 ai-i18n-tools.config.json 中，i18n.locales 在 astro.config.mjs 中（Astro 使用 小寫 路由代碼，例如 pt-br），以及 ui-languages.json（透過 generate-ui-languages）。扁平化套件檔案名稱使用配置大小寫 (pt-BR.json)；透過您的清單 code 欄位將 Astro 的 pt-br 路由映射到該檔案。

透過查找英文原始字面量作為鍵，在建置時解析 t('…') — 請參閱 examples/astro-website/src/i18n/t.ts。除非您新增在載入後切換語言的客戶端島嶼，否則靜態網站不需要 ai-i18n-tools/runtime 或 i18next。

範例專案

examples/astro-website — 混合登陸頁面，透過 translate-docs 呈現 HTML，並透過 t() + translate-ui 呈現螢幕截圖標籤。

專案範例

專案	用例	連接埠
examples/astro-docs	Starlight 文件	3050
examples/astro-website	純 Astro 行銷網站 (HTML + t() 混合)	(請參閱 README)

比較 examples/astro-docs 與 examples/docusaurus-docs —— 教學內容相似，但輸出風格為 Docusaurus 而非 Starlight。