React 路由

安装

🌐 Setup

在文件中定义 i18n 配置，我们将在本指南中使用 @/lib/i18n 导入它。

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

app/lib/i18n.ts

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

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

查看可用选项以进行国际化配置。

路由

🌐 Routing

在你所有的页面前添加 :lang 前缀。

🌐 Add :lang prefix to all your pages.

app/routes.ts

import { route, type RouteConfig } from '@react-router/dev/routes';

export default [
  route(':lang', 'routes/home.tsx'),
  route(':lang/docs/*', 'docs/page.tsx'),
  route('api/search', 'docs/search.ts'),
] satisfies RouteConfig;

使区域设置可选

🌐 Make locale optional

你也可以使用 :lang? 前缀，并更新 i18n 配置：

🌐 You can also use :lang? prefix, and update the i18n config:

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

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

页面

🌐 Pages

为 <RootProvider /> 提供 UI 翻译和其他配置，英语翻译将作为回退使用。

🌐 Provide UI translations and other config to <RootProvider />, the English translations are used as fallbacks.

app/root.tsx

import { Links, Meta, Scripts, ScrollRestoration, useParams } from 'react-router';
import { RootProvider } from 'fumadocs-ui/provider/base';
import { ReactRouterProvider } from 'fumadocs-core/framework/react-router';
import { defineI18nUI } from 'fumadocs-ui/i18n';
import { i18n } from '@/lib/i18n';
import './app.css';

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

export function Layout({ children }: { children: React.ReactNode }) {
  const { lang = i18n.defaultLanguage } = useParams();

  return (
    <html lang="en" suppressHydrationWarning>
      <head>
        <meta charSet="utf-8" />
        <meta name="viewport" content="width=device-width, initial-scale=1" />
        <Meta />
        <Links />
      </head>
      <body className="flex flex-col min-h-screen">
        <ReactRouterProvider>
          <RootProvider
            i18n={provider(lang)}
          >
            {children}
          </RootProvider>
        </ReactRouterProvider>
        <ScrollRestoration />
        <Scripts />
      </body>
    </html>
  );
}

通过地区

🌐 Pass Locale

将 locale 参数添加到 baseOptions() 并在 props 中包含 i18n：

🌐 Add locale parameter to baseOptions() and include i18n in props:

app/lib/layout.shared.tsx

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

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

在你的页面和布局中将区域设置传递给 Fumadocs。

🌐 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

在你的搜索解决方案上配置国际化（i18n）。

🌐 Configure i18n on your search solution.

内置搜索（Orama）： 参见国际化。
云解决方案（例如 Algolia）： 它们通常提供官方的多语言支持。

撰写文档

🌐 Writing Documents

请参阅 i18n 路由了解如何为特定语言创建页面。

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

🌐 Navigation

Fumadocs 仅处理自己布局（例如侧边栏）的导航。对于其他地方，你可以使用 useParams 钩子从 URL 获取语言环境。

🌐 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 'react-router';

const { lang } = useParams();

<Link to={`/${lang}/about`}>About Us</Link>;

此外，fumadocs-core/dynamic-link 组件支持动态 href，你可以用它来处理本地化前缀。这对于 Markdown/MDX 内容非常有用。

🌐 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>

On this page