vuepress-theme-plume/docs/en/notes/theme/guide/international.md

title, icon, createTime, permalink, tags

title	icon	createTime	permalink	tags
Internationalization	material-symbols-light:language	2025/03/04 13:12:03	/en/guide/international/	Guide i18n

Implementing ==internationalization== in the theme only requires some simple configurations.

Let's take an example of creating a project with Chinese as the default language and including English and French.

Directory Structure

First, you need to create a directory structure similar to the following:

::: file-tree

• docs
  • en # English directory
    • foo.md
    • README.md # English home page
  • fr # French directory
    • foo.md
    • README.md # French home page
  • foo.md
  • README.md # Chinese home page :::

Here, docs/en/ is used to store English documents, docs/fr/ stores French documents, and Chinese documents are stored directly under docs/.

::: important Consistent directory and file names across languages Try to keep the file names and directory names consistent across different language directories. This helps the theme correctly navigate to different language versions of the article when switching languages. :::

VuePress Configuration

Default Language

In .vuepress/config.ts, declare the default language:

::: code-tabs @tab .vuepress/config.ts

import { defineUserConfig } from 'vuepress'

export default defineUserConfig({
  // Declare the default language
  lang: 'zh-CN', // [!code ++]
  // Locales supported under multilingual
  locales: {
    '/': { lang: 'zh-CN', title: '博客' }, // Default language is Simplified Chinese
  }
})

:::

Adding Other Languages

You need to set the lang option for each language. Even if you are only using a single language, you must set lang in .vuepress/config.{js,ts}.

::: tip Why do this? To provide the correct locale text, the theme needs to know which language is being used in the root folder and each multilingual folder. :::

Configure in .vuepress/config.ts:

::: code-tabs @tab .vuepress/config.ts

import { defineUserConfig } from 'vuepress'

export default defineUserConfig({
  // Declare the default language
  lang: 'zh-CN',
  // Locales supported under multilingual
  locales: {
    // Configure languages under different paths
    '/': { lang: 'zh-CN', title: '博客' }, // Default language is Simplified Chinese
    '/en/': { lang: 'en-US', title: 'Blog' }, // English // [!code ++]
    '/fr/': { lang: 'fr-FR', title: 'Le blog' }, // French // [!code ++]
  }
})

:::

The key in the locales configuration acts as the localePath, corresponding to the language path under the docs directory, and should have the same naming.

At the same time, the key (localePath) will also serve as the prefix for the page access links of different languages.

::: important Language codes The key in the locales configuration, i.e., localePath, must comply with the ISO 639 standard. For non-default languages, such as English, it should be /en/.

In locales[localePath], lang is the language code for the current language. Please use the standard BCP47 language code. For example, English should be en-US (indicating English (United States)). :::

Theme Configuration

In the theme configuration, the locales configuration item is also used for multilingual configuration.

locales supports all theme configuration items.

::: code-tabs @tab .vuepress/config.ts

import { plumeTheme } from '@vuepress-plume/vuepress-theme-plume'
import { defineUserConfig } from 'vuepress'

export default defineUserConfig({
  lang: 'zh-CN',
  locales: {
    '/': { lang: 'zh-CN', title: '博客' }, // Default language is Simplified Chinese
    '/en/': { lang: 'en-US', title: 'Blog' }, // English
    '/fr/': { lang: 'fr-FR', title: 'Le blog' }, // French
  },
  theme: plumeTheme({
    // Multilingual configuration within the theme
    locales: {
      '/': { // [!code hl]
        // The text displayed in the navigation bar language dropdown menu for the current language
        selectLanguageName: '简体中文',
        navbar: [
          { text: '首页', link: '/' },
          { text: '博客', link: '/blog/' },
        ]
      },
      '/en/': { // [!code hl]
        selectLanguageName: 'English',
        navbar: [
          { text: 'Home', link: '/en/' },
          { text: 'Blog', link: '/en/blog/' },
        ]
      },
      '/fr/': { // [!code hl]
        selectLanguageName: 'Français',
        navbar: [
          { text: 'Accueil', link: '/fr/' },
          { text: 'Le Blog', link: '/fr/blog/' },
        ]
      }
    }
  })
})

:::

The key in the theme theme.locales configuration should be consistent with the key in the locales configuration of vuepress.

You should configure selectLanguageName for theme.locales[localePath] to display the name of the current language in the navigation bar language dropdown menu.

For more locales configuration, please refer to

• Theme Configuration > Locales Configuration - Configure the behavior of the theme under different languages.
• Theme Configuration > Multilingual Configuration - Configure text related to languages.