---
title: 国际化
description: 为您的文档站点添加多语言支持
type: guide
summary: 通过 Geistdocs CLI 和 Fumadocs 路由实现多语言文档自动翻译。
prerequisites:
  - /docs/getting-started
related:
  - /docs/configuration
---

Geistdocs 支持开箱即用的国际化 (i18n)，使用 Fumadocs 的语言感知路由。您可以通过 Geistdocs CLI 提供多语言文档并使用自动翻译。

## 工作原理

i18n 系统使用带有 `[lang]` URL 段的动态路由。默认语言（英语）不会显示在 URL 中，而其他语言会获得前缀：

- `/docs/getting-started` - 英语（默认）
- `/cn/docs/getting-started` - 中文

用户可以使用导航栏中的语言选择器切换语言。

## 翻译内容

使用 Geistdocs CLI 自动翻译您的 MDX 文件：

```bash
npx @vercel/geistdocs translate
```

CLI 会从 `geistdocs.tsx` 中读取目标语言并提示您选择要翻译的文件。

翻译由 Geistdocs 平台生成，并与原始文件并存保存在带有区域后缀的文件中（例如，`introduction.cn.mdx`）。

### 命令选项

您可以直接传递选项以跳过交互式提示：

```bash
# Translate files using the default glob pattern
npx @vercel/geistdocs translate

# Translate files matching a specific glob pattern
npx @vercel/geistdocs translate "content/docs/**/*.mdx"

# Use a custom config file
npx @vercel/geistdocs translate "content/**/*.mdx" --config custom-config.tsx
```

| 选项        | 描述                                                       |
| ----------- | ---------------------------------------------------------- |
| `--config`  | 含有翻译配置的配置文件路径（默认：`geistdocs.tsx`）        |
| `--url`     | 自定义翻译 API URL                                          |

### 批量处理

当翻译多个文件时，CLI 会自动将它们分成每组 10 个的批次，以避免速率限制。每个批次完成时都会显示进度。

## 配置

在 `geistdocs.tsx` 中配置支持的语言：

```typescript title="geistdocs.tsx"
export const translations = {
  en: {
    displayName: "English",
  },
  cn: {
    displayName: "中文",
    search: "搜尋文檔",
  },
};
```

`translations` 对象中的第一个区域设置被视为默认/源语言，并且不会作为翻译目标。

### 添加新语言

添加新语言的步骤：

1. 在 `translations` 对象中添加带有语言代码的新键
2. 为诸如 `displayName` 和 `search` 之类的 UI 元素添加翻译
3. 运行 `npx @vercel/geistdocs translate "content/**/*.mdx"` 以生成翻译内容

语言选择器将自动包含您添加的新语言。

## 内容组织

翻译后的文件与原始文件并存并带有语言后缀保存：

```
content/docs/
├── getting-started.mdx      # English (default)
├── getting-started.cn.mdx   # Chinese
├── getting-started.fr.mdx   # French
└── getting-started.es.mdx   # Spanish
```

Fumadocs 会根据 URL 路径自动提供正确的文件。

## 翻译 UI 元素

`geistdocs.tsx` 中的 `translations` 对象控制诸如搜索占位符、导航标签和错误消息等 UI 文本。为您支持的每种语言添加相应的翻译。

如果您没有为某个特定元素提供翻译，则会回退到英语。

## 语言检测

语言由 URL 路径确定。不根据浏览器设置进行自动检测——用户必须使用语言选择器显式选择他们的语言。

这种方法为用户提供了完全的控制，并确保他们看到预期的语言。