VitePress 国际化 (i18n)

VitePress 的默认主题内置了对国际化（i18n）的支持，可以帮助你轻松地为网站提供多语言版本。

文件结构

要启用 i18n，你需要按照特定的目录结构来组织你的多语言内容。你需要为每种语言创建一个以其语言代码命名的子目录，并将该语言的所有 Markdown 文件放入其中。

.
└── docs
    ├── en
    │   ├── guide.md
    │   └── index.md
    ├── fr
    │   ├── guide.md
    │   └── index.md
    └── index.md

• docs/en/ 和 docs/fr/ 分别包含了英语和法语的内容。
• 根目录下的 index.md 通常用作语言选择的着陆页，但这并非强制要求。

配置 i18n

接下来，你需要在 .vitepress/config.js 文件中配置 locales 选项。

// .vitepress/config.js
export default {
  themeConfig: {
    // ...
    // highlight-start
    locales: {
      root: {
        label: 'English',
        lang: 'en'
      },
      fr: {
        label: 'Français',
        lang: 'fr',
        // 为该语言的特定文本提供翻译
        themeConfig: {
          nav: [
            { text: 'Guide', link: '/fr/guide' }
          ],
          sidebar: {
            '/fr/': [
              { text: 'Guide', items: [{ text: 'Introduction', link: '/fr/guide' }] }
            ]
          }
        }
      }
    }
    // highlight-end
  }
}

locales 配置详解

• root: 这是你的默认语言（在此例中是英语）。label 是将显示在语言切换菜单中的文本，lang 是该语言的 HTML lang 属性。
• fr: 这是一个新的语言环境。键名（fr）必须与你在 docs 目录中创建的子目录名匹配。
  • label 和 lang 的作用同上。
  • 你可以在这里覆盖顶层的 themeConfig。例如，为法语版本提供一个完全不同的导航栏（nav）和侧边栏（sidebar）。注意链接需要包含 /fr/ 前缀。

默认主题的 i18n

配置完成后，默认主题会自动在导航栏的末尾添加一个语言切换器。它会根据你的 locales 配置显示一个下拉菜单，让用户可以在不同语言之间切换。

许多默认主题中的文本，如“编辑此页”、“上一页”、“下一页”等，也会根据 lang 配置自动翻译成对应的语言（目前支持英语、法语、日语、中文等）。你也可以在 locales 配置中为特定语言提供自定义翻译来覆盖默认文本。

// .vitepress/config.js
export default {
  themeConfig: {
    locales: {
      fr: {
        label: 'Français',
        lang: 'fr',
        // highlight-start
        themeConfig: {
          // ...
          editLink: {
            pattern: 'https://github.com/vuejs/vitepress/edit/main/docs/:path',
            text: 'Éditer cette page sur GitHub'
          }
        }
        // highlight-end
      }
    }
  }
}

通过这种方式，你可以为你的 VitePress 网站构建一个功能完善、体验良好的多语言版本。