This guide will help you quickly configure multi-language support for your VuePress theme. With simple directory structure and configuration adjustments, you can achieve a professional internationalized site.

Directory Structure Planning

First, create a directory structure that meets multi-language requirements. The following example shows a project layout supporting Chinese, English, and French:

docs

en# English documentation directory

foo.md

README.md# English homepage

fr# French documentation directory

foo.md

README.md# French homepage

foo.md

README.md# Chinese homepage

Directory Structure Explanation:

• docs/en/ - Stores English version documents
• docs/fr/ - Stores French version documents
• docs/ - Stores default language (Chinese) documents

::: Important Maintain File Structure Consistency Maintain identical file names and directory structures across different language directories. This ensures the theme can correctly navigate to the corresponding language version of documents during language switching. :::

VuePress Basic Configuration

Setting Default Language

Declare the default language in the configuration file .vuepress/config.ts:

.vuepress/config.ts

import { 
defineUserConfig
 } from 'vuepress'

export default 
defineUserConfig
({
  // Set default language code
  
lang
: 'zh-CN', 
  // Configure multi-language support
  
locales
: {
    '/': { 
lang
: 'zh-CN', 
title
: 'Blog' }, // Simplified Chinese as default language
  }
})

Adding Other Language Support

Extend the locales configuration to support more languages:

.vuepress/config.ts

import { 
defineUserConfig
 } from 'vuepress'

export default 
defineUserConfig
({
  
lang
: 'zh-CN',
  
locales
: {
    '/': { 
lang
: 'zh-CN', 
title
: 'Blog' }, // Simplified Chinese
    '/en/': { 
lang
: 'en-US', 
title
: 'Blog' }, // American English
    '/fr/': { 
lang
: 'fr-FR', 
title
: 'Le blog' }, // French
  }
})

Configuration Key Points:

• The keys in locales (such as /en/) correspond to language folder names in the documentation directory
• These keys also serve as access path prefixes for each language's pages
• Each language must have the correct lang attribute set, even if only using a single language

::: Tip Language Code Standards

• Path Keys: Follow ISO 639 standard (e.g., use /en/ for English)
• Language Codes: Use BCP47 standard format (e.g., use en-US for English) :::

Theme Multi-language Configuration

Customize interface elements for each language through the locales field in theme configuration:

.vuepress/config.ts

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

export default 
defineUserConfig
({
  
lang
: 'zh-CN', 
  
locales
: {
    '/': { 
lang
: 'zh-CN', 
title
: 'Blog' },
    '/en/': { 
lang
: 'en-US', 
title
: 'Blog' },
    '/fr/': { 
lang
: 'fr-FR', 
title
: 'Le blog' },
  },
  
theme
: 
plumeTheme
({
    // Theme-level multi-language configuration
    
locales
: { 
      // Simplified Chinese configuration
      '/': {
        
selectLanguageName
: '简体中文',
        
navbar
: [
          { 
text
: '首页', 
link
: '/' },
          { 
text
: '博客', 
link
: '/blog/' },
        ]
      },
      // English configuration
      '/en/': {
        
selectLanguageName
: 'English',
        
navbar
: [
          { 
text
: 'Home', 
link
: '/en/' },
          { 
text
: 'Blog', 
link
: '/en/blog/' },
        ]
      },
      // French configuration
      '/fr/': { 
        
selectLanguageName
: 'Français',
        
navbar
: [
          { 
text
: 'Accueil', 
link
: '/fr/' },
          { 
text
: 'Le Blog', 
link
: '/fr/blog/' },
        ]
      }
    }
  })
})

Key Configuration Items:

• selectLanguageName: Language name displayed in the language selector
• navbar: Navigation bar configuration unique to each language
• All theme configuration items support overriding by language in locales

Configuration Consistency Requirements

Ensure path keys in VuePress configuration exactly match those in theme configuration:

export default {
// VuePress configuration
  locales: {
    '/': { /* Chinese configuration */ },
    '/en/': { /* English configuration */ },
  },

  // Theme configuration
  theme: plumeTheme({
    locales: {
      '/': { /* Chinese theme configuration */ },
      '/en/': { /* English theme configuration */ }
    }
  })
}

Further Reading

• Theme Locales Configuration - Learn about language-specific theme behavior configurations
• Multi-language Text Configuration - Master internationalization customization methods for interface text

With the above configurations, your documentation site will have complete multi-language support capabilities, providing users with a more friendly internationalized access experience.

Contributors

pengzhanbo

Changelog

10/9/25, 7:46 AM

View All Changelog

• 38505-docs: update en docs (#708)on 10/9/25

Edit this page

Previous pagefrontmatter

Next pageDeployment