From c2d3cdccf9c710be1cbf943a92cbf6053d2a9e92 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Thu, 15 Jan 2026 09:52:10 +0000
Subject: [PATCH 1/2] Initial plan


From 770fc07201ad689b88b2a9e68cdefc6e0b0aecd8 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Thu, 15 Jan 2026 10:19:25 +0000
Subject: [PATCH 2/2] Add comprehensive multi-language documentation guide

Co-authored-by: huangyiirene <7665279+huangyiirene@users.noreply.github.com>
---
 README.md                         |  62 +++++-
 content/docs/i18n-guide.en.mdx    | 334 ++++++++++++++++++++++++++++++
 content/docs/i18n-guide.zh-CN.mdx | 334 ++++++++++++++++++++++++++++++
 content/docs/meta.en.json         |   2 +-
 content/docs/meta.zh-CN.json      |   2 +-
 5 files changed, 731 insertions(+), 3 deletions(-)
 create mode 100644 content/docs/i18n-guide.en.mdx
 create mode 100644 content/docs/i18n-guide.zh-CN.mdx

diff --git a/README.md b/README.md
index 78c7e76..8861402 100644
--- a/README.md
+++ b/README.md
@@ -1,7 +1,67 @@
 # docs
 
+A multi-language documentation site built with Fumadocs, supporting English and Chinese.
+
+## Features
+
+- 🌍 **Multi-language Support**: Full internationalization with English (en) and Chinese (zh-CN)
+- 📝 **MDX Content**: Write documentation using MDX for interactive content
+- 🔍 **Fast Search**: Quick search across all documentation
+- 🎨 **Modern UI**: Beautiful and responsive design with Fumadocs UI
+- 📱 **Mobile Friendly**: Fully responsive on all devices
+
+## Getting Started
+
+### Installation
+
+```bash
+npm install
+```
+
+### Development
+
+```bash
+npm run dev
+```
+
+Visit `http://localhost:3000` to view the documentation site.
+
+### Build
+
+```bash
+npm run build
+```
+
+### Production
+
+```bash
+npm start
+```
+
+## Building Multi-language Documentation
+
+For a comprehensive guide on how to build and maintain multi-language documentation, see the [Multi-language Documentation Guide](content/docs/i18n-guide.en.mdx) available in the documentation:
+
+- English: `/en/docs/i18n-guide`
+- Chinese: `/zh-CN/docs/i18n-guide`
+
+The guide covers:
+- Configuration setup
+- Creating multi-language content
+- File naming conventions
+- Adding new languages
+- Troubleshooting common issues
+
 ## Configuration Notes
 
 ### Internationalization (i18n)
 
-The default language is configured in `lib/i18n.ts` as `en`. If you change the default language, you must also update the redirect destination in `vercel.json` to match (currently `/en/docs`).
\ No newline at end of file
+The default language is configured in `lib/i18n.ts` as `en`. If you change the default language, you must also update the redirect destination in `vercel.json` to match (currently `/en/docs`).
+
+### Content Structure
+
+Content files are located in `content/docs/` and use language suffixes:
+- `{filename}.en.mdx` - English content
+- `{filename}.zh-CN.mdx` - Chinese content
+- `meta.en.json` - English navigation
+- `meta.zh-CN.json` - Chinese navigation
\ No newline at end of file
diff --git a/content/docs/i18n-guide.en.mdx b/content/docs/i18n-guide.en.mdx
new file mode 100644
index 0000000..65fd776
--- /dev/null
+++ b/content/docs/i18n-guide.en.mdx
@@ -0,0 +1,334 @@
+---
+title: Multi-language Documentation Guide
+description: Learn how to build and maintain multi-language documentation
+---
+
+# Multi-language Documentation Guide
+
+This guide explains how to build and maintain multi-language documentation using Fumadocs with internationalization (i18n) support.
+
+## Overview
+
+This documentation site supports multiple languages (currently English and Chinese) using Fumadocs' built-in i18n capabilities. The system allows you to:
+
+- Create content in multiple languages
+- Switch between languages seamlessly
+- Maintain separate translations for UI elements
+- Configure language-specific navigation
+
+## Configuration
+
+### 1. Define Supported Languages
+
+The i18n configuration is defined in `lib/i18n.ts`:
+
+```typescript
+import type { I18nConfig } from 'fumadocs-core/i18n';
+
+export const i18n: I18nConfig<'en' | 'zh-CN'> = {
+  defaultLanguage: 'en',
+  languages: ['en', 'zh-CN'],
+};
+```
+
+**Key Points:**
+- `defaultLanguage`: The fallback language when no language is specified
+- `languages`: Array of all supported language codes
+
+### 2. Configure UI Translations
+
+UI element translations are defined in `lib/i18n-ui.ts`:
+
+```typescript
+import type { Translations } from 'fumadocs-ui/i18n';
+
+export const cn: Partial<Translations> = {
+  search: '搜索文档',
+  searchNoResult: '没有结果',
+  toc: '目录',
+  tocNoHeadings: '没有标题',
+  lastUpdate: '最后更新',
+  chooseTheme: '选择主题',
+  previousPage: '上一页',
+  nextPage: '下一页',
+  chooseLanguage: '选择语言',
+};
+```
+
+### 3. Set Up Source Configuration
+
+In `lib/source.ts`, integrate i18n with your content source:
+
+```typescript
+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,
+});
+```
+
+### 4. Configure App Layout
+
+The language layout in `app/[lang]/layout.tsx` provides language context to child components:
+
+```typescript
+import { I18nProvider } from 'fumadocs-ui/contexts/i18n';
+import { defineI18nUI } from 'fumadocs-ui/i18n';
+
+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>;
+}
+```
+
+## Creating Multi-language Content
+
+### File Naming Convention
+
+Content files use language suffixes to distinguish between translations:
+
+```
+content/docs/
+├── index.en.mdx          # English version
+├── index.zh-CN.mdx       # Chinese version
+├── getting-started.en.mdx
+├── getting-started.zh-CN.mdx
+├── meta.en.json          # English navigation
+└── meta.zh-CN.json       # Chinese navigation
+```
+
+**Format:** `{filename}.{language-code}.mdx`
+
+### Content Structure
+
+Each MDX file should include frontmatter with title and description:
+
+**English (`index.en.mdx`):**
+```mdx
+---
+title: Welcome
+description: Welcome to the documentation
+---
+
+# Welcome to Our Documentation
+
+Content goes here...
+```
+
+**Chinese (`index.zh-CN.mdx`):**
+```mdx
+---
+title: 欢迎
+description: 欢迎访问文档
+---
+
+# 欢迎访问我们的文档
+
+内容在这里...
+```
+
+### Navigation Configuration
+
+Create language-specific navigation files using `meta.{language}.json`:
+
+**English (`meta.en.json`):**
+```json
+{
+  "title": "Documentation",
+  "pages": ["index", "getting-started"]
+}
+```
+
+**Chinese (`meta.zh-CN.json`):**
+```json
+{
+  "title": "文档",
+  "pages": ["index", "getting-started"]
+}
+```
+
+## Adding a New Language
+
+To add a new language (e.g., Spanish):
+
+1. **Update i18n configuration** (`lib/i18n.ts`):
+```typescript
+export const i18n: I18nConfig<'en' | 'zh-CN' | 'es'> = {
+  defaultLanguage: 'en',
+  languages: ['en', 'zh-CN', 'es'],
+};
+```
+
+2. **Add UI translations** (`lib/i18n-ui.ts`):
+```typescript
+export const es: Partial<Translations> = {
+  search: 'Buscar documentación',
+  searchNoResult: 'Sin resultados',
+  toc: 'Tabla de contenidos',
+  // ... other translations
+};
+```
+
+3. **Update layout configuration** (`app/[lang]/layout.tsx`):
+```typescript
+const i18nConfig = defineI18nUI(i18n, {
+  translations: {
+    en: { displayName: 'English' },
+    'zh-CN': { ...cn, displayName: '简体中文' },
+    es: { ...es, displayName: 'Español' },
+  },
+});
+```
+
+4. **Create content files**:
+```
+content/docs/
+├── index.es.mdx
+├── getting-started.es.mdx
+└── meta.es.json
+```
+
+## Default Language Redirect
+
+Configure the root redirect in `vercel.json`:
+
+```json
+{
+  "redirects": [
+    {
+      "source": "/",
+      "destination": "/en/docs",
+      "permanent": true
+    }
+  ]
+}
+```
+
+**Note:** If you change the default language in `lib/i18n.ts`, update the destination path in `vercel.json` accordingly.
+
+## URL Structure
+
+The documentation uses language-prefixed URLs:
+
+```
+/en/docs              → English documentation home
+/en/docs/getting-started  → English getting started page
+/zh-CN/docs           → Chinese documentation home
+/zh-CN/docs/getting-started → Chinese getting started page
+```
+
+## Best Practices
+
+1. **Consistency**: Keep the same page structure across all languages
+2. **Complete translations**: Ensure all pages have translations for all supported languages
+3. **Meta files**: Always create matching `meta.{lang}.json` files for proper navigation
+4. **Fallback**: The default language serves as a fallback if a translation is missing
+5. **Testing**: Test all language versions before deploying
+
+## Building and Testing
+
+Build the documentation:
+```bash
+npm run build
+```
+
+Run the development server:
+```bash
+npm run dev
+```
+
+The build process will generate static pages for all language variants.
+
+## Troubleshooting
+
+### Page not found for specific language
+
+**Problem:** A page works in one language but returns 404 in another.
+
+**Solution:** Ensure both `{page}.{lang1}.mdx` and `{page}.{lang2}.mdx` files exist with the same base filename.
+
+### Navigation not showing correctly
+
+**Problem:** Sidebar navigation is missing or incorrect.
+
+**Solution:** Check that `meta.{lang}.json` files exist for all languages and contain the correct page references.
+
+### Language switcher not appearing
+
+**Problem:** Language selector is not visible in the UI.
+
+**Solution:** Verify that:
+- Multiple languages are defined in `lib/i18n.ts`
+- `I18nProvider` is properly configured in `app/[lang]/layout.tsx`
+- UI translations include language names with `displayName`
+
+### Wrong default language
+
+**Problem:** Site redirects to incorrect language.
+
+**Solution:** 
+- Check `defaultLanguage` in `lib/i18n.ts`
+- Update redirect destination in `vercel.json` to match
+- Clear browser cache and rebuild
+
+## Example Repository Structure
+
+```
+docs/
+├── app/
+│   ├── [lang]/
+│   │   ├── docs/
+│   │   │   ├── [[...slug]]/
+│   │   │   │   └── page.tsx
+│   │   │   └── layout.tsx
+│   │   ├── layout.tsx
+│   │   └── page.tsx
+│   ├── layout.config.tsx
+│   ├── layout.tsx
+│   └── page.tsx
+├── content/
+│   └── docs/
+│       ├── index.en.mdx
+│       ├── index.zh-CN.mdx
+│       ├── getting-started.en.mdx
+│       ├── getting-started.zh-CN.mdx
+│       ├── meta.en.json
+│       └── meta.zh-CN.json
+├── lib/
+│   ├── i18n.ts
+│   ├── i18n-ui.ts
+│   └── source.ts
+└── vercel.json
+```
+
+## Next Steps
+
+- Add more content pages in multiple languages
+- Customize UI translations for your specific needs
+- Consider adding more languages based on your audience
+- Set up automated translation workflows if needed
diff --git a/content/docs/i18n-guide.zh-CN.mdx b/content/docs/i18n-guide.zh-CN.mdx
new file mode 100644
index 0000000..245b7ab
--- /dev/null
+++ b/content/docs/i18n-guide.zh-CN.mdx
@@ -0,0 +1,334 @@
+---
+title: 多语言文档指南
+description: 学习如何构建和维护多语言文档
+---
+
+# 多语言文档指南
+
+本指南介绍如何使用 Fumadocs 的国际化（i18n）支持来构建和维护多语言文档。
+
+## 概述
+
+本文档站点支持多种语言（目前支持英语和中文），使用 Fumadocs 内置的 i18n 功能。该系统允许您：
+
+- 创建多语言内容
+- 无缝切换语言
+- 维护 UI 元素的独立翻译
+- 配置特定语言的导航
+
+## 配置
+
+### 1. 定义支持的语言
+
+i18n 配置定义在 `lib/i18n.ts` 中：
+
+```typescript
+import type { I18nConfig } from 'fumadocs-core/i18n';
+
+export const i18n: I18nConfig<'en' | 'zh-CN'> = {
+  defaultLanguage: 'en',
+  languages: ['en', 'zh-CN'],
+};
+```
+
+**关键点：**
+- `defaultLanguage`：未指定语言时的后备语言
+- `languages`：所有支持的语言代码数组
+
+### 2. 配置 UI 翻译
+
+UI 元素的翻译定义在 `lib/i18n-ui.ts` 中：
+
+```typescript
+import type { Translations } from 'fumadocs-ui/i18n';
+
+export const cn: Partial<Translations> = {
+  search: '搜索文档',
+  searchNoResult: '没有结果',
+  toc: '目录',
+  tocNoHeadings: '没有标题',
+  lastUpdate: '最后更新',
+  chooseTheme: '选择主题',
+  previousPage: '上一页',
+  nextPage: '下一页',
+  chooseLanguage: '选择语言',
+};
+```
+
+### 3. 设置源配置
+
+在 `lib/source.ts` 中，将 i18n 与您的内容源集成：
+
+```typescript
+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,
+});
+```
+
+### 4. 配置应用布局
+
+`app/[lang]/layout.tsx` 中的语言布局为子组件提供语言上下文：
+
+```typescript
+import { I18nProvider } from 'fumadocs-ui/contexts/i18n';
+import { defineI18nUI } from 'fumadocs-ui/i18n';
+
+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>;
+}
+```
+
+## 创建多语言内容
+
+### 文件命名规范
+
+内容文件使用语言后缀来区分不同的翻译：
+
+```
+content/docs/
+├── index.en.mdx          # 英文版本
+├── index.zh-CN.mdx       # 中文版本
+├── getting-started.en.mdx
+├── getting-started.zh-CN.mdx
+├── meta.en.json          # 英文导航
+└── meta.zh-CN.json       # 中文导航
+```
+
+**格式：** `{文件名}.{语言代码}.mdx`
+
+### 内容结构
+
+每个 MDX 文件都应该包含带有标题和描述的前置元数据：
+
+**英文 (`index.en.mdx`)：**
+```mdx
+---
+title: Welcome
+description: Welcome to the documentation
+---
+
+# Welcome to Our Documentation
+
+Content goes here...
+```
+
+**中文 (`index.zh-CN.mdx`)：**
+```mdx
+---
+title: 欢迎
+description: 欢迎访问文档
+---
+
+# 欢迎访问我们的文档
+
+内容在这里...
+```
+
+### 导航配置
+
+使用 `meta.{语言}.json` 创建特定语言的导航文件：
+
+**英文 (`meta.en.json`)：**
+```json
+{
+  "title": "Documentation",
+  "pages": ["index", "getting-started"]
+}
+```
+
+**中文 (`meta.zh-CN.json`)：**
+```json
+{
+  "title": "文档",
+  "pages": ["index", "getting-started"]
+}
+```
+
+## 添加新语言
+
+添加新语言（例如西班牙语）的步骤：
+
+1. **更新 i18n 配置** (`lib/i18n.ts`)：
+```typescript
+export const i18n: I18nConfig<'en' | 'zh-CN' | 'es'> = {
+  defaultLanguage: 'en',
+  languages: ['en', 'zh-CN', 'es'],
+};
+```
+
+2. **添加 UI 翻译** (`lib/i18n-ui.ts`)：
+```typescript
+export const es: Partial<Translations> = {
+  search: 'Buscar documentación',
+  searchNoResult: 'Sin resultados',
+  toc: 'Tabla de contenidos',
+  // ... 其他翻译
+};
+```
+
+3. **更新布局配置** (`app/[lang]/layout.tsx`)：
+```typescript
+const i18nConfig = defineI18nUI(i18n, {
+  translations: {
+    en: { displayName: 'English' },
+    'zh-CN': { ...cn, displayName: '简体中文' },
+    es: { ...es, displayName: 'Español' },
+  },
+});
+```
+
+4. **创建内容文件**：
+```
+content/docs/
+├── index.es.mdx
+├── getting-started.es.mdx
+└── meta.es.json
+```
+
+## 默认语言重定向
+
+在 `vercel.json` 中配置根路径重定向：
+
+```json
+{
+  "redirects": [
+    {
+      "source": "/",
+      "destination": "/en/docs",
+      "permanent": true
+    }
+  ]
+}
+```
+
+**注意：** 如果您在 `lib/i18n.ts` 中更改了默认语言，请相应更新 `vercel.json` 中的目标路径。
+
+## URL 结构
+
+文档使用带语言前缀的 URL：
+
+```
+/en/docs              → 英文文档首页
+/en/docs/getting-started  → 英文快速开始页面
+/zh-CN/docs           → 中文文档首页
+/zh-CN/docs/getting-started → 中文快速开始页面
+```
+
+## 最佳实践
+
+1. **一致性**：在所有语言中保持相同的页面结构
+2. **完整翻译**：确保所有页面都有所有支持语言的翻译
+3. **元文件**：始终为正确的导航创建匹配的 `meta.{语言}.json` 文件
+4. **后备**：如果缺少翻译，默认语言将作为后备
+5. **测试**：在部署前测试所有语言版本
+
+## 构建和测试
+
+构建文档：
+```bash
+npm run build
+```
+
+运行开发服务器：
+```bash
+npm run dev
+```
+
+构建过程将为所有语言变体生成静态页面。
+
+## 故障排除
+
+### 特定语言的页面未找到
+
+**问题：** 页面在一种语言中有效，但在另一种语言中返回 404。
+
+**解决方案：** 确保 `{页面}.{语言1}.mdx` 和 `{页面}.{语言2}.mdx` 文件都存在且具有相同的基本文件名。
+
+### 导航显示不正确
+
+**问题：** 侧边栏导航缺失或不正确。
+
+**解决方案：** 检查所有语言的 `meta.{语言}.json` 文件是否存在并包含正确的页面引用。
+
+### 语言切换器未出现
+
+**问题：** 语言选择器在 UI 中不可见。
+
+**解决方案：** 验证：
+- 在 `lib/i18n.ts` 中定义了多种语言
+- `I18nProvider` 在 `app/[lang]/layout.tsx` 中正确配置
+- UI 翻译包含带有 `displayName` 的语言名称
+
+### 错误的默认语言
+
+**问题：** 网站重定向到错误的语言。
+
+**解决方案：**
+- 检查 `lib/i18n.ts` 中的 `defaultLanguage`
+- 更新 `vercel.json` 中的重定向目标以匹配
+- 清除浏览器缓存并重新构建
+
+## 示例仓库结构
+
+```
+docs/
+├── app/
+│   ├── [lang]/
+│   │   ├── docs/
+│   │   │   ├── [[...slug]]/
+│   │   │   │   └── page.tsx
+│   │   │   └── layout.tsx
+│   │   ├── layout.tsx
+│   │   └── page.tsx
+│   ├── layout.config.tsx
+│   ├── layout.tsx
+│   └── page.tsx
+├── content/
+│   └── docs/
+│       ├── index.en.mdx
+│       ├── index.zh-CN.mdx
+│       ├── getting-started.en.mdx
+│       ├── getting-started.zh-CN.mdx
+│       ├── meta.en.json
+│       └── meta.zh-CN.json
+├── lib/
+│   ├── i18n.ts
+│   ├── i18n-ui.ts
+│   └── source.ts
+└── vercel.json
+```
+
+## 下一步
+
+- 添加多语言内容页面
+- 根据您的特定需求自定义 UI 翻译
+- 根据您的受众考虑添加更多语言
+- 如果需要，设置自动化翻译工作流程
diff --git a/content/docs/meta.en.json b/content/docs/meta.en.json
index 0261304..e933264 100644
--- a/content/docs/meta.en.json
+++ b/content/docs/meta.en.json
@@ -1,4 +1,4 @@
 {
   "title": "Documentation",
-  "pages": ["index", "getting-started"]
+  "pages": ["index", "getting-started", "i18n-guide"]
 }
diff --git a/content/docs/meta.zh-CN.json b/content/docs/meta.zh-CN.json
index 6b01f4c..77f28d8 100644
--- a/content/docs/meta.zh-CN.json
+++ b/content/docs/meta.zh-CN.json
@@ -1,4 +1,4 @@
 {
   "title": "文档",
-  "pages": ["index", "getting-started"]
+  "pages": ["index", "getting-started", "i18n-guide"]
 }