Fumadocs Internationalization

Before you get started

Fumadocs is not a full-powered i18n library, it manages only its own components and utilities.

You can use other libraries like next-intl for the rest of your app. Read the Next.js Docs to learn more about implementing I18n in Next.js.

Manual Setup

Create an i18n config file first. In this guide, it will be imported from @/lib/i18n.

Once that exists, pass it into the source loader.

lib/source.ts

import { i18n } from '@/lib/i18n';
import { loader } from 'fumadocs-core/source';

export const source = loader({
  i18n, 
  // other options
});

You should also update the Fumadocs UI layout options so the layouts know about your locales.

app/layout.config.tsx

import { i18n } from '@/lib/i18n';
import type { BaseLayoutProps } from 'fumadocs-ui/layouts/shared';

export function baseOptions(locale: string): BaseLayoutProps {
  return {
    i18n,
    // different props based on `locale`
  };
}

Middleware

Add middleware to redirect users to the proper locale.

{
  "file": "../../examples/i18n/middleware.ts",
  "codeblock": {
    "lang": "ts",
    "meta": "title=\"middleware.ts\""
  }
}

For more control, read Middleware.

Note that this is optional, you can also use your own middleware or the one provided by i18n libraries.

Route Structure

Create /app/[lang], then move your app files such as page.tsx and layout.tsx under that folder.

Wrap the root provider with I18nProvider, and pass in both the available locales and your translated UI strings. Only English translations are bundled by default, so other languages need to be supplied by you.

app/[lang]/layout.tsx

import { RootProvider } from 'fumadocs-ui/provider';
import { I18nProvider, type Translations } from 'fumadocs-ui/i18n';

const cn: Partial<Translations> = {
  search: 'Translated Content',
  // other translations
};

// available languages that will be displayed on UI
// make sure `locale` is consistent with your i18n config
const locales = [
  {
    name: 'English',
    locale: 'en',
  },
  {
    name: 'Chinese',
    locale: 'cn',
  },
];

export default async function RootLayout({
  params,
  children,
}: {
  params: Promise<{ lang: string }>;
  children: React.ReactNode;
}) {
  const lang = (await params).lang;

  return (
    <html lang={lang}>
      <body>
        <I18nProvider
          locale={lang}
          locales={locales}
          translations={{ cn }[lang]}
        >
          <RootProvider>{children}</RootProvider>
        </I18nProvider>
      </body>
    </html>
  );
}

Pass Locale Through Pages and Layouts

Every layout and page that talks to Fumadocs should receive the locale.

Search

Your search setup should also be aware of locale differences.

Built-in Search (Orama): For Supported Languages, no further changes are needed.

Otherwise, additional config is required (e.g. Chinese & Japanese). See Special Languages.
Cloud Solutions (e.g. Algolia): They usually have official support for multilingual.

Writing Documents

Fumadocs only manages navigation inside its own layouts, such as the sidebar. For links elsewhere in your app, read the locale from the URL with useParams and append it to the destination.

import Link from 'next/link';
import { useParams } from 'next/navigation';

const { lang } = useParams();

return <Link href={`/${lang}/another-page`}>This is a link</Link>;

fumadocs-core/dynamic-link can also build locale-aware hrefs automatically, which is especially useful inside Markdown or MDX content.

content.mdx

import { DynamicLink } from 'fumadocs-core/dynamic-link';

<DynamicLink href="/[lang]/another-page">This is a link</DynamicLink>

Before you get started

Fumadocs is not a full-powered i18n library, it manages only its own components and utilities.

You can use other libraries like next-intl for the rest of your app. Read the Next.js Docs to learn more about implementing I18n in Next.js.

Manual Setup

Create an i18n config file first. In this guide, it will be imported from @/lib/i18n.

Once that exists, pass it into the source loader.

lib/source.ts

import { i18n } from '@/lib/i18n';
import { loader } from 'fumadocs-core/source';

export const source = loader({
  i18n, 
  // other options
});

You should also update the Fumadocs UI layout options so the layouts know about your locales.

app/layout.config.tsx

import { i18n } from '@/lib/i18n';
import type { BaseLayoutProps } from 'fumadocs-ui/layouts/shared';

export function baseOptions(locale: string): BaseLayoutProps {
  return {
    i18n,
    // different props based on `locale`
  };
}

Middleware

Add middleware to redirect users to the proper locale.

{
  "file": "../../examples/i18n/middleware.ts",
  "codeblock": {
    "lang": "ts",
    "meta": "title=\"middleware.ts\""
  }
}

For more control, read Middleware.

Note that this is optional, you can also use your own middleware or the one provided by i18n libraries.

Route Structure

Create /app/[lang], then move your app files such as page.tsx and layout.tsx under that folder.

app/[lang]/layout.tsx

import { RootProvider } from 'fumadocs-ui/provider';
import { I18nProvider, type Translations } from 'fumadocs-ui/i18n';

const cn: Partial<Translations> = {
  search: 'Translated Content',
  // other translations
};

// available languages that will be displayed on UI
// make sure `locale` is consistent with your i18n config
const locales = [
  {
    name: 'English',
    locale: 'en',
  },
  {
    name: 'Chinese',
    locale: 'cn',
  },
];

export default async function RootLayout({
  params,
  children,
}: {
  params: Promise<{ lang: string }>;
  children: React.ReactNode;
}) {
  const lang = (await params).lang;

  return (
    <html lang={lang}>
      <body>
        <I18nProvider
          locale={lang}
          locales={locales}
          translations={{ cn }[lang]}
        >
          <RootProvider>{children}</RootProvider>
        </I18nProvider>
      </body>
    </html>
  );
}

Pass Locale Through Pages and Layouts

Every layout and page that talks to Fumadocs should receive the locale.

Search

Your search setup should also be aware of locale differences.

Built-in Search (Orama): For Supported Languages, no further changes are needed.

Otherwise, additional config is required (e.g. Chinese & Japanese). See Special Languages.
Cloud Solutions (e.g. Algolia): They usually have official support for multilingual.

Writing Documents

Fumadocs only manages navigation inside its own layouts, such as the sidebar. For links elsewhere in your app, read the locale from the URL with useParams and append it to the destination.

import Link from 'next/link';
import { useParams } from 'next/navigation';

const { lang } = useParams();

return <Link href={`/${lang}/another-page`}>This is a link</Link>;

fumadocs-core/dynamic-link can also build locale-aware hrefs automatically, which is especially useful inside Markdown or MDX content.

content.mdx

import { DynamicLink } from 'fumadocs-core/dynamic-link';

<DynamicLink href="/[lang]/another-page">This is a link</DynamicLink>

Manual Setup

Middleware

Route Structure

Pass Locale Through Pages and Layouts

Search

Writing Documents

Navigation

Author

Categories

More Posts

Orelune Tarot Series: Ten of Wands - Responsibility, Pressure, and Near Completion

Orelune Tarot Series: The Chariot - Willpower, Direction & Hard-Won Victory

Getting Started with Fumadocs

Newsletter

Fumadocs Internationalization

Manual Setup

Middleware

Route Structure

Pass Locale Through Pages and Layouts

Search

Writing Documents

Navigation

Author

Categories

More Posts

Orelune Tarot Series: Ten of Wands - Responsibility, Pressure, and Near Completion

Orelune Tarot Series: The Chariot - Willpower, Direction & Hard-Won Victory

Getting Started with Fumadocs

Newsletter