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 <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)

当您在一次 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）。

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（引导输出）。当 layout.shared.ts 中的英文覆盖发生更改时，请重新运行 sync。
• outputPathTemplate（可选）—— 每个区域设置的输出；默认：ui.{locale}.json 位于 catalogPath 旁边。

通过 loadUiCatalog(locale) 在 layout.shared.ts 中加载每个区域设置的 JSON，并在您的根布局中与 i18nProvider(translations, lang) 合并。请参阅 examples/fumadocs-docs/lib/layout.shared.ts。

标准区域设置可由 @fumadocs/language/* 预设覆盖，无需 LLM 成本；目录仅在英文块中翻译 项目覆盖。

不要 将 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-Hans/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。

区域设置代码

请将 ai-i18n-tools.config.json 中的 targetLocales 与你的 Fumadocs 应用中的 defineI18n().languages 保持完全一致。dot 示例使用短代码（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 目录引导模式）