Next.js
在你的 Next.js + Fumadocs 应用中支持国际化路由
刚接触 Next.js？
安装
🌐 Setup
在文件中定义 i18n 配置，我们将在本指南中使用 @/lib/i18n 导入它。
🌐 Define the i18n configurations in a file, we will import it with @/lib/i18n in this guide.
import { defineI18n } from 'fumadocs-core/i18n';
export const i18n = defineI18n({
defaultLanguage: 'en',
languages: ['en', 'cn'],
});查看 可用选项 以进行国际化配置。
中间件
🌐 Middleware
创建一个中间件，将用户重定向到适当的语言环境。
🌐 Create a middleware that redirects users to appropriate locale.
import { createI18nMiddleware } from 'fumadocs-core/i18n/middleware';
import { i18n } from '@/lib/i18n';
export default createI18nMiddleware(i18n);
export const config = {
// Matcher ignoring `/_next/` and `/api/`
// You may need to adjust it to ignore static assets in `/public` folder
matcher: ['/((?!api|_next/static|_next/image|favicon.ico).*)'],
};使用你自己的中间件？
默认的中间件是可选的，你也可以使用你自己的中间件或 i18n 库提供的中间件。
🌐 The default middleware is optional, you can also use your own middleware or the one provided by i18n libraries.
确保其行为与你在 i18n 配置中设置的 hidePrefix 选项一致。
🌐 Make sure its behaviour aligns with the hidePrefix option you set in your i18n config.
路由
🌐 Routing
创建一个 /app/[lang] 文件夹，并将你的页面/布局移动到其中，但路由处理程序除外。
🌐 Create a /app/[lang] folder, and move your pages/layouts into it, except route handlers.
常见错误
你是否意外发现你的样式丢失了？请确保导入 global.css 的路径仍然正确！
为 <RootProvider /> 提供界面翻译和其他配置，当未指定 translations 时使用英文翻译。
🌐 Provide UI translations and other config to <RootProvider />, the English translations are used when translations is not specified.
import { RootProvider } from 'fumadocs-ui/provider/next';
import { defineI18nUI } from 'fumadocs-ui/i18n';
import { i18n } from '@/lib/i18n';
const { provider } = defineI18nUI(i18n, {
translations: {
en: {
displayName: 'English',
},
cn: {
displayName: 'Chinese',
search: '搜尋文檔',
},
},
});
export default async function RootLayout({
params,
children,
}: {
params: Promise<{ lang: string }>;
children: React.ReactNode;
}) {
const lang = (await params).lang;
return (
<html lang={lang}>
<body>
<RootProvider
i18n={provider(lang)}
>
{children}
</RootProvider>
</body>
</html>
);
}通过地区
🌐 Pass Locale
将 locale 参数添加到 baseOptions() 并将 i18n 添加到其中：
🌐 Add locale parameter to baseOptions() and add i18n into it:
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
});为 lang 动态段使用另一个名称?
如果你使用其他名称如 app/[locale]，你还需要在文档页面中更新 generateStaticParams()：
🌐 If you're using another name like app/[locale], you also need to update generateStaticParams() in docs page:
export function generateStaticParams() {
return source.generateParams();
return source.generateParams('slug', 'locale'); // new param name
}搜索
🌐 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 获取语言环境，并将其添加到 href 前面。
🌐 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, and prepend it to href.
import Link from 'next/link';
import { useParams } from 'next/navigation';
const { lang } = useParams();
return <Link href={`/${lang}/another-page`}>This is a link</Link>;此外，fumadocs-core/dynamic-link 组件支持动态 href，你可以用它来添加语言前缀。这对 Markdown/MDX 内容非常有用。
🌐 In addition, the fumadocs-core/dynamic-link component supports dynamic hrefs, you can use it to prepend the locale prefix.
It is useful for Markdown/MDX content.
import { DynamicLink } from 'fumadocs-core/dynamic-link';
<DynamicLink href="/[lang]/another-page">This is a link</DynamicLink>Last updated on