Tanstack Start

Setup

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

src/lib/i18n.ts

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

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

See available options for i18n config.

Translations

Define your translations in a file (e.g. lib/layout.shared.tsx), the English translations are used when translations is not specified.

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

lib/layout.shared.tsx

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

export const i18nUI = defineI18nUI(i18n, {
  translations: {
    en: {
      displayName: 'English',
    },
    cn: {
      displayName: 'Chinese',
      search: '搜尋文檔',
    },
  },
});

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

Pass translations to <RootProvider />:

src/routes/__root.tsx

import { HeadContent, Scripts, useParams } from '@tanstack/react-router';
import * as React from 'react';
import { RootProvider } from 'fumadocs-ui/provider/tanstack';
import { i18nUI } from '@/lib/layout.shared';

function RootDocument({ children }: { children: React.ReactNode }) {
  const { lang } = useParams({ strict: false });

  return (
    <html suppressHydrationWarning>
      <head>
        <HeadContent />
      </head>
      <body className="flex flex-col min-h-screen">
        <RootProvider
          i18n={i18nUI.provider(lang)}
        >
          {children}
        </RootProvider>
        <Scripts />
      </body>
    </html>
  );
}

Routing

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

index.tsx

docs/$.tsx

search.ts

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

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.

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

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

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

In addition, the fumadocs-core/dynamic-link component supports dynamic hrefs, you can use it to attend 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>