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)。
快速開始
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 檔案位於集合根目錄。翻譯副本在同一目錄中使用地區代碼後綴:
content/docs/index.mdx → content/docs/index.pt.mdx
content/docs/guide/getting-started.mdx → content/docs/guide/getting-started.zh.mdx{
"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":
content/docs/en/index.mdx → content/docs/pt-BR/index.mdx
content/docs/en/guide/foo.mdx → content/docs/zh-Hans/guide/foo.mdx{
"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),並寫入地區設定輸出:
| 解析器 | 來源語系 | 輸出 |
|---|---|---|
| dot | content/docs/**/meta.json | content/docs/**/meta.{locale}.json |
| dir | content/docs/en/**/meta.json | content/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:
{
"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 放在展開運算 之後,這樣英文名稱的翻譯才不會取代它:
"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 目錄提示
# 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 自動修正每個翻譯檔案中的連結:
"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。
交叉參照
- 設定 —
docsOutput - 輸出佈局
- Docusaurus 整合
- Nextra 整合 (目錄解析器心智模型)
- VitePress 整合 (UI 目錄啟動模式)