Internationalization

Overview

For Next.js apps, you'll have to configure i18n routing on both Next.js and Fumadocs.

Fumadocs is not a full-powered i18n library, it's up to you when implementing i18n for Next.js part. You can also use other libraries with Fumadocs like next-intl.

Learn more about i18n in Next.js.

Setup

Define the i18n configurations in a file, we will import it with @/ilb/i18n in this guide.

lib/i18n.ts

import type { I18nConfig } from 'fumadocs-core/i18n';

export const i18n: I18nConfig = {
  defaultLanguage: 'en',
  languages: ['en', 'cn'],
};

See customisable options.

Pass it to the source loader.

lib/source.ts

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

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

Middleware

Create a middleware that redirects users to appropriate locale.

middleware.ts

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

export default createI18nMiddleware(i18n);

export const config = {
  // Matcher ignoring `/_next/` and `/api/`
  matcher: ['/((?!api|_next/static|_next/image|favicon.ico).*)'],
};

Custom Middleware

The default middleware is optional, you can instead use your own middleware or the one provided by i18n libraries.

When using custom middleware, make sure the locale is correctly passed to Fumadocs. You may also want to customise page URLs from loader().

Routing

Create a /app/[lang] folder, and move all files (e.g. page.tsx, layout.tsx) from /app to the folder.

Provide UI translations and other config to <RootProvider />. Note that only English translations are provided by default.

app/[lang]/layout.tsx

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

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

// 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>
        <RootProvider
          i18n={{
            locale: lang,
            locales,
            translations: { cn }[lang],
          }}
        >
          {children}
        </RootProvider>
      </body>
    </html>
  );
}

Pass Locale

Pass the locale to Fumadocs in your pages and layouts.

app/layout.config.tsx

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

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

/app/[lang]/(home)/layout.tsx

import type { ReactNode } from 'react';
import { HomeLayout } from 'fumadocs-ui/layouts/home';
import { baseOptions } from '@/app/layout.config';

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

  return <HomeLayout {...baseOptions(lang)}>{children}</HomeLayout>;
}

/app/[lang]/docs/layout.tsx

import type { ReactNode } from 'react';
import { source } from '@/lib/source';
import { DocsLayout } from 'fumadocs-ui/layouts/docs';
import { baseOptions } from '@/app/layout.config';

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

  return (
    <DocsLayout {...baseOptions(lang)} tree={source.pageTree[lang]}>
      {children}
    </DocsLayout>
  );
}

page.tsx

import { source } from '@/lib/source';

export default async function Page({
  params,
}: {
  params: Promise<{ lang: string; slug?: string[] }>;
}) {
  const { slug, lang } = await params;
  // get page
  source.getPage(slug);
  source.getPage(slug, lang);

  // get pages
  source.getPages();
  source.getPages(lang);
}

Using another name for lang dynamic segment?

If you're using another name like app/[locale], you also need to update generateStaticParams() in docs page:

export function generateStaticParams() {
  return source.generateParams();
  return source.generateParams('slug', 'locale'); // new param name
}

Search

Configure i18n on your search solution.

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

You can add Markdown/meta files for different languages by attending .{locale} to your file name, like page.cn.md and meta.cn.json.

Make sure to create a file for the default locale first, the locale code is optional (e.g. both get-started.mdx and get-started.en.mdx are accepted).

meta.json

meta.cn.json

get-started.mdx

get-started.cn.mdx

Fumadocs only handles navigation for its own layouts (e.g. sidebar). For other places, you can use the useParams hook to get the locale from url, and attend it to href.

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

const { lang } = useParams();

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

In addition, the fumadocs-core/dynamic-link component supports dynamic hrefs, you can use it to attend the locale prefix. It is useful for Markdown/MDX content.

content.mdx

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

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