> AI coding agents: see [/llms.txt](/llms.txt) for the full documentation index. Markdown version: [/docs/manual/zh/concepts/internationalization.md](/docs/manual/zh/concepts/internationalization.md).

---
title: 国际化
description: 使用 TockDocs 内置的 i18n 支持创建多语言文档。
navigation:
  icon: i-lucide-globe
seo:
  description: 学习如何使用 TockDocs 内置的 i18n 支持设置和管理多语言文档。
  title: 国际化
---

TockDocs 在其两种内容模式下均支持国际化：

- **传统模式** — 带语言前缀的路由，如 `/en/...` 和 `/zh/...`
- **知识库模式** — 知识库感知路由，如 `/docs/manual/en/...` 和 `/docs/manual/zh/...`

## TockDocs 为您处理的内容

- 语言感知的内容集合
- 语言感知的路由生成
- 文档页面的语言切换器
- 过滤没有实际内容的语言
- 当不同知识库提供不同语言集时的知识库感知语言行为

## 单语言站点

如果您的站点是单语言的且不使用完整的 `@nuxtjs/i18n` 模块，您仍然可以在 `app.config.ts` 中设置 UI 语言：

```ts [app/app.config.ts]
export default defineAppConfig({
  tockdocs: {
    locale: 'zh',
  },
})
```

这主要用于内置 UI 字符串和文档语言元数据。

## 使用 `@nuxtjs/i18n` 的多语言设置

对于真正的本地化文档，请在 `nuxt.config.ts` 中配置 `@nuxtjs/i18n`：

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  modules: ['@nuxtjs/i18n'],
  i18n: {
    defaultLocale: 'en',
    locales: [
      { code: 'en', name: 'English' },
      { code: 'zh', name: '简体中文' },
    ],
  },
})
```

::warning
TockDocs 强制文档路由策略为 `prefix`，以确保本地化文档路由保持明确。
::

## 传统模式内容结构

在传统模式下，按语言组织内容：

```bash
content/
├── en/
│   ├── index.md
│   └── 1.getting-started/
└── zh/
    ├── index.md
    └── 1.getting-started/
```

典型路由：

- `content/en/index.md` → `/en`
- `content/zh/1.getting-started/3.installation.md` → `/zh/getting-started/installation`

## 知识库模式内容结构

在知识库模式下，语言位于每个知识库内部：

```bash
content/
├── site/
│   └── index.md
└── manual/
    ├── kb.yml
    ├── en/
    │   └── 1.getting-started/
    └── zh/
        └── 1.getting-started/
```

`kb.yml` 示例：

```yaml [content/manual/kb.yml]
id: manual
title: Manual
defaultLocale: en
locales:
  - en
  - zh
entry: getting-started/installation
```

典型路由：

- `/docs/manual/en/getting-started/installation`
- `/docs/manual/zh/getting-started/installation`

## 语言过滤

TockDocs 只注册有实际内容支持的语言。

这意味着：

- 仅在 `i18n.locales` 中声明语言是不够的
- 对应的内容目录也必须存在
- 在知识库模式下，语言可用性按每个知识库评估

示例：

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  modules: ['@nuxtjs/i18n'],
  i18n: {
    defaultLocale: 'en',
    locales: ['en', 'zh', 'ja'],
  },
})
```

如果您的内容只存在于 `en` 和 `zh`，那么 `ja` 将在文档路由中被跳过。

## 知识库模式下的混合语言数量

知识库模式支持每个知识库拥有不同数量的语言。

例如：

- `manual` 可以提供 `en` 和 `zh`
- `parser` 可以只提供 `en`

在这种情况下：

- 语言切换器出现在多语言知识库上
- 在单语言知识库上保持隐藏

## 默认语言要求

务必确保您配置的默认语言在内容中实际存在：

- 传统模式：`content/<defaultLocale>/...`
- 知识库模式：`content/<kb>/<defaultLocale>/...`

如果某个文档语言缺失，TockDocs 会尽可能回退到知识库或站点的默认语言。

## 起步模板

如果您想要一个预配置的本地化起步模板，请使用：

```bash [Terminal]
npx create-tockdocs my-docs -t i18n
```

该起步模板使用传统模式，包含语言文件夹，且 `@nuxtjs/i18n` 已预先配置。