# Fumadocs (Framework Mode, Next.js): Internationalization
URL: /docs/next/internationalization
Source: https://raw.githubusercontent.com/fuma-nama/fumadocs/refs/heads/main/apps/docs/content/docs/(framework)/[framework]/internationalization.mdx

Support multiple languages in your Next.js docs.

<Callout title="Fumadocs CLI">
`npx @fumadocs/cli init --i18n` sets up a new docs with i18n, or configure it manually below.
</Callout>

## Overview [#overview]

Configure i18n routing on both Next.js and Fumadocs.

Fumadocs handles i18n for the docs content and sidebar. Internationalize the rest of your app with your own i18n setup.

You can also use libraries like [next-intl](https://github.com/amannn/next-intl) with Fumadocs. To learn the basics, see [i18n in Next.js](https://nextjs.org/docs/app/building-your-application/routing/internationalization).

## Setup [#setup]

Define the i18n config in a file. This guide imports it as `@/lib/i18n`.

```ts title="lib/i18n.ts"
import { defineI18n } from 'fumadocs-core/i18n';

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

> See [available options](/docs/headless/internationalization/config) for i18n config.

### Middleware [#middleware]

Create a middleware that redirects users to the appropriate locale.

```ts title="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).*)'],
};
```

<Callout title="Using your own middleware?">
The default middleware is optional. You can also use your own middleware, or the one of an i18n library.

Make sure its behaviour aligns with the [`hideLocale`](/docs/headless/internationalization/config#hide-locale-prefix) option you set in your i18n config.
</Callout>

### Routing [#routing]

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

<Files>
<Folder name="app" defaultOpen>
<File name="api/search/route.ts" />

<Folder name="[lang]" defaultOpen>
<File name="layout.tsx" />

<File name="(home)/page.tsx" />

<File name="..." />
</Folder>
</Folder>
</Files>

<Callout title="Common Mistake" type="error">
Did you accidentally find your styles lost? Make sure the import path to `global.css` is still
correct!
</Callout>

### Translations [#translations]

Define your translations in `lib/layout.shared.tsx`. See [Translations](/docs/ui/translations) for more details, including the official language packs.

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

```tsx title="lib/layout.shared.tsx"
// [!code ++:2]
import { i18n } from '@/lib/i18n';
import { uiTranslations } from 'fumadocs-ui/i18n';
import type { BaseLayoutProps } from 'fumadocs-ui/layouts/shared';

// [!code ++:11]
export const translations = i18n
  .translations()
  .extend(uiTranslations())
  .add({
    en: {
      displayName: 'English',
    },
    cn: {
      displayName: 'Chinese',
    },
  });

export function baseOptions(): BaseLayoutProps { // [!code --]
export function baseOptions(locale: string): BaseLayoutProps { // [!code ++]
  return {
    // different props based on `locale`
  };
}
```

Pass translations to `<RootProvider />`:

```tsx title="app/[lang]/layout.tsx"
import { RootProvider } from 'fumadocs-ui/provider/next';
// [!code ++:2]
import { i18nProvider } from 'fumadocs-ui/i18n';
import { translations } from '@/lib/layout.shared';

export default function Layout({ children }: LayoutProps<'/'>) { // [!code --]
// [!code ++:2]
export default async function Layout({ params, children }: LayoutProps<'/[lang]'>) {
  const { lang } = await params;

  return (
    // [!code highlight]
    <html lang={lang} suppressHydrationWarning>
      <body className="flex flex-col min-h-screen">
        <RootProvider
          // [!code ++]
          i18n={i18nProvider(translations, lang)}
        >
          {children}
        </RootProvider>
      </body>
    </html>
  );
}
```

### Pass Locale [#pass-locale]

Pass the locale to Fumadocs in your pages and layouts.

```ts tab="lib/source.ts"
import { i18n } from '@/lib/i18n'; // [!code ++]
import { loader } from 'fumadocs-core/source';

export const source = loader({
  i18n, // [!code ++]
  // other options
});
```

```tsx tab="Home Layout" title="app/[lang]/(home)/layout.tsx"
export default function Layout({ children }: LayoutProps<'/'>) { // [!code --]
// [!code ++:2]
export default async function Layout({ params, children }: LayoutProps<'/[lang]'>) {
  const { lang } = await params;

  return <HomeLayout {...baseOptions(lang)}>{children}</HomeLayout>; // [!code highlight]
}
```

```tsx tab="Docs Layout" title="app/[lang]/docs/layout.tsx"
export default function Layout({ children }: LayoutProps<'/docs'>) { // [!code --]
// [!code ++:2]
export default async function Layout({ params, children }: LayoutProps<'/[lang]/docs'>) {
  const { lang } = await params;

  return (
    // [!code highlight]
    <DocsLayout {...baseOptions(lang)} tree={source.getPageTree(lang)}>
      {children}
    </DocsLayout>
  );
}
```

```tsx tab="Docs Page" title="app/[lang]/docs/[[...slug]]/page.tsx"
export default async function Page(props: PageProps<'/docs/[[...slug]]'>) { // [!code --]
export default async function Page(props: PageProps<'/[lang]/docs/[[...slug]]'>) { // [!code ++]
  const params = await props.params;
  const page = source.getPage(params.slug); // [!code --]
  const page = source.getPage(params.slug, params.lang); // [!code ++]
  if (!page) notFound();

  // ...
}
```

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

```tsx
export function generateStaticParams() {
  return source.generateParams(); // [!code --]
  return source.generateParams('slug', 'locale'); // [!code ++]
}
```
</Callout>

### Search [#search]

Configure i18n on your search solution.

- **Built-in Search:** See [Internationalization](/docs/headless/search/orama#internationalization).
- **Cloud Solutions (e.g. Algolia):** They usually have official support for multilingual.

## Writing Documents [#writing-documents]

See [i18n routing](/docs/next/page-conventions#i18n-routing) to learn how to create pages for specific locales.

### Navigation [#navigation]

Fumadocs only handles navigation for its own layouts (e.g. sidebar).

For other places, use the `useParams` hook to get the locale from the URL, and prepend it to `href`.

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

const { lang } = useParams();

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

The [`fumadocs-core/dynamic-link`](/docs/headless/components/link#dynamic-hrefs) component supports dynamic hrefs, so you can use it to prepend the locale prefix in Markdown/MDX content.

```mdx title="content.mdx"
import { DynamicLink } from 'fumadocs-core/dynamic-link';

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