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 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)ページコンテンツ、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を使用しています)。
既存のサイトで i18n を有効にする
英語のみのFumadocsアプリでは、translate-docsが兄弟ファイルを書き込む前に、ロケールルートとdefineI18nが必要です。初回セットアップでは、ウェブサイトまたはドキュメントサイトに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 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()オーバーライド)は、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のようなナビゲーションタイトルはそこには配置できません。この例では、JSONにsite.titleを保持し、nav.titleのためにcatalog["site.title"]を読み取ります。ファイル内に既に存在し、enオブジェクトにないキーはそのまま残ります。マージは{ ...existing, ...extracted }です。英語のリテラルが変更されたら、syncを再実行してください。outputPathTemplate(オプション) — ロケールごとの出力。デフォルト:catalogPathの隣のui.{locale}.json。
翻訳されたキーは、アプリがそれを読み取るまで何もしません。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 を参照してください。
標準ロケールは、LLM のコストなしで @fumadocs/language/* プリセットでカバーできます。カタログは、英語ブロックの プロジェクトのオーバーライドのみを翻訳します。
エージェントプロンプト
英語のみの 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`.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アプリ内のdefineI18n().languagesと、ai-i18n-tools.config.json内のtargetLocalesを正確に一致させてください。ドットの例ではショートコード(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カタログのブートストラップパターン)