Fumadocs integration
Use init -t ui-fumadocs and docsOutput.style: "fumadocs" for Fumadocs 4 documentation sites on Next.js App Router. The preset is an alias for doc-system with an empty localeSubpath and BCP-47 or short locale codes preserved (localePathLowercase defaults to false).
See also Documents and the runnable examples/fumadocs-docs demo (dot parser, port 3080).
Quick start
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)Enable features.translateDocs when you translate page content, meta.json sidebar labels, and Fumadocs UI overrides in one sync run.
Page layout
Fumadocs supports two i18n content layouts via docsOutput.fumadocsParser. The dot parser is the default (Fumadocs built-in and production sites such as SWR).
Dot parser (default)
English MDX lives at the collection root. Translated copies use a locale suffix in the same directory:
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
}
}Align targetLocales with defineI18n().languages in lib/i18n.ts exactly (the example uses short codes pt and zh).
Enable i18n in an existing site
An English-only Fumadocs app needs a locale route and defineI18n before translate-docs can write sibling files. First-time setup uses the prompt on Add i18n to a website or docs site. The agent prompt on this page is the follow-up that wires the UI catalog. Checklist:
defineI18ninlib/i18n.tswithlanguages,defaultLanguage, andparser: "dot"or"dir".app/[lang]/routes andcreateI18nMiddlewarefromproxy.ts(the example's file).i18n.translations()inlib/layout.shared.ts, passed toi18nProvider.- English MDX at the collection root (dot) or under
content/docs/en/(dir). targetLocalesequal tolanguagesminus the default language, thensync.
Dir parser (Nextra-style)
For teams used to locale folders (content/docs/en/ → content/docs/pt-BR/), set fumadocsParser to "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
}
}See ai-i18n-tools.config.dir.example.json in examples/fumadocs-docs for a copy-paste dir config. Mental model matches Nextra integration.
Sidebar (meta.json)
Fumadocs uses JSON meta.json files for sidebar structure and titles. When docsOutput.style is "fumadocs", translate-docs collects meta.json under docsRoot (or docs[].fumadocsMetaGlob), translates string values for keys listed in docs[].fumadocsMetaTranslatableKeys (default: title, description), and writes locale outputs:
| Parser | Source locale | Output |
|---|---|---|
| dot | content/docs/**/meta.json | content/docs/**/meta.{locale}.json |
| dir | content/docs/en/**/meta.json | content/docs/{locale}/**/meta.json |
Do not translate pages slug arrays, root, icon, defaultOpen, or other structural keys — only human-readable labels.
UI catalog
Fumadocs layout shell strings (search placeholder, locale display names, and other defineTranslations / i18n.translations() overrides in lib/layout.shared.ts) are not extracted from markdown. Configure docsOutput.fumadocsUiCatalog so translate-docs bootstraps the source-locale catalog from sourcePath and translates per-locale 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— English flat JSON. The bootstrap reads only theenobject of.add({ … })insourcePath. String literals in that object become catalog keys (displayName,Search(search trigger))..add()only accepts keys the Fumadocs UI presets registered, so a nav title such assite.titlecannot live there. The example keepssite.titlein the JSON and readscatalog["site.title"]fornav.title. Keys already in the file but absent from theenobject stay: the merge is{ ...existing, ...extracted }. Re-runsyncwhen the English literals change.outputPathTemplate(optional) — per-locale outputs; default:ui.{locale}.jsonbesidecatalogPath.
A translated key does nothing until the app reads it. i18n.translations().get(lang) returns only keys registered with .extend() (the Fumadocs UI presets). Spread the locale catalog into .add() so those keys apply, and put native displayName after the spread so a translation of the English name does not replace it:
"pt-BR": {
...loadUiCatalog("pt-BR"),
displayName: "Português (Brasil)",
},site.title is not a Fumadocs UI key. The example reads it from the catalog for nav.title. A search label that exists only in ui.pt-BR.json stays on the built-in preset until that spread (or another read) uses it.
See examples/fumadocs-docs/lib/layout.shared.ts.
Standard locales may be covered by @fumadocs/language/* presets without LLM cost; the catalog translates project overrides in the English block only.
Agent prompt
Copy this when an English-only Fumadocs site should gain locales. It wires routing and the UI catalog. It does not translate strings.
UI catalog prompt
# 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`.Do not use json[] for Fumadocs UI strings — that pipeline is for unrelated app locale bundles.
Link conventions
Fumadocs serves locale-prefixed routes via Next.js middleware (/docs/getting-started, /pt/docs/getting-started). In-page links should stay locale-neutral (/docs/getting-started) so the active locale prefix is applied automatically.
Enable the built-in normaliser so translate-docs fixes links in every translated file automatically:
"docsOutput": {
"style": "fumadocs",
"docsRoot": "content/docs",
"rewriteFumadocsLinks": true
}rewriteFumadocsLinks defaults to enabled when style is "fumadocs".
| Author in the source locale | After normaliser |
|---|---|
[Guide](content/docs/guide/getting-started.mdx) | [Guide](/docs/guide/getting-started) |
[Home](content/docs/index.mdx) | [Home](/docs) |
[Guide](../guide/getting-started.mdx) | [Guide](/docs/guide/getting-started) |
[Demo](https://github.com/org/repo) | unchanged (full URL) |
Authoring rules
- Cross-page doc links: use locale-neutral site routes (
/docs/…) in English MDX, orcontent/docs/…/ relative.mdxpaths and let the normaliser rewrite them duringsync. - Repo files outside the content tree: use full URLs.
- Do not hand-edit links in locale-suffixed copies (
*.pt.mdx) orcontent/{locale}/trees — regenerate withsync/translate-docs.
See also Documents — link rewriting and Configuration — docsOutput.
Locale codes
Keep targetLocales in ai-i18n-tools.config.json aligned with defineI18n().languages in your Fumadocs app exactly. The dot example uses short codes (pt, zh); dir configs may use BCP-47 folders (pt-BR, zh-Hans). There is no forced normalisation — mismatched codes produce wrong output paths or missing pages.
Multiple collections
Fumadocs projects may define several defineDocs blocks in source.config.ts (docs, blog, examples). Add one docs[] block per collection you translate, each with its own contentPaths, outputDir, and docsRoot.
Example project
examples/fumadocs-docs — English MDX at content/docs/, committed pt and zh dot-suffix pages, meta.json, and lib/i18n/ui.{locale}.json. Run pnpm run dev on port 3080.
Cross-references
- Configuration —
docsOutput - Output layouts
- Docusaurus integration
- Nextra integration (dir parser mental model)
- VitePress integration (UI catalog bootstrap pattern)