国际化

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

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

TockDocs 为您处理的内容

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

单语言站点

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

export default defineAppConfig({
  tockdocs: {
    locale: 'zh',
  },
})

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

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

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

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

传统模式内容结构

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

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

知识库模式内容结构

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

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

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 中声明语言是不够的
• 对应的内容目录也必须存在
• 在知识库模式下，语言可用性按每个知识库评估

示例：

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 会尽可能回退到知识库或站点的默认语言。

起步模板

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

npx create-tockdocs my-docs -t i18n

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