Next.js

New to Next.js?

You can learn more about i18n in Next.js.

Setup

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

lib/i18n.ts

import { defineI18n } from 'fumadocs-core/i18n';

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

See available options for i18n config.

Middleware

Create a middleware that redirects users to appropriate locale.

proxy.ts

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

export default createI18nMiddleware(i18n);

export const config = {
  // Matcher ignoring `/_next/` and `/api/`
  // You may need to adjust it to ignore static assets in `/public` folder
  matcher: ['/((?!api|_next/static|_next/image|favicon.ico).*)'],
};

Using your own middleware?

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

Make sure its behaviour aligns with the hidePrefix option you set in your i18n config.

Translations

Define your translations in lib/layout.shared.tsx, see Translations for more details (including official language packs).

You can also add locale parameter to baseOptions() for localized layout options:

lib/layout.shared.tsx

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

export const translations = i18n
  .translations()
  .extend(uiTranslations())
  .add({
    en: {
      displayName: 'English',
    },
    cn: {
      displayName: 'Chinese',
    },
  });

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

Pass translations to <RootProvider />:

app/[lang]/layout.tsx

import { RootProvider } from 'fumadocs-ui/provider/next';
import { translations } from '@/lib/layout.shared';
import { i18nProvider } from 'fumadocs-ui/i18n';

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={i18nProvider(translations, lang)}
        >
          {children}
        </RootProvider>
      </body>
    </html>
  );
}

Routing

Create a /app/[lang] folder, and move your pages/layouts into it, except route handlers.

api/search/route.ts

layout.tsx

(home)/page.tsx

...

Common Mistake

Did you accidentally find your styles lost? Make sure the import path to global.css is still correct!

Pass Locale

Pass the locale to Fumadocs in your pages and layouts.

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

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

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): See Internationalization.
Cloud Solutions (e.g. Algolia): They usually have official support for multilingual.

Writing Documents

See i18n routing to learn how to create pages for specific locales.

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 prepend 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 prepend 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>