VitePress Internationalization (i18n)

VitePress's default theme has built-in support for internationalization (i18n), helping you easily provide multi-language versions of your website.

File Structure

To enable i18n, you need to organize your multi-language content according to a specific directory structure. You need to create a subdirectory named after each language code and place all Markdown files for that language in it.

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

• docs/en/ and docs/fr/ contain English and French content, respectively.
• The index.md in the root directory is typically used as a landing page for language selection, but this is not required.

Configuring i18n

Next, you need to configure the locales option in the .vitepress/config.js file.

// .vitepress/config.js
export default {
  themeConfig: {
    // ...
    // highlight-start
    locales: {
      root: {
        label: 'English',
        lang: 'en'
      },
      fr: {
        label: 'Français',
        lang: 'fr',
        // Provide translations for language-specific text
        themeConfig: {
          nav: [
            { text: 'Guide', link: '/fr/guide' }
          ],
          sidebar: {
            '/fr/': [
              { text: 'Guide', items: [{ text: 'Introduction', link: '/fr/guide' }] }
            ]
          }
        }
      }
    }
    // highlight-end
  }
}

locales Configuration Explained

• root: This is your default language (English in this example). label is the text that will appear in the language switcher menu, and lang is the HTML lang attribute for that language.
• fr: This is a new locale. The key name (fr) must match the subdirectory name you created in the docs directory.
  • label and lang serve the same purpose as above.
  • You can override the top-level themeConfig here. For example, provide a completely different navbar (nav) and sidebar (sidebar) for the French version. Note that links need to include the /fr/ prefix.

Default Theme i18n

Once configured, the default theme will automatically add a language switcher to the end of the navbar. It will display a dropdown menu based on your locales configuration, allowing users to switch between different languages.

Many default theme texts, such as "Edit this page", "Previous page", "Next page", etc., will also be automatically translated to the corresponding language based on the lang configuration (currently supporting English, French, Japanese, Chinese, etc.). You can also provide custom translations for specific languages in the locales configuration to override the default text.

// .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
      }
    }
  }
}

Through this approach, you can build a fully functional, well-experienced multi-language version of your VitePress website.