Fumadocs 国际化配置

开始之前

Fumadocs 不是一个功能齐全的 i18n 库，它只管理自己的组件和工具。

您可以使用其他库，如 next-intl，用于应用程序的其余部分。阅读 Next.js 文档，了解更多关于在 Next.js 中实现 I18n 的信息。

手动配置

先准备一个 i18n 配置文件。本篇示例会从 @/lib/i18n 导入它。

配置完成后，把它传给 source loader。

lib/source.ts

import { i18n } from '@/lib/i18n';
import { loader } from 'fumadocs-core/source';

export const source = loader({
  i18n, 
  // other options
});

同时也要更新 Fumadocs UI 的布局选项，让布局层知道有哪些语言可用。

app/layout.config.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`
  };
}

中间件

接着添加中间件，把用户重定向到正确的语言路径下。

{
  "file": "../../examples/i18n/middleware.ts",
  "codeblock": {
    "lang": "ts",
    "meta": "title=\"middleware.ts\""
  }
}

如果你想进一步定制，可以查看中间件。

请注意，这是可选的，您也可以使用自己的中间件或 i18n 库提供的中间件。

路由结构

创建 /app/[lang] 目录，然后把 page.tsx、layout.tsx 等原本放在 /app 下的文件迁移进去。

之后用 I18nProvider 包住根 provider，并传入可用语言列表与翻译内容。默认只自带英文文本，因此其他语言需要你自行提供。

app/[lang]/layout.tsx

import { RootProvider } from 'fumadocs-ui/provider';
import { I18nProvider, type Translations } from 'fumadocs-ui/i18n';

const cn: Partial<Translations> = {
  search: 'Translated Content',
  // other translations
};

// available languages that will be displayed on UI
// make sure `locale` is consistent with your i18n config
const locales = [
  {
    name: 'English',
    locale: 'en',
  },
  {
    name: 'Chinese',
    locale: 'cn',
  },
];

export default async function RootLayout({
  params,
  children,
}: {
  params: Promise<{ lang: string }>;
  children: React.ReactNode;
}) {
  const lang = (await params).lang;

  return (
    <html lang={lang}>
      <body>
        <I18nProvider
          locale={lang}
          locales={locales}
          translations={{ cn }[lang]}
        >
          <RootProvider>{children}</RootProvider>
        </I18nProvider>
      </body>
    </html>
  );
}

在页面与布局中传递语言

所有和 Fumadocs 交互的页面、布局，都应该把 locale 一路传进去。

搜索

搜索方案同样要考虑多语言差异。

内置搜索 (Orama)： 对于支持的语言，无需进一步更改。

否则，需要额外配置（例如中文和日语）。请参阅特殊语言。
云解决方案（例如 Algolia）： 它们通常官方支持多语言。

编写文档

手动配置

先准备一个 i18n 配置文件。本篇示例会从 @/lib/i18n 导入它。

配置完成后，把它传给 source loader。

lib/source.ts

import { i18n } from '@/lib/i18n';
import { loader } from 'fumadocs-core/source';

export const source = loader({
  i18n, 
  // other options
});

同时也要更新 Fumadocs UI 的布局选项，让布局层知道有哪些语言可用。

app/layout.config.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`
  };
}

中间件

接着添加中间件，把用户重定向到正确的语言路径下。

{
  "file": "../../examples/i18n/middleware.ts",
  "codeblock": {
    "lang": "ts",
    "meta": "title=\"middleware.ts\""
  }
}

如果你想进一步定制，可以查看中间件。

请注意，这是可选的，您也可以使用自己的中间件或 i18n 库提供的中间件。

路由结构

创建 /app/[lang] 目录，然后把 page.tsx、layout.tsx 等原本放在 /app 下的文件迁移进去。

之后用 I18nProvider 包住根 provider，并传入可用语言列表与翻译内容。默认只自带英文文本，因此其他语言需要你自行提供。

app/[lang]/layout.tsx

import { RootProvider } from 'fumadocs-ui/provider';
import { I18nProvider, type Translations } from 'fumadocs-ui/i18n';

const cn: Partial<Translations> = {
  search: 'Translated Content',
  // other translations
};

// available languages that will be displayed on UI
// make sure `locale` is consistent with your i18n config
const locales = [
  {
    name: 'English',
    locale: 'en',
  },
  {
    name: 'Chinese',
    locale: 'cn',
  },
];

export default async function RootLayout({
  params,
  children,
}: {
  params: Promise<{ lang: string }>;
  children: React.ReactNode;
}) {
  const lang = (await params).lang;

  return (
    <html lang={lang}>
      <body>
        <I18nProvider
          locale={lang}
          locales={locales}
          translations={{ cn }[lang]}
        >
          <RootProvider>{children}</RootProvider>
        </I18nProvider>
      </body>
    </html>
  );
}

在页面与布局中传递语言

所有和 Fumadocs 交互的页面、布局，都应该把 locale 一路传进去。

搜索

搜索方案同样要考虑多语言差异。

内置搜索 (Orama)： 对于支持的语言，无需进一步更改。

否则，需要额外配置（例如中文和日语）。请参阅特殊语言。
云解决方案（例如 Algolia）： 它们通常官方支持多语言。

手动配置

中间件

路由结构

在页面与布局中传递语言

搜索

编写文档

导航

作者

分类

更多文章

Orelune Tarot Series: Seven of Wands - Courage Under Pressure and Steady Defense

Orelune 塔罗系列：皇帝——秩序、权威与稳固根基

Orelune塔罗系列：权杖国王牌义——远见、领导与掌控力

邮件列表

Fumadocs 国际化配置

手动配置

中间件

路由结构

在页面与布局中传递语言

搜索

编写文档

导航

作者

分类

更多文章

Orelune Tarot Series: Seven of Wands - Courage Under Pressure and Steady Defense

Orelune 塔罗系列：皇帝——秩序、权威与稳固根基

Orelune塔罗系列：权杖国王牌义——远见、领导与掌控力

邮件列表