Internationalization

OverviewCopy Anchor Link

Configure i18n routing on both TanStack Start and Fumadocs.

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

SetupCopy Anchor Link

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

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

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

RoutingCopy Anchor Link

Create a $lang directory under routes, and move all pages into it.

TranslationsCopy Anchor Link

Define your translations in lib/layout.shared.tsx. See Translations for more details, including the official language packs.

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

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(): BaseLayoutProps { 
export function baseOptions(locale: string): BaseLayoutProps { 
  return {
    // different props based on `locale`
  };
}

Pass translations to <RootProvider />:

import { createRootRoute, HeadContent, Outlet, Scripts } from '@tanstack/react-router'; 
import { createRootRoute, HeadContent, Outlet, Scripts, useParams } from '@tanstack/react-router'; 
import { RootProvider } from 'fumadocs-ui/provider/tanstack';
import { i18nProvider } from 'fumadocs-ui/i18n';
import { i18n } from '@/lib/i18n';
import { translations } from '@/lib/layout.shared';

// ...

function RootComponent() {
  const { lang = i18n.defaultLanguage } = useParams({ strict: false }); 

  return (
    <html lang={lang} suppressHydrationWarning>
      <head>
        <HeadContent />
      </head>
      <body className="flex flex-col min-h-screen">
        <RootProvider
          i18n={i18nProvider(translations, lang)}
        >
          <Outlet />
        </RootProvider>
        <Scripts />
      </body>
    </html>
  );
}

Pass LocaleCopy Anchor Link

Pass the locale to Fumadocs in your pages and layouts.

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

export const source = loader({
  source: docs.toFumadocsSource(),
  baseUrl: '/docs',
  i18n, 
});

SearchCopy Anchor Link

Configure i18n on your search solution.

• Built-in Search: See Internationalization.
• Cloud Solutions (e.g. Algolia): They usually have official support for multilingual.

Writing DocumentsCopy Anchor Link

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

NavigationCopy Anchor Link

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.

import { Link, useParams } from '@tanstack/react-router';

const { lang } = useParams({ from: '/$lang/' });

<Link
  to="/$lang/docs/$"
  params={{
    lang,
    _splat: '',
  }}
>
  Open Docs
</Link>;

The fumadocs-core/dynamic-link component supports dynamic hrefs, so you can use it to prepend the locale prefix in Markdown/MDX content.

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

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