实现多语言

为你的 VitePress 站点添加多语言支持，触达全球用户。

目录结构

docs/
├── .vitepress/
│   └── config.mts
├── en/                    # 英文内容
│   ├── index.md
│   └── guide/
│       └── index.md
├── zh/                    # 中文内容
│   ├── index.md
│   └── guide/
│       └── index.md
└── index.md               # 默认语言首页

配置多语言

// .vitepress/config.mts
import { defineConfig } from 'vitepress'

export default defineConfig({
  // 默认语言
  lang: 'zh-CN',
  
  // 多语言配置
  locales: {
    root: {
      label: '简体中文',
      lang: 'zh-CN',
      themeConfig: {
        nav: [
          { text: '首页', link: '/' },
          { text: '指南', link: '/guide/' }
        ],
        sidebar: {
          '/guide/': [
            {
              text: '开始',
              items: [
                { text: '介绍', link: '/guide/' }
              ]
            }
          ]
        },
        editLink: {
          pattern: 'https://github.com/user/repo/edit/main/docs/:path',
          text: '在 GitHub 上编辑此页'
        },
        footer: {
          message: '基于 MIT 许可发布',
          copyright: 'Copyright © 2026'
        },
        docFooter: {
          prev: '上一页',
          next: '下一页'
        },
        outline: {
          label: '页面导航'
        },
        lastUpdated: {
          text: '最后更新于'
        },
        langMenuLabel: '多语言',
        returnToTopLabel: '返回顶部',
        sidebarMenuLabel: '菜单',
        darkModeSwitchLabel: '主题'
      }
    },
    en: {
      label: 'English',
      lang: 'en-US',
      link: '/en/',
      themeConfig: {
        nav: [
          { text: 'Home', link: '/en/' },
          { text: 'Guide', link: '/en/guide/' }
        ],
        sidebar: {
          '/en/guide/': [
            {
              text: 'Getting Started',
              items: [
                { text: 'Introduction', link: '/en/guide/' }
              ]
            }
          ]
        },
        editLink: {
          pattern: 'https://github.com/user/repo/edit/main/docs/:path',
          text: 'Edit this page on GitHub'
        },
        footer: {
          message: 'Released under the MIT License',
          copyright: 'Copyright © 2026'
        },
        docFooter: {
          prev: 'Previous',
          next: 'Next'
        },
        outline: {
          label: 'On this page'
        },
        lastUpdated: {
          text: 'Last updated'
        }
      }
    }
  },
  
  // 共享主题配置
  themeConfig: {
    logo: '/logo.svg',
    socialLinks: [
      { icon: 'github', link: 'https://github.com/user/repo' }
    ]
  }
})

语言切换器

VitePress 自动在导航栏显示语言切换器。你也可以自定义：

themeConfig: {
  localeLinks: {
    text: '',  // 可选：自定义文本
    items: [
      { text: '简体中文', link: '/' },
      { text: 'English', link: '/en/' }
    ]
  }
}

翻译 Markdown 内容

中文首页

<!-- docs/zh/index.md -->
---
layout: home
hero:
  name: VitePress
  text: 快速、简洁的静态站点生成器
  tagline: 基于 Vue 和 Vite
  actions:
    - theme: brand
      text: 快速开始
      link: /guide/
    - theme: alt
      text: GitHub
      link: https://github.com
features:
  - title: 🚀 极速
    details: 基于 Vite，毫秒级热更新
  - title: 🎨 灵活
    details: CSS 变量覆盖，完全定制
  - title: 📦 简洁
    details: 以 Markdown 为中心
---

英文首页

<!-- docs/en/index.md -->
---
layout: home
hero:
  name: VitePress
  text: Fast & Concise Static Site Generator
  tagline: Powered by Vue and Vite
  actions:
    - theme: brand
      text: Get Started
      link: /en/guide/
    - theme: alt
      text: GitHub
      link: https://github.com
features:
  - title: 🚀 Fast
    details: Powered by Vite, instant hot reload
  - title: 🎨 Flexible
    details: Customize with CSS variables
  - title: 📦 Simple
    details: Markdown-centered project structure
---

共享组件翻译

创建翻译文件

// .vitepress/theme/i18n/translations.ts
export const translations = {
  'zh-CN': {
    readMore: '阅读更多',
    lastUpdated: '最后更新',
    editPage: '编辑此页',
    backToTop: '返回顶部',
    search: '搜索',
    noResults: '没有找到结果',
    toc: '目录',
    minutesRead: '分钟阅读'
  },
  'en-US': {
    readMore: 'Read More',
    lastUpdated: 'Last Updated',
    editPage: 'Edit this page',
    backToTop: 'Back to top',
    search: 'Search',
    noResults: 'No results found',
    toc: 'On this page',
    minutesRead: 'min read'
  }
}

export type TranslationKey = keyof typeof translations['en-US']

创建 i18n 工具

// .vitepress/theme/i18n/index.ts
import { useData } from 'vitepress'
import { translations, TranslationKey } from './translations'

export function useTranslations() {
  const { lang } = useData()
  
  const t = (key: TranslationKey): string => {
    return translations[lang.value as keyof typeof translations]?.[key] 
      || translations['en-US'][key]
  }
  
  return { t }
}

在组件中使用

<script setup lang="ts">
import { useTranslations } from '../i18n'

const { t } = useTranslations()
</script>

<template>
  <button>{{ t('readMore') }}</button>
  <span>{{ t('minutesRead') }}</span>
</template>

重定向默认语言

// .vitepress/config.mts
export default defineConfig({
  rewrites: {
    'zh/:path': ':path',  // 中文作为根路径
    'en/:path': 'en/:path'
  }
})

多语言 SEO

设置 hreflang 标签

VitePress 自动为每个页面生成 hreflang 标签。你也可以手动添加：

export default defineConfig({
  head: [
    ['link', { rel: 'alternate', hreflang: 'zh-CN', href: 'https://example.com/' }],
    ['link', { rel: 'alternate', hreflang: 'en-US', href: 'https://example.com/en/' }],
    ['link', { rel: 'alternate', hreflang: 'x-default', href: 'https://example.com/' }]
  ]
})

学习检查清单

• [ ] 配置了多语言目录结构
• [ ] 设置了 locales 配置
• [ ] 翻译了首页内容
• [ ] 翻译了导航和侧边栏
• [ ] 创建了翻译工具函数

下一步

继续学习 开发 VitePress 插件，扩展 VitePress 功能。