Set up Fumadocs with internationalization support

Copilot · huangyiirene · Copilot · commit a7dbb5598e32 · 2026-01-15T05:27:51.000Z
Co-authored-by: huangyiirene &lt;7665279+huangyiirene@users.noreply.github.com&gt;
diff --git a/.gitignore b/.gitignore
@@ -0,0 +1,36 @@
+# dependencies
+/node_modules
+/.pnp
+.pnp.js
+
+# testing
+/coverage
+
+# next.js
+/.next/
+/out/
+
+# production
+/build
+
+# misc
+.DS_Store
+*.pem
+
+# debug
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+# local env files
+.env*.local
+
+# vercel
+.vercel
+
+# typescript
+*.tsbuildinfo
+next-env.d.ts
+
+# fumadocs
+.source
diff --git a/app/[lang]/docs/[[...slug]]/page.tsx b/app/[lang]/docs/[[...slug]]/page.tsx
@@ -0,0 +1,48 @@
+import { source } from '@/lib/source';
+import type { Metadata } from 'next';
+import { DocsPage, DocsBody } from 'fumadocs-ui/page';
+import { notFound } from 'next/navigation';
+
+interface PageProps {
+  params: Promise<{
+    lang: string;
+    slug?: string[];
+  }>;
+}
+
+export default async function Page({ params }: PageProps) {
+  const { lang, slug = [] } = await params;
+  
+  const page = source.getPage(slug, lang);
+  
+  if (!page) {
+    notFound();
+  }
+
+  const MDX = page.data.body as any;
+
+  return (
+    <DocsPage toc={page.data.toc as any} full={page.data.full as any}>
+      <DocsBody>
+        <h1>{page.data.title}</h1>
+        <MDX />
+      </DocsBody>
+    </DocsPage>
+  );
+}
+
+export async function generateStaticParams() {
+  return source.generateParams();
+}
+
+export async function generateMetadata({ params }: PageProps): Promise<Metadata> {
+  const { lang, slug = [] } = await params;
+  const page = source.getPage(slug, lang);
+
+  if (!page) notFound();
+
+  return {
+    title: page.data.title,
+    description: page.data.description,
+  };
+}
diff --git a/app/[lang]/docs/layout.tsx b/app/[lang]/docs/layout.tsx
@@ -0,0 +1,23 @@
+import { source } from '@/lib/source';
+import { DocsLayout } from 'fumadocs-ui/layouts/docs';
+import type { ReactNode } from 'react';
+import { baseOptions } from '@/app/layout.config';
+
+export default async function Layout({
+  params,
+  children,
+}: {
+  params: Promise<{ lang: string }>;
+  children: ReactNode;
+}) {
+  const { lang } = await params;
+  
+  return (
+    <DocsLayout
+      tree={source.getPageTree(lang)}
+      {...baseOptions}
+    >
+      {children}
+    </DocsLayout>
+  );
+}
diff --git a/app/[lang]/layout.tsx b/app/[lang]/layout.tsx
@@ -0,0 +1,38 @@
+import { I18nProvider } from 'fumadocs-ui/contexts/i18n';
+import { defineI18nUI } from 'fumadocs-ui/i18n';
+import type { ReactNode } from 'react';
+import { i18n } from '@/lib/i18n';
+import { cn } from '@/lib/i18n-ui';
+
+const translations = {
+  'zh-CN': cn,
+};
+
+const i18nConfig = defineI18nUI(i18n, {
+  translations: {
+    en: {
+      displayName: 'English',
+    },
+    'zh-CN': {
+      ...cn,
+      displayName: '简体中文',
+    },
+  },
+});
+
+export default async function LangLayout({
+  params,
+  children,
+}: {
+  params: Promise<{ lang: string }>;
+  children: ReactNode;
+}) {
+  const { lang } = await params;
+  const providerProps = i18nConfig.provider(lang);
+  
+  return <I18nProvider {...providerProps}>{children}</I18nProvider>;
+}
+
+export async function generateStaticParams() {
+  return i18n.languages.map((lang) => ({ lang }));
+}
diff --git a/app/[lang]/page.tsx b/app/[lang]/page.tsx
@@ -0,0 +1,10 @@
+import { redirect } from 'next/navigation';
+
+export default async function LangPage({
+  params,
+}: {
+  params: Promise<{ lang: string }>;
+}) {
+  const { lang } = await params;
+  redirect(`/${lang}/docs`);
+}
diff --git a/app/layout.config.tsx b/app/layout.config.tsx
@@ -0,0 +1,14 @@
+import { type BaseLayoutProps } from 'fumadocs-ui/layouts/shared';
+
+export const baseOptions: BaseLayoutProps = {
+  nav: {
+    title: 'My Docs',
+  },
+  links: [
+    {
+      text: 'Documentation',
+      url: '/docs',
+      active: 'nested-url',
+    },
+  ],
+};
diff --git a/app/layout.tsx b/app/layout.tsx
@@ -0,0 +1,13 @@
+import 'fumadocs-ui/style.css';
+import { RootProvider } from 'fumadocs-ui/provider/next';
+import type { ReactNode } from 'react';
+
+export default function RootLayout({ children }: { children: ReactNode }) {
+  return (
+    <html lang="en" suppressHydrationWarning>
+      <body className="flex flex-col min-h-screen">
+        <RootProvider>{children}</RootProvider>
+      </body>
+    </html>
+  );
+}
diff --git a/app/page.tsx b/app/page.tsx
@@ -0,0 +1,5 @@
+import { redirect } from 'next/navigation';
+
+export default function HomePage() {
+  redirect('/en/docs');
+}
diff --git a/content/docs/en/getting-started.mdx b/content/docs/en/getting-started.mdx
@@ -0,0 +1,25 @@
+---
+title: Getting Started
+description: Learn how to get started with this documentation
+---
+
+# Getting Started
+
+This guide will help you get started with our documentation.
+
+## Installation
+
+To use this documentation site locally:
+
+```bash
+npm install
+npm run dev
+```
+
+## Navigation
+
+Use the sidebar to navigate through different sections. The search bar at the top allows you to quickly find specific topics.
+
+## Language Support
+
+Click on the language selector in the navigation bar to switch between English and Chinese.
diff --git a/content/docs/en/index.mdx b/content/docs/en/index.mdx
@@ -0,0 +1,19 @@
+---
+title: Welcome
+description: Welcome to the documentation
+---
+
+# Welcome to Our Documentation
+
+This is a documentation site built with Fumadocs that supports internationalization.
+
+## Features
+
+- **Multi-language Support**: Switch between English and Chinese
+- **Fast Search**: Quick search across all documentation
+- **Beautiful UI**: Modern and responsive design
+- **MDX Support**: Write docs with MDX for interactive content
+
+## Getting Started
+
+Explore the documentation using the sidebar navigation. You can switch languages using the language selector in the top navigation bar.
diff --git a/content/docs/en/meta.json b/content/docs/en/meta.json
@@ -0,0 +1,4 @@
+{
+  "title": "Documentation",
+  "pages": ["index", "getting-started"]
+}
diff --git a/content/docs/zh-CN/getting-started.mdx b/content/docs/zh-CN/getting-started.mdx
@@ -0,0 +1,25 @@
+---
+title: 快速开始
+description: 了解如何开始使用本文档
+---
+
+# 快速开始
+
+本指南将帮助您开始使用我们的文档。
+
+## 安装
+
+要在本地使用此文档网站：
+
+```bash
+npm install
+npm run dev
+```
+
+## 导航
+
+使用侧边栏浏览不同的部分。顶部的搜索栏可以让您快速找到特定主题。
+
+## 语言支持
+
+点击导航栏中的语言选择器，在英语和中文之间切换。
diff --git a/content/docs/zh-CN/index.mdx b/content/docs/zh-CN/index.mdx
@@ -0,0 +1,19 @@
+---
+title: 欢迎
+description: 欢迎访问文档
+---
+
+# 欢迎访问我们的文档
+
+这是一个使用 Fumadocs 构建的文档网站，支持国际化。
+
+## 特性
+
+- **多语言支持**：在英语和中文之间切换
+- **快速搜索**：快速搜索所有文档
+- **美观界面**：现代化的响应式设计
+- **MDX 支持**：使用 MDX 编写交互式内容的文档
+
+## 开始使用
+
+使用侧边栏导航浏览文档。您可以使用顶部导航栏中的语言选择器切换语言。
diff --git a/content/docs/zh-CN/meta.json b/content/docs/zh-CN/meta.json
@@ -0,0 +1,4 @@
+{
+  "title": "文档",
+  "pages": ["index", "getting-started"]
+}
diff --git a/lib/i18n-ui.ts b/lib/i18n-ui.ts
@@ -0,0 +1,13 @@
+import type { Translations } from 'fumadocs-ui/i18n';
+
+export const cn: Partial<Translations> = {
+  search: '搜索文档',
+  searchNoResult: '没有结果',
+  toc: '目录',
+  tocNoHeadings: '没有标题',
+  lastUpdate: '最后更新',
+  chooseTheme: '选择主题',
+  previousPage: '上一页',
+  nextPage: '下一页',
+  chooseLanguage: '选择语言',
+};
diff --git a/lib/i18n.ts b/lib/i18n.ts
@@ -0,0 +1,8 @@
+import type { I18nConfig } from 'fumadocs-core/i18n';
+
+export const i18n: I18nConfig<'en' | 'zh-CN'> = {
+  defaultLanguage: 'en',
+  languages: ['en', 'zh-CN'],
+};
+
+export type Locale = (typeof i18n.languages)[number];
diff --git a/lib/source.ts b/lib/source.ts
@@ -0,0 +1,10 @@
+import { loader } from 'fumadocs-core/source';
+import { docs, meta } from '@/.source/server';
+import { toFumadocsSource } from 'fumadocs-mdx/runtime/server';
+import { i18n } from './i18n';
+
+export const source = loader({
+  baseUrl: '/docs',
+  source: toFumadocsSource(docs, meta),
+  i18n,
+});
diff --git a/mdx-components.tsx b/mdx-components.tsx
@@ -0,0 +1,9 @@
+import defaultComponents from 'fumadocs-ui/mdx';
+import type { MDXComponents } from 'mdx/types';
+
+export function useMDXComponents(components: MDXComponents): MDXComponents {
+  return {
+    ...defaultComponents,
+    ...components,
+  };
+}
diff --git a/middleware.ts b/middleware.ts
@@ -0,0 +1,9 @@
+import { createI18nMiddleware } from 'fumadocs-core/i18n/middleware';
+import { i18n } from './lib/i18n';
+
+export default createI18nMiddleware(i18n);
+
+export const config = {
+  // Matcher ignoring `/_next/` and `/api/`
+  matcher: ['/((?!api|_next/static|_next/image|favicon.ico).*)'],
+};
diff --git a/next.config.mjs b/next.config.mjs
@@ -0,0 +1,10 @@
+import { createMDX } from 'fumadocs-mdx/next';
+
+const withMDX = createMDX();
+
+/** @type {import('next').NextConfig} */
+const nextConfig = {
+  reactStrictMode: true,
+};
+
+export default withMDX(nextConfig);
diff --git a/package-lock.json b/package-lock.json
diff --git a/package.json b/package.json
diff --git a/source.config.ts b/source.config.ts
diff --git a/tsconfig.json b/tsconfig.json
