Fumadocsの統合

Next.js App RouterでFumadocs 4のドキュメントサイトには、init -t ui-fumadocsとdocsOutput.style: "fumadocs"を使用します。このプリセットは、空のdoc-systemとBCP-47または短いロケールコードが保持されたlocaleSubpathのエイリアスです（localePathLowercaseはデフォルトでfalse）。

Documentsと実行可能なexamples/fumadocs-docsデモ（ドットパーサー、ポート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)

ページコンテンツ、meta.jsonサイドバーラベル、およびFumadocs UIのオーバーライドを1回のsync実行で翻訳する場合は、features.translateDocsを有効にします。

ページレイアウト

Fumadocsは、docsOutput.fumadocsParserを介して2つのi18nコンテンツレイアウトをサポートしています。ドットパーサーがデフォルトです（Fumadocsに組み込まれており、SWRなどの本番サイトで使用されています）。

ドットパーサー (デフォルト)

英語の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 integration と一致します。

サイドバー (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スラッグ配列、root、icon、defaultOpen、またはその他の構造キー — 人間が読めるラベルのみを翻訳します。

UIカタログ

Fumadocsのレイアウトクローム（検索プレースホルダー、ロケール表示名、およびlib/layout.shared.ts内のその他のdefineTranslations / i18n.translations()オーバーライド）は、マークダウンから抽出されません。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（オプション） — ロケールごとの出力。デフォルト：catalogPathの隣のui.{locale}.json。

layout.shared.tsでloadUiCatalog(locale)を介してロケールごとのJSONをロードし、ルートレイアウトでi18nProvider(translations, lang)とマージします。examples/fumadocs-docs/lib/layout.shared.tsを参照してください。

標準ロケールは、LLM のコストなしで @fumadocs/language/* プリセットでカバーできます。カタログは、英語ブロックの プロジェクトのオーバーライドのみを翻訳します。

Fumadocs UI 文字列には json[] を使用しないでください。このパイプラインは、関連性のないアプリのロケールバンドル用です。

リンクの表記規則

Fumadocsは、Next.jsミドルウェア（/docs/getting-started、/pt/docs/getting-started）を介してロケールプレフィックス付きルートを提供します。ページ内リンクはロケールニュートラルであるべきです（/docs/getting-started）。そうすることで、アクティブなロケールプレフィックスが自動的に適用されます。

組み込みのノーマライザーを有効にすると、translate-docsがすべての翻訳ファイルのリンクを自動的に修正します:

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

rewriteFumadocsLinksは、styleが"fumadocs"の場合にデフォルトで有効になります。

英語ソースの作成者	正規化後
[Guide](content/docs/guide/getting-started.mdx)	[Guide](/docs/guide/getting-started)
[Home](content/docs/index.mdx)	[Home](/docs)
[Guide](/ja/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で再生成してください。

こちらも参照してください: Documents — link rewriting および Configuration — docsOutput。

ロケールコード

Fumadocs アプリの ai-i18n-tools.config.json の targetLocales を、defineI18n().languages と完全に一致させてください。ドットの例では短いコード (pt、zh) を使用していますが、ディレクトリ設定では BCP-47 フォルダー (pt-BR、zh-Hans) を使用できます。強制的な正規化はありません。コードが一致しないと、誤った出力パスやページが見つからない原因となります。

複数のコレクション

Fumadocs プロジェクトでは、source.config.ts に複数の defineDocs ブロック (docs、blog、examples) を定義できます。翻訳するコレクションごとに 1 つの docs[] ブロックを追加し、それぞれに独自の contentPaths、outputDir、および docsRoot を設定します。

サンプルプロジェクト

examples/fumadocs-docs — content/docs/ の英語 MDX、コミットされた pt と zh のドットサフィックスページ、meta.json、および lib/i18n/ui.{locale}.json。ポート 3080 で pnpm run dev を実行します。

相互参照

• 設定 — docsOutput
• 出力レイアウト
• Docusaurus integration
• Nextra integration (ディレクトリパーサーのメンタルモデル)
• VitePress integration (UIカタログのブートストラップパターン)