Next.js

设置

在专用文件中定义 i18n 配置：

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

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

中间件

中间件文件处理基于语言的用户重定向：

import { createI18nMiddleware } from 'fumadocs-core/i18n/middleware';
import { i18n } from '@/lib/i18n';

export default createI18nMiddleware(i18n);

export const config = {
  matcher: ['/((?!api|_next/static|_next/image|favicon.ico).*)'],
};

你可以替换为自定义中间件，确保行为与配置的 hidePrefix 选项一致。

翻译

翻译定义支持英文默认值和特定语言覆盖：

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

baseOptions() 函数接受 locale 参数用于本地化布局配置。RootProvider 组件通过 i18nUI.provider(lang) 接收这些翻译。

路由结构

应用需要一个 /app/[lang] 文件夹，包含页面和布局，不包括路由处理器：

app/
  api/search/route.ts
  [lang]/
    layout.tsx
    (home)/page.tsx

常见错误是重构后丢失样式；请验证全局 CSS 的导入路径。

传递语言数据

四个关键位置需要语言参数：

1. lib/source.ts：在 loader 配置中添加 i18n
2. 首页布局：传递 locale 到 baseOptions(lang)
3. 文档布局：在 baseOptions(lang) 中包含 locale，通过 source.getPageTree(lang) 传递页面树
4. 文档页面：使用 source.getPage(slug, lang) 和 source.getPages(lang)

搜索配置

实现方式因搜索提供商而异：

• 内置 Orama 搜索有专门的 i18n 文档
• Algolia 等第三方方案通常包含原生多语言支持

导航

框架管理自己的布局导航。对于外部链接，useParams() hook 获取 locale 并应添加到 href 前。fumadocs-core/dynamic-link 的 DynamicLink 组件支持动态 href 模式，适用于 MDX 内容。