Internationalization

Read the Next.js Docs to learn more about implementing I18n in Next.js.

Setup

Define all supported languages in a file.
i18n.ts
export const defaultLanguage = 'en'; export const languages = ['en', 'cn'];
Change your current source configurations.
source.ts
import { languages } from '@/i18n'; import { loader } from 'fumadocs-core/source'; export const { getPage, getPages, pageTree } = loader({ languages, ... });

Create the middleware that redirects users when missing locale.

middleware.ts

import { defaultLanguage, languages } from '@/i18n';
import { createI18nMiddleware } from 'fumadocs-core/middleware';
 
export default createI18nMiddleware({
  languages,
  defaultLanguage,
});
 
export const config = {
  // Matcher ignoring `/_next/` and `/api/`
  matcher: ['/((?!api|_next/static|_next/image|favicon.ico).*)'],
};

Create a dynamic route /app/[lang], and move all special files to the folder.
app/[lang]/layout.tsx
export default function Layout({ params, children, }: { params: { lang: string }; children: React.ReactNode; }) { return ( <html lang={params.lang}> <body>{children}</body> </html> ); }
Write documents, see Page Conventions to learn how to organize your documents.
Configure i18n on your search solution. For Flexsearch, see Setup I18n.

Get Pages

To get the pages of a specific language, use the utilities exported from source.ts.

import { getPage, getPages, pageTree } from '@/source';
 
// get page tree
pageTree[params.lang];
 
// get page
getPage(params.slug, params.lang);
 
// get pages
getPages(params.lang);

Static Generation

Generate parameters for every language and page.

import { getPages } from '@/source';
import { languages } from '@/i18n';
 
export async function generateStaticParams() {
  return languages.flatMap((lang) =>
    getPages(lang)!.map((page) => ({
      slug: page.slug,
      lang,
    })),
  );
}

Setup UI

A I18nProvider is needed for localization. Wrap the root provider inside your i18n provider.

import { RootProvider } from 'fumadocs-ui/provider';
import { I18nProvider } from 'fumadocs-ui/i18n';
 
export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <I18nProvider>
      <RootProvider>{children}</RootProvider>
    </I18nProvider>
  );
}

Adding Translations

We only provide english translation by default, you have to pass your translations to the provider.

import { RootProvider } from 'fumadocs-ui/provider';
import { I18nProvider } from 'fumadocs-ui/i18n';
 
export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <I18nProvider
      translations={{
        cn: {
          name: 'Chinese', // required
          search: 'Translated Content',
        },
      }}
    >
      <RootProvider>{children}</RootProvider>
    </I18nProvider>
  );
}

To allow users changing their language, enable i18n on docs layout.

[lang]/docs/layout.tsx

import { DocsLayout } from 'fumadocs-ui/layout';
 
export default function Layout({ children }: { children: React.ReactNode }) {
  return <DocsLayout i18n>{children}</DocsLayout>;
}