Skip to content

Fumadocs 整合 ​

在 Next.js App Router 上的 Fumadocs 4 文件網站使用 init -t ui-fumadocs 與 docsOutput.style: "fumadocs"。此預設為 doc-system 的別名,帶有空白的 localeSubpath 並保留 BCP-47 或短地區代碼(localePathLowercase 預設為 false)。

另請參閱文件及可執行的 examples/fumadocs-docs 範例(dot 解析器,連接埠 3080)。

快速開始 ​

bash
ai-i18n-tools init -t ui-fumadocs -P groq
# 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)

當您要在單次 sync 執行中翻譯頁面內容、meta.json 側邊欄標籤及 Fumadocs UI 覆寫時,請啟用 features.translateDocs。

頁面版面 ​

Fumadocs 透過 docsOutput.fumadocsParser 支援兩種 i18n 內容佈局。dot 解析器為預設值(Fumadocs 內建及如 SWR 等正式網站所使用)。

Dot 解析器(預設) ​

英文 MDX 檔案位於集合根目錄。翻譯副本在同一目錄中使用地區代碼後綴:

text
content/docs/index.mdx                    →  content/docs/index.pt.mdx
content/docs/guide/getting-started.mdx    →  content/docs/guide/getting-started.zh.mdx
json
{
  "contentPaths": ["content/docs"],
  "outputDir": "content/docs",
  "docsOutput": {
    "style": "fumadocs",
    "docsRoot": "content/docs",
    "fumadocsParser": "dot",
    "rewriteFumadocsLinks": true
  }
}

在 lib/i18n.ts 中將 targetLocales 與 defineI18n().languages 精確對齊(範例使用短代碼 pt 與 zh)。

在現有網站中啟用 i18n ​

僅限英文的 Fumadocs 應用程式需要一個地區設定路由和 defineI18n,然後 translate-docs 才能寫入同級檔案。首次設定會使用 在網站或文件網站中新增 i18n 上的提示。此頁面上的 代理程式提示 是連接 UI 目錄的後續步驟。清單:

  • 在 lib/i18n.ts 中設定 defineI18n,並使用 languages、defaultLanguage 以及 parser: "dot" 或 "dir"。
  • 從 proxy.ts(範例檔案)中 app/[lang]/ 路由和 createI18nMiddleware。
  • 在 lib/layout.shared.ts 中設定 i18n.translations(),並將其傳遞給 i18nProvider。
  • 英文 MDX 檔案位於集合根目錄(點)或 content/docs/en/(目錄)底下。
  • targetLocales 等於 languages 減去預設語言,然後 sync。

Dir 解析器(Nextra 風格) ​

對於習慣使用地區資料夾的團隊(content/docs/en/ → content/docs/pt-BR/),將 fumadocsParser 設定為 "dir":

text
content/docs/en/index.mdx           →  content/docs/pt-BR/index.mdx
content/docs/en/guide/foo.mdx       →  content/docs/zh-Hans/guide/foo.mdx
json
{
  "contentPaths": ["content/docs/en"],
  "outputDir": "content/docs",
  "docsOutput": {
    "style": "fumadocs",
    "docsRoot": "content/docs/en",
    "fumadocsParser": "dir",
    "rewriteFumadocsLinks": true
  }
}

請參閱 examples/fumadocs-docs 中的 ai-i18n-tools.config.dir.example.json 以取得可複製貼上的目錄設定。心智模型與 Nextra 整合 相符。

側邊欄(meta.json) ​

Fumadocs 使用 JSON meta.json 檔案來定義側邊欄結構和標題。當 docsOutput.style 為 "fumadocs" 時,translate-docs 會在 docsRoot (或 docs[].fumadocsMetaGlob) 下收集 meta.json,翻譯 docs[].fumadocsMetaTranslatableKeys 中列出的鍵的字串值 (預設值:title、description),並寫入地區設定輸出:

解析器來源語系輸出
dotcontent/docs/**/meta.jsoncontent/docs/**/meta.{locale}.json
dircontent/docs/en/**/meta.jsoncontent/docs/{locale}/**/meta.json

切勿翻譯 pages slug 陣列、root、icon、defaultOpen 或其他結構性鍵值——僅翻譯供人類閱讀的標籤。

UI 目錄 ​

Fumadocs 佈局介面字串(搜尋佔位符、地區設定顯示名稱,以及 lib/layout.shared.ts 中的其他 defineTranslations / i18n.translations() 覆寫)未從 Markdown 中提取。請設定 docsOutput.fumadocsUiCatalog,以便 translate-docs 從 sourcePath 啟動來源地區設定目錄,並翻譯每個地區設定的 JSON:

json
{
  "features": {
    "translateDocs": true
  },
  "docs": [
    {
      "contentPaths": ["content/docs"],
      "outputDir": "content/docs",
      "docsOutput": {
        "style": "fumadocs",
        "docsRoot": "content/docs",
        "fumadocsParser": "dot",
        "fumadocsUiCatalog": {
          "sourcePath": "lib/layout.shared.ts",
          "catalogPath": "lib/i18n/ui.en.json"
        }
      }
    }
  ]
}
  • catalogPath — 英文平面 JSON。啟動程序只會讀取 sourcePath 中 .add({ … }) 的 en 物件。該物件中的字串常值會成為目錄鍵 (displayName、Search(search trigger))。.add() 只接受 Fumadocs UI 預設集註冊的鍵,因此像 site.title 這樣的導覽標題不能放在那裡。範例將 site.title 保留在 JSON 中,並讀取 catalog["site.title"] 以取得 nav.title。檔案中已存在但 en 物件中不存在的鍵會保留:合併為 { ...existing, ...extracted }。當英文常值變更時,請重新執行 sync。
  • outputPathTemplate (選用) — 每個地區設定的輸出;預設值:ui.{locale}.json 位於 catalogPath 旁邊。

在應用程式讀取已翻譯的鍵值前,它不會有任何作用。i18n.translations().get(lang) 只會傳回向 .extend() (Fumadocs UI 預設集) 註冊的鍵值。將語系目錄展開至 .add() 中,這樣這些鍵值才會生效,並將原生的 displayName 放在展開運算 之後,這樣英文名稱的翻譯才不會取代它:

ts
"pt-BR": {
  ...loadUiCatalog("pt-BR"),
  displayName: "Português (Brasil)",
},

site.title 不是 Fumadocs UI 鍵值。範例會為 nav.title 從目錄中讀取它。一個只存在於 ui.pt-BR.json 中的搜尋標籤會保留在內建的預設集上,直到該展開運算(或其他讀取操作)使用它為止。

請參閱 examples/fumadocs-docs/lib/layout.shared.ts。

標準地區設定可由 @fumadocs/language/* 預設集涵蓋而無需 LLM 成本;目錄僅翻譯英文區塊中的 專案覆寫。

代理提示 ​

當僅限英文的 Fumadocs 網站需要增加語系時,請複製此內容。它會連接路由和 UI 目錄,但不會翻譯字串。

UI 目錄提示
markdown
# Enable Fumadocs i18n and the UI catalog

## Context

ai-i18n-tools translates Fumadocs MDX, `meta.json` titles, and the English block
of `i18n.translations().add({ en: { … } })` via `translate-docs` and
`docsOutput.fumadocsUiCatalog`. The literal in that `en` object is the source
string. Locale JSON takes effect only for keys the app reads: either a catalog
spread into `.add()` for registered UI keys, or a direct read such as
`catalog["site.title"]` for the nav title. Do not translate any string.

Reference:
https://github.com/wsj-br/ai-i18n-tools/tree/main/examples/fumadocs-docs

## Scope

Edit `lib/i18n.ts`, `lib/layout.shared.ts`, `proxy.ts`, `app/[lang]/` routes,
and `ai-i18n-tools.config.json`. Skip URLs, slugs, and native language names
(`displayName` on each locale entry).

## Call shape

- `defineI18n({ languages, defaultLanguage, parser })`. Use `"dot"` unless the
  project already keeps English under a locale folder (`"dir"`).
- `export default createI18nMiddleware(i18n)` from `proxy.ts`.
- Move pages under `app/[lang]/…` and pass `lang` into `baseOptions` and
  `i18nProvider(translations, lang)`.
- In `lib/layout.shared.ts`, keep English UI overrides as string literals inside
  `.add({ en: { … } })`. For each other locale, spread `loadUiCatalog(locale)`
  and then set `displayName` to the native name.
- Config: `features.translateDocs`, `docsOutput.style: "fumadocs"`,
  `fumadocsParser` matching `defineI18n`, and `fumadocsUiCatalog.sourcePath`
  pointing at `lib/layout.shared.ts`. `targetLocales` must equal `languages`
  except the default language, character for character.

## Order

1. Routing and `defineI18n`.
2. English literals in the `en` block, and the catalog spread for other locales.
3. Ask the user to run `sync`. Do not hand-write `ui.<locale>.json` or
   translated MDX.

## Do not

- Do not translate, rename, or reword the English literals.
- Do not put native language names only in the `en` block (they would be
  extracted and translated).
- Do not hand-edit locale JSON, `meta.<locale>.json`, or locale MDX.
- Do not use `json[]` for this catalog.

## Verify

- `pnpm build` passes.
- The default locale still shows the English overrides.
- After `sync`, one other locale shows the translated search trigger and nav
  title, and `displayName` in the language menu is still the native name.

## Report back

List files changed, each key you added to the `en` block, each key you left
unread (and so unused) with a one-line reason, and whether the parser is `dot`
or `dir`.

請勿 將 json[] 用於 Fumadocs UI 字串 — 該管線適用於不相關的應用程式地區設定套件。

連結慣例 ​

Fumadocs 透過 Next.js 中介軟體提供語言前綴路由(/docs/getting-started、/pt/docs/getting-started)。頁內連結應保持語言中立(/docs/getting-started),以便自動套用當前語言前綴。

啟用內建的標準化工具,讓 translate-docs 自動修正每個翻譯檔案中的連結:

json
"docsOutput": {
  "style": "fumadocs",
  "docsRoot": "content/docs",
  "rewriteFumadocsLinks": true
}

當 style 為 "fumadocs" 時,rewriteFumadocsLinks 預設為啟用。

在來源地區設定中撰寫正規化器之後
[Guide](content/docs/guide/getting-started.mdx)[Guide](/docs/guide/getting-started)
[Home](content/docs/index.mdx)[Home](/docs)
[Guide](/zh-Hant/guide/getting-started.mdx)[Guide](/docs/guide/getting-started)
[Demo](https://github.com/org/repo)不變(完整 URL)

撰寫規則

  • 跨頁文件連結:在英文 MDX 中使用 地區設定中立的網站路由 (/docs/…),或 content/docs/… / 相對 .mdx 路徑,並讓正規化器在 sync 期間重寫它們。
  • 內容樹外部的儲存庫檔案:使用 完整 URL。
  • 請勿手動編輯帶有地區設定後綴的副本 (*.pt.mdx) 或 content/{locale}/ 樹中的連結 — 請使用 sync / translate-docs 重新產生。

另請參閱 文件 — 連結改寫 與 設定 — docsOutput。

地區設定代碼 ​

讓您的 Fumadocs 應用程式中 ai-i18n-tools.config.json 的 targetLocales 與 defineI18n().languages 完全一致。點範例使用短代碼 (pt、zh);目錄設定可以使用 BCP-47 資料夾 (pt-BR、zh-Hans)。沒有強制正規化 — 不匹配的代碼會產生錯誤的輸出路徑或遺失的頁面。

多重集合 ​

Fumadocs 專案可在 source.config.ts 中定義多個 defineDocs 區塊(文件、部落格、範例)。請為每個要翻譯的集合新增一個 docs[] 區塊,各自擁有獨立的 contentPaths、outputDir 與 docsRoot。

範例專案 ​

examples/fumadocs-docs — 位於 content/docs/ 的英文 MDX,已提交的 pt 與 zh dot 後綴頁面、meta.json 及 lib/i18n/ui.{locale}.json。在連接埠 3080 上執行 pnpm run dev。

交叉參照 ​

採用 MIT 授權條款釋出。