2025/6/8
vuepress 多语言支持
多语言配置
站点多语言配置
- 要启用 VuePress 的多语言支持，首先需要使用如下的文件目录结构：
docs
├─ README.md
├─ foo.md
├─ nested
│ └─ README.md
└─ zh
├─ README.md
├─ foo.md
└─ nested
└─ README.md- 在 配置文件 中设置 locales 选项：
默认主题提供多语言支持的方式：
export default {
locales: {
// 键名是该语言所属的子路径
// 作为特例，默认语言可以使用 '/' 作为其路径。
'/': {
lang: 'en-US',
title: 'VuePress',
description: 'Vue-powered Static Site Generator',
},
'/zh/': {
lang: 'zh-CN',
title: 'VuePress',
description: 'Vue 驱动的静态网站生成器',
},
},
}如果一个语言没有声明 lang, title, description 或者 head ，VuePress 将会尝试使用顶层配置的对应值。
如果每个语言都声明了这些值，那么顶层配置中的对应值可以被省略。
主题多语言配置
不同主题可能会有不同的多语言配置方式
import { defaultTheme } from '@vuepress/theme-default'
import { defineUserConfig } from 'vuepress'
export default defineUserConfig({
theme: defaultTheme({
locales: {
'/': {
selectLanguageName: 'English',
},
'/zh/': {
selectLanguageName: '简体中文',
},
},
}),
})theme-hope 多语言支持
多语言配置
设置语言
你需要为每个语言设置 lang 选项。
主题需要知道根文件夹以及每个多语言文件夹正在使用哪种语言。
单语言案例：
import { defineUserConfig } from "vuepress";
export default defineUserConfig({
lang: "zh-CN",
});多语言案例：
import { defineUserConfig } from "vuepress";
export default defineUserConfig({
locales: {
"/": {
lang: "zh-CN",
},
"/en/": {
lang: "en-US",
},
},
});多语言配置
locales 是一个对象，其键为每个语言的路径前缀，值为该语言的配置，可以包含 title, description, lang 等。
如果站点和主题配置中的 locales 对象只包含 "/" 一个键，那么站点不会被视为多语言的。
语言适配
- 简体中文 (zh-CN)
- 繁体中文 (zh-TW)
- 英文(美国) (en-US)
- 德语 (de-DE)
- 德语(澳大利亚) (de-AT)
- 俄语 (ru-RU)
- 乌克兰语 (uk-UA)
- 越南语 (vi-VN)
- 葡萄牙语(巴西) (pt-BR)
- 波兰语 (pl-PL)
- 法语 (fr-FR)
- 西班牙语 (es-ES)
- 斯洛伐克 (sk-SK)
- 日语 (ja-JP)
- 土耳其语 (tr-TR)
- 韩语 (ko-KR)
- 芬兰语 (fi-FI)
- 印尼语 (id-ID)
- 荷兰语 (nl-NL)
为每个语言设置主题选项
vuepress-theme-hope 也在主题选项中支持 locales，因此你可以为每种语言设置不同的主题配置。
vuepress-theme-hope主题的站点多语言配置和主题多语言配置
import { defineUserConfig } from "vuepress";
import { hopeTheme } from "vuepress-theme-hope";
export default defineUserConfig({
locales: {
"/": {
lang: "en-US",
},
"/zh/": {
lang: "zh-CN",
},
},
theme: hopeTheme({
// 通用配置
// ...
locales: {
"/": {
// 英文配置
// ...
},
"/zh/": {
// 中文配置
// ...
},
},
}),
});主题多语言选项
可以在主题配置中通过在 locales[localePath] 添加下列选项自定义主题的多语言选项。
interface ThemeLocaleData {
/**
* 当前语言代码
*/
lang: string;
/**
* 外观
*/
outlookLocales: {
/**
* 主题色
*/
themeColor: string;
/**
* 夜间模式
*/
darkmode: string;
/**
* 全屏文字
*/
fullscreen: string;
};
/**
* 博客
*/
blogLocales: {
/** 文章文字 */
article: string;
/** 文章列表文字 */
articleList: string;
/** 分类文字 */
category: string;
/** 标签文字 */
tag: string;
/** 时间轴文字 */
timeline: string;
/** 时间轴标题文字 */
timelineTitle: string;
/** 全部文字 */
all: string;
/** 个人介绍 */
intro: string;
/** 星标文章 */
star: string;
};
/**
* 分页
*/
paginationLocales: {
/**
* 上一页文字
*/
prev: string;
/**
* 下一页文字
*/
next: string;
/**
* 跳转提示文字
*/
navigate: string;
/**
* 跳转按钮文字
*/
action: string;
/**
* 页码错误文字
*
* @description `$page` 会自动替换为当前的总页数
*/
errorText: string;
};
/**
* 加密
*/
encryptLocales: {
/**
* 加密图标的无障碍标签
*/
iconLabel: string;
/**
* 密码输入框的默认占位符
*/
placeholder: string;
/**
* 是否记忆密码
*/
remember: string;
/**
* 密码错误提示
*/
errorHint: string;
};
navbarLocales: {
/**
* 语言下拉列表的无障碍标签
*/
selectLangAriaLabel: string;
/**
* 当前语言的名称
*/
langName: string;
};
/**
* 页面元信息
*/
metaLocales: {
/**
* 作者文字
*/
author: string;
/**
* 写作日期文字
*/
date: string;
/**
* 标记原创的文字
*/
origin: string;
/**
* 访问量文字
*/
views: string;
/**
* 标签文字
*/
tag: string;
/**
* 分类文字
*/
category: string;
/**
* 期望阅读时间文字
*/
readingTime: string;
/**
* 文章字数
*/
words: string;
/**
* 此页内容
*/
toc: string;
/**
* 上一页
*/
prev: string;
/**
* 下一页
*/
next: string;
/**
* 贡献者文字
*/
contributors: string;
/**
* 编辑此页文字
*/
editLink: string;
};
routerLocales: {
/**
* 跳转到主要内容
*/
skipToContent: string;
/**
* 404 页面的标题
*/
notFoundTitle: string;
/**
* 404 页面提示
*/
notFoundMsg: string[];
/**
* 返回主页
*/
home: string;
/**
* 返回上一页
*/
back: string;
};
}同时，一些多语言选项是由插件控制的，它们包括:
- plugins.comment.locales: Waline 评论服务
- plugins.components.locales: 组件多语言
- plugins.copyCode.locales: 代码块复制
- plugins.copyright.locales: 版权信息
- plugins.markdownHint.locales: Markdown 提示
- plugins.photoSwipe.locales: 图片浏览
- plugins.pwa.locales: PWA