Translate Your Fumadocs Site with AI

Ship multilingual documentation without duplicating your Fumadocs setup. Babely translates UI JSON and MDX content in one command — navigation labels, search UI, and every docs page.

Why teams automate this

UI strings and docs content live in different formats

Fumadocs sites mix ui.[locale].json for chrome strings and MDX files under content/docs/[locale]/. Managing both manually does not scale.

MDX breaks with naive translation tools

Code blocks, front matter, and component syntax must stay untouched while prose translates — generic tools often corrupt MDX.

Docs lag behind the source language

When English docs update frequently, translated locales fall behind unless translation is part of your docs CI pipeline.

How it works

Configure JSON and MDX includes

Point Babely at Fumadocs UI JSON files and your docs MDX tree. Align target locales with your content folder names.

{
  "locale": {
    "source": "en",
    "targets": ["cn", "fr"]
  },
  "files": {
    "json": {
      "include": ["content/ui.[locale].json"]
    },
    "md": {
      "include": ["content/docs/[locale]/**/*.mdx"]
    }
  }
}

Translate UI chrome and docs together

One translate command updates navigation labels, search placeholders, and every docs page that changed since the last run.

npx @babely/cli@latest translate

Review MDX diffs in Git

Code fences and front matter stay untranslated. Review prose changes in pull requests before publishing to your docs site.

Automate in CI

Run Babely on every docs change so translated locales stay in sync with English source content.

# See docs/ci for pipeline setup

Example babely.json

Copy this config into your project root and adjust targets to match your locale folders.

{
  "locale": {
    "source": "en",
    "targets": ["fr", "es"]
  },
  "files": {
    "json": {
      "include": ["content/ui.[locale].json"]
    },
    "md": {
      "include": ["content/docs/[locale]/**/*.mdx"]
    }
  }
}

Why Babely for Fumadocs

UI + docs in one config

Translate Fumadocs navigation, search UI, and MDX pages without separate tools or workflows.

MDX-safe translation

Code blocks, front matter, and Markdown structure are preserved while prose translates.

Locale folder parity

Babely mirrors your content/docs/[locale]/ tree so Fumadocs routing keeps working unchanged.

CI-ready CLI

Git diff detection means only updated docs pages are translated — ideal for fast-moving documentation.

Other use cases

next-intl

Babely translates your messages/[locale].json files while preserving ICU plurals, select rules, rich text tags, and nested keys — the same stack we use on babely.dev.

next-international

Babely translates your locales/[locale].ts modules while preserving TypeScript structure and nested keys — a lightweight alternative to next-intl for Next.js apps.

Nuxt

Babely translates your Nuxt locale JSON files while preserving linked keys, interpolation, and layout namespaces — the only Vue stack example in the Babely repo.

Start translating your Fumadocs project

Set up Babely in minutes, automate translations in CI, and ship multilingual products without enterprise localization overhead.

Read the guide Quickstart

Frequently Asked Questions

Does Babely translate code blocks in MDX?

No. Code fences and inline code stay in the source language. Only prose, headings, and front matter values meant for readers are translated.

Can I translate Fumadocs UI strings separately?

Yes, but you do not need to. A single babely.json can include both content/ui.[locale].json and content/docs/[locale]/**/*.mdx paths.

How do target locales map to Fumadocs folders?

Set targets in babely.json to match your locale folder names (e.g. cn, fr, es). Babely writes files under those paths so Fumadocs i18n routing picks them up.

Does this work with Fumadocs i18n routing?

Yes. Babely only manages translation files on disk. Your existing Fumadocs locale config and middleware continue to serve translated content.