国际化

Docus 基于 @nuxtjs/i18n 模块提供原生国际化支持，让你可以通过自动路由和内容管理创建多语言文档。

功能

• 内置 i18n 模块：原生集成 @nuxtjs/i18n
• 动态 locale 路由：自动为 URL 添加语言代码前缀（/en/docs、/zh-cn/docs）
• 按 locale 分离内容 collection：每种语言拥有独立的内容管理
• 语言切换器：内置用于切换 locale 的组件
• 单语言配置：单语言站点可以通过 app.config.ts 配置 locale

单语言配置

如果你正在构建单语言文档（不使用完整的 @nuxtjs/i18n 模块），可以通过 app.config.ts 配置 locale。这适用于设置 UI 组件语言和本地化内置字符串。

export default defineAppConfig({
  docus: {
    locale: 'zh-cn', // 设置 locale（默认：'en'）
  }
})

多语言设置

对于多语言文档，请使用下面介绍的完整 @nuxtjs/i18n 集成。

设置现有项目

要在 Docus 项目中启用 i18n，请将 @nuxtjs/i18n 模块添加到 nuxt.config.ts，并定义 locales：

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

使用 i18n 模板创建新项目

创建新项目时，你可以选择预配置国际化能力的 i18n 模板：

npx create-docus my-docs -t i18n

目录结构

启用 i18n 后，请在 content/ 目录中按 locale 组织内容：

content/
├── en/                    # 英文内容
│   ├── index.md           # 英文首页
│   ├── getting-started/
│   │   ├── installation.md
│   │   └── configuration.md
│   └── guide/
│       └── advanced.md
└── zh-cn/                 # 简体中文内容
    ├── index.md           # 简体中文首页
    ├── getting-started/
    │   ├── installation.md
    │   └── configuration.md
    └── guide/
        └── advanced.md

Locale fallback

如果某个 locale 不存在于你的 content/ 目录中，Docus 会发出警告并跳过该 locale。缺失的 locale 不会被注册。

Docus 会从 Nuxt 配置中检测 locales：

export default defineNuxtConfig({
  modules: ['@nuxtjs/i18n'],
  i18n: {
    locales: ['en', 'zh-cn', 'ja'],
    defaultLocale: 'en'
  }
})

但只会根据 content/ 文件夹结构注册实际存在的 locale：

content/
├─ en/           # 已注册 ✅
├─ zh-cn/        # 已注册 ✅（如果存在）
└─ ja/           # 已跳过 🚫（如果缺失）

如果用户请求缺失的文档 locale，Docus 会重定向到默认 locale。