Nextra 整合

使用 init -t ui-nextra 和 docsOutput.style: "nextra" 為基於 Next.js App Router 的 Nextra 4 文件網站提供支援。此預設集是 doc-system 的別名，具有空的 localeSubpath 並保留 BCP-47 地區資料夾名稱（localePathLowercase 預設為 false，因此資料夾保持為 pt-BR、zh-Hans 等）。

另請參閱文件，以及可執行的 examples/nextra-docs 示範。

快速開始

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

翻譯頁面內容、_meta.ts 側邊欄標籤及主題詞典模組時，在單一 sync 執行作業中啟用 features.translateDocs。

頁面版面

Nextra 4 搭配 i18n 會將 英文來源 MDX 置於語言資料夾 中（通常為 content/en/）。翻譯副本會寫入同層級的語言資料夾：

content/en/index.mdx              →  content/pt-BR/index.mdx
content/en/guide/getting-started.mdx  →  content/zh-Hans/guide/getting-started.mdx

設定一個 docs[] 區塊：

{
  "contentPaths": ["content/en"],
  "outputDir": "content",
  "docsOutput": {
    "style": "nextra",
    "docsRoot": "content/en",
    "rewriteNextraLinks": true
  }
}

將 contentPaths 指向您的英文 .mdx 檔案和目錄。將 docsRoot 設為 content/ 內的英文地區資料夾。

連接 Nextra 國際化：在 next.config 中設定 i18n.locales 和 defaultLocale，並讓 targetLocales 在 ai-i18n-tools.config.json 中與這些地區代碼和 content/{locale}/ 資料夾名稱保持一致。

主題字串

Nextra 主題介面（editLink、搜尋佔位符、頁尾等）不會從 Markdown 中擷取。在 TypeScript 字典模組中編寫英文字串（例如 app/_dictionaries/en.ts），然後在 translate-docs 內進行翻譯：

{
  "features": {
    "translateDocs": true
  },
  "docs": [
    {
      "contentPaths": ["content/en"],
      "outputDir": "content",
      "nextraDictionaryPath": "app/_dictionaries/en.ts",
      "docsOutput": {
        "style": "nextra",
        "docsRoot": "content/en"
      }
    }
  ]
}

工具會寫入 app/_dictionaries/{locale}.ts（預設範本：{dir}/{locale}.ts）。在 app/_dictionaries/get-dictionary.ts 中載入每個地區的模組，並將翻譯後的字串傳遞給 <Layout>、<Search>、<Footer> 及相關主題元件。

請勿 將 json[] 用於 Nextra 主題字典字串——該模式僅適用於不相關的應用程式地區套件。

側邊欄標籤 (_meta.ts)

Nextra 3+ 使用 TypeScript _meta.ts / _meta.tsx 檔案來處理側邊欄結構和標題。當 docsOutput.style 為 "nextra" 時，translate-docs 會自動收集 docsRoot 下的 _meta.ts、_meta.tsx 和 _meta.js，翻譯 export default { … } 中繼地圖中的字串常值，並將鏡像檔案寫入 content/{locale}/**。

建議的模式： 將英文常值保留在 content/en/**/_meta.ts 內（與 swr-site 相同）：

content/en/_meta.ts           English sidebar labels (source)
content/pt-BR/_meta.ts        Translated copy (generated by translate-docs)

選用：使用 docs[].nextraMetaGlob 覆寫收集，或使用 docs[].nextraMetaTranslatableKeys 限制可翻譯的屬性名稱（預設：title、display、breadcrumb）。

請勿 手動編寫 JSON 側邊檔案（i18n/meta.en.json）或匯入翻譯 JSON 的精簡 _meta.ts 檔案——當英文變更時，使用 sync / translate-docs 重新產生地區 _meta 檔案。

範例專案

examples/nextra-docs — 英文來源位於 content/en/，已提交 pt-BR 和 zh-Hans 頁面樹、內嵌 _meta.ts 檔案及 app/_dictionaries/{locale}.ts。在連接埠 3070 上執行 pnpm run dev。

選用：t() 適用於 app/ React（混合）

預設： _meta.ts / _meta.tsx 物件字面量字串會在 translate-docs 內被翻譯 — 不需要 t()。

選用的混合模式： 團隊可以額外使用 t() + translate-ui 來處理 app/ 版面裝飾、自訂 MDX 元件，或僅存在於 JSX 元件主體中的 _meta.tsx 標籤（超越 v1 中的物件字面量萃取）。這 不會 取代 meta 檔案的 translate-meta，除非您明確地將側邊欄標籤重構為元件。

內容	預設管線	選用替代方案
MDX 頁面主體	translate-docs	—
_meta.ts / _meta.tsx 物件標題	translate-docs	重構為 JSX 中的 t()（混合模式）
app/ 版面、_components/	nextraDictionaryPath + 字典 .ts	t() + translate-ui

AI 代理程式提示範例（在將版面裝飾遷移至 t() 時複製到 Cursor 或其他編碼代理程式）：

Add i18n to our Nextra 4 app/ layout using ai-i18n-tools translate-ui (optional hybrid).

Context:
- We already translate MDX pages and _meta.ts via translate-docs (default).
- We want t() in app/[lang]/layout.tsx and app/_components/ for labels not covered by nextraDictionaryPath.
- English-as-key: t("Edit this page on GitHub") in source; strings.json + locales/{locale}.json from extract + translate-ui.
- Do not move _meta.ts sidebar labels into t() unless we explicitly ask — translate-docs handles _meta object literals.

Requirements:
1. Wire getRequestConfig / i18n provider for the app router locale param.
2. Replace hard-coded layout strings with t() calls; keep structure and Nextra theme APIs unchanged.
3. Enable features.translateUIStrings, set ui.sourceRoots to app/ (and mdx-components if needed).
4. Do not duplicate dictionary.ts strings that nextraDictionaryPath already translates — pick one approach per string.

After editing: run extract, translate-ui (or sync), verify en + one target locale in dev.

連結慣例

Nextra 透過 Next.js i18n（/guide/getting-started、/pt-BR/guide/getting-started）提供地區前置詞路由。頁面內連結應保持地區中立（/guide/getting-started），讓 Next.js 自動附加目前的地區前置詞。

啟用內建正規化器，讓 translate-docs 自動修正每個翻譯檔案中的連結：

"docsOutput": {
  "style": "nextra",
  "docsRoot": "content/en",
  "rewriteNextraLinks": true
}

當 style 為 "nextra" 時，rewriteNextraLinks 預設為啟用。

英文來源中的作者	正規化器處理後
[Guide](content/en/guide/getting-started.mdx)	[Guide](/zh-Hant/guide/getting-started)
[Guide](/zh-Hant/guide/getting-started.mdx)	[Guide](/zh-Hant/guide/getting-started)
[Demo](https://github.com/org/repo)	不變（完整 URL）

撰寫規則

• 跨頁面文件連結：在英文 MDX 中使用 地區中立網站路由（/guide/…），或使用 content/en/… / 相對 .mdx 路徑，讓正規化器在 sync 期間重寫它們。
• 內容樹外部的 Repo 檔案：使用 完整 URL。
• 請勿 手動編輯 content/<locale>/ 中的連結 — 使用 sync / translate-docs 重新產生。

選用地區代理程式

Nextra 為 i18n 網站提供地區偵測代理程式。從專案根目錄的 proxy.ts 匯出：

export { proxy } from 'nextra/locales'

export const config = {
  matcher: [
    '/((?!api|_next/static|_next/image|favicon.ico|icon.svg|apple-icon.png|manifest|_pagefind).*)',
  ],
}

網站地區代碼與 sourceLocale： Nextra 和 Next.js 在 next.config、content/{locale}/ 和 NEXT_LOCALE cookie 中使用短路由代碼（en、pt-BR、zh-Hans）。ai-i18n-tools.config.json 中的 sourceLocale 可以是 BCP-47 標籤，例如 en-GB，用於翻譯品質 — 該標籤 不是 網站路由。如果瀏覽器 cookie 或 Accept-Language 解析為 i18n.locales 外部的標籤（例如當只設定 en 時的 en-GB），Nextra 的現成代理程式可能會在重新導向中循環。examples/nextra-docs 範例包裝了 nextra/locales，在委派前將無效的 cookie 和路徑重設為預設網站地區。

這不適用於 output: 'export' 靜態匯出。請參閱 Nextra i18n 文件。

另請參閱 設定 — docsOutput 和 輸出版面配置。