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>
  );
}

Writing Documents

see Page Conventions to learn how to organize your documents.

Search

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 '@/app/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 '@/app/source';
import { languages } from '@/i18n';
 
export async function generateStaticParams() {
  return languages.flatMap((lang) =>
    getPages(lang)!.map((page) => ({
      slug: page.slug,
      lang,
    })),
  );
}

Middleware Options

You can also customise the I18n middleware.

Hide Locale Prefix

To hide the locale prefix, for example, use / instead of /en where en is the default locale, use the hidePrefix option.

Mode	Description
`always`	Always hide the prefix
`default-locale`	Only hide the default locale
`never`	Never hide the prefix (default)

It uses NextResponse.rewrite under the hood.

import { defaultLanguage, languages } from '@/i18n';
import { createI18nMiddleware } from 'fumadocs-core/middleware';
 
export default createI18nMiddleware({
  languages,
  defaultLanguage,
  hideLocale: 'default-locale',
});