VuePress 多语言支持i18n完全指南站点配置与默认主题国际化实战【免费下载链接】vuepress Minimalistic Vue-powered static site generator项目地址: https://gitcode.com/gh_mirrors/vu/vuepress导读本文基于 VuePress 官方中文文档《多语言支持》展开深入讲解如何在当前仓库GitHub 加速计划 / vu / vuepress 镜像中为静态站点搭建完整的多语言体系从目录结构规划、locales站点级配置到默认主题的themeConfig.locales导航栏与侧边栏国际化并结合仓库源码剖析$localePath、$localeConfig、$lang等运行时计算属性的底层实现。读完本文你将能够独立为 VuePress 站点配置中英文等多语言版本并理解语言切换背后从文件路径到页面 URL 的完整映射原理。站点多语言配置第一步规划多语言目录结构要启用 VuePress 的多语言支持首先需要使用按语言划分子目录的文件结构。以中英双语站点为例在docs目录下默认语言英文的文件直接放在根目录其他语言如中文放在以语言代码命名的子目录中docs ├─ README.md ├─ foo.md ├─ nested │ └─ README.md └─ zh ├─ README.md ├─ foo.md └─ nested └─ README.md这种结构的核心约定是目录层级即 URL 路径前缀。docs/zh/foo.md对应的页面路径是/zh/foo.html具体路由规则由 Page.js 中的fileToPath转换而来从而与/foo.html形成一一对应的多语言页面。仓库自身的文档正是采用这一模式packages/docs/docs/下同时存在英文文档与zh/中文文档目录二者结构完全对称。第二步在 config.js 中提供 locales 选项目录就绪后在.vuepress/config.js中通过顶层locales选项声明每种语言module.exports { locales: { // 键名是该语言所属的子路径 // 作为特例默认语言可以使用 / 作为其路径。 /: { lang: en-US, // 将会被设置为 html 的 lang 属性 title: VuePress, description: Vue-powered Static Site Generator }, /zh/: { lang: zh-CN, title: VuePress, description: Vue 驱动的静态网站生成器 } } }要点说明键名即子路径每个locales键都对应一个语言子路径例如/zh/对应zh目录默认语言是特例使用/作为键名对应 docs 根目录。lang属性声明该语言的 BCP 47 语言标签如en-US、zh-CN最终会被写入html的lang属性对 SEO 和无障碍a11y均有实际意义。title/description回退规则如果一个语言没有声明title或descriptionVuePress 会尝试使用配置顶层的对应值即module.exports根级定义的title、description反过来如果每个语言都声明了title和description则顶层的这两个值可以被省略。这一回退逻辑并非文档空谈而是由运行时计算属性真正实现的。在 ClientComputedMixin.js 中可以看到get $description () { const description getMetaDescription(this.$page.frontmatter.meta) if (description) { return description } return this.$page.frontmatter.description || this.$localeConfig.description || this.$site.description || } get $lang () { return this.$page.frontmatter.lang || this.$localeConfig.lang || en-US } get $localePath () { return this.$localeConfig.path || / }其取值优先级清晰可见页面 frontmatter 当前 locale 配置 站点顶层配置 最终兜底值$lang的兜底为en-US。其中$localeConfig的计算会遍历$site.locales依据当前页面路径匹配出最合适的语言配置而$site中每个 locale 的path字段则由 dataMixin.js 在客户端初始化时补全if (siteData.locales) { Object.keys(siteData.locales).forEach(path { siteData.locales[path].path path }) }第三步理解页面如何归属到某一种语言页面与语言的归属关系在构建期Node 端就已确定。每个页面实例都会在初始化阶段执行 i18n 解析// resolve i18n computed.setPage(this) this._computed computed this._localePath computed.$localePath这段逻辑位于 Page.js。$localePath即当前页面所属语言的路径如/zh/它随后参与buildPermalink()见 Page.js的最终 URL 生成并在页面数据中通过localePath字段暴露给客户端Page.js。简而言之文件落在哪个语言目录页面就归属哪种语言URL 前缀也就随之确定。默认主题多语言配置themeConfig.locales按语言定制主题文案与导航默认主题同样内置了多语言支持通过themeConfig.locales配置。该选项接受与站点级locales相同的{ path: config }格式每个键仍为语言子路径默认语言为/每个语言除了可以配置站点界面中出现的文字外还可以拥有自己独立的导航栏和侧边栏module.exports { locales: { /* ... */ }, themeConfig: { locales: { /: { selectText: Languages, label: English, ariaLabel: Languages, editLinkText: Edit this page on GitHub, serviceWorker: { updatePopup: { message: New content is available., buttonText: Refresh } }, algolia: {}, nav: [ { text: Nested, link: /nested/, ariaLabel: Nested } ], sidebar: { /: [/* ... */], /nested/: [/* ... */] } }, /zh/: { // 多语言下拉菜单的标题 selectText: 选择语言, // 该语言在下拉菜单中的标签 label: 简体中文, // 编辑链接文字 editLinkText: 在 GitHub 上编辑此页, // Service Worker 的配置 serviceWorker: { updatePopup: { message: 发现新内容可用., buttonText: 刷新 } }, // 当前 locale 的 algolia docsearch 选项 algolia: {}, nav: [ { text: 嵌套, link: /zh/nested/ } ], sidebar: { /zh/: [/* ... */], /zh/nested/: [/* ... */] } } } } }各配置项的实战含义配置项作用说明selectText多语言下拉菜单的标题文字语言切换器上的显示label该语言在下拉菜单中的标签名如简体中文、EnglishariaLabel语言切换器的无障碍标签供屏幕阅读器使用editLinkText页面「编辑此页」链接的文字通常指向 GitHub 仓库中的源文件serviceWorker.updatePopup配合官方 PWA 插件使用的更新弹窗文案message提示语 buttonText按钮文字algolia当前 locale 专属的 Algolia DocSearch 配置对象nav当前语言的导航栏配置sidebar当前语言的侧边栏配置{ 路径: 配置 }格式注意nav与sidebar中的链接也遵循语言路径约定英文导航指向/nested/中文导航则指向/zh/nested/从而保证切换到对应语言后导航栏与侧边栏能指向该语言下的页面。底层实现$themeLocaleConfig 按语言取配置默认主题的多语言文案之所以能做到「切换语言即切换界面文字」得益于客户端计算属性$themeLocaleConfigget $themeLocaleConfig () { return (this.$site.themeConfig.locales || {})[this.$localePath] || {} }该属性位于 ClientComputedMixin.js$themeLocaleConfig紧跟$localePath定义。它直接以当前页面的$localePath为键从themeConfig.locales中取出对应语言的配置若未命中则返回空对象此时主题组件会回退到无语言差异的默认行为。同理client/util.js 中的通用配置解析工具也遵循同一模式传入{ [localePath]: config }结构即可按当前语言精确取出对应配置。这正是「主题配置 站点配置」两层 locales 体系得以协同工作的基石。配置实战建议保持目录与 locales 键一一对应/zh/键对应zh目录缺失目录会导致语言页面 404反之存在目录却未声明 locales则页面不会被纳入任何语言配置。善用回退机制减少重复各语言都有的相同标题可直接放在顶层title仅在语言间有差异时才下沉到locales中覆盖。导航与侧边栏务必使用对应语言路径中文 locale 的nav、sidebar链接应以/zh/开头否则用户切换语言后仍会跳转到默认语言页面。语言切换器开箱即用默认主题的导航栏会自动根据themeConfig.locales渲染语言下拉菜单无需额外编码只需正确填写selectText、label等文案字段。扩展其他语言新增语言只需三步——新建docs/xx/目录、在顶层locales与themeConfig.locales各加一个/xx/配置块、将页面文件复制到新目录并翻译内容。小结VuePress 的多语言支持由「目录结构 双层 locales 配置」构成站点级locales负责语言元信息lang、title、description主题级themeConfig.locales负责界面文案与导航侧边栏的国际化而运行时计算属性$localePath、$localeConfig、$lang、$themeLocaleConfigClientComputedMixin.js将二者串联配合构建期 Page.js 的 i18n 解析最终把每个页面精确映射到对应语言。理解了这条从文件目录到 URL 前缀、再到主题文案的链路你就掌握了 VuePress 站点国际化的全部关键。【免费下载链接】vuepress Minimalistic Vue-powered static site generator项目地址: https://gitcode.com/gh_mirrors/vu/vuepress创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
VuePress 多语言支持（i18n）完全指南：站点配置与默认主题国际化实战
VuePress 多语言支持i18n完全指南站点配置与默认主题国际化实战【免费下载链接】vuepress Minimalistic Vue-powered static site generator项目地址: https://gitcode.com/gh_mirrors/vu/vuepress导读本文基于 VuePress 官方中文文档《多语言支持》展开深入讲解如何在当前仓库GitHub 加速计划 / vu / vuepress 镜像中为静态站点搭建完整的多语言体系从目录结构规划、locales站点级配置到默认主题的themeConfig.locales导航栏与侧边栏国际化并结合仓库源码剖析$localePath、$localeConfig、$lang等运行时计算属性的底层实现。读完本文你将能够独立为 VuePress 站点配置中英文等多语言版本并理解语言切换背后从文件路径到页面 URL 的完整映射原理。站点多语言配置第一步规划多语言目录结构要启用 VuePress 的多语言支持首先需要使用按语言划分子目录的文件结构。以中英双语站点为例在docs目录下默认语言英文的文件直接放在根目录其他语言如中文放在以语言代码命名的子目录中docs ├─ README.md ├─ foo.md ├─ nested │ └─ README.md └─ zh ├─ README.md ├─ foo.md └─ nested └─ README.md这种结构的核心约定是目录层级即 URL 路径前缀。docs/zh/foo.md对应的页面路径是/zh/foo.html具体路由规则由 Page.js 中的fileToPath转换而来从而与/foo.html形成一一对应的多语言页面。仓库自身的文档正是采用这一模式packages/docs/docs/下同时存在英文文档与zh/中文文档目录二者结构完全对称。第二步在 config.js 中提供 locales 选项目录就绪后在.vuepress/config.js中通过顶层locales选项声明每种语言module.exports { locales: { // 键名是该语言所属的子路径 // 作为特例默认语言可以使用 / 作为其路径。 /: { lang: en-US, // 将会被设置为 html 的 lang 属性 title: VuePress, description: Vue-powered Static Site Generator }, /zh/: { lang: zh-CN, title: VuePress, description: Vue 驱动的静态网站生成器 } } }要点说明键名即子路径每个locales键都对应一个语言子路径例如/zh/对应zh目录默认语言是特例使用/作为键名对应 docs 根目录。lang属性声明该语言的 BCP 47 语言标签如en-US、zh-CN最终会被写入html的lang属性对 SEO 和无障碍a11y均有实际意义。title/description回退规则如果一个语言没有声明title或descriptionVuePress 会尝试使用配置顶层的对应值即module.exports根级定义的title、description反过来如果每个语言都声明了title和description则顶层的这两个值可以被省略。这一回退逻辑并非文档空谈而是由运行时计算属性真正实现的。在 ClientComputedMixin.js 中可以看到get $description () { const description getMetaDescription(this.$page.frontmatter.meta) if (description) { return description } return this.$page.frontmatter.description || this.$localeConfig.description || this.$site.description || } get $lang () { return this.$page.frontmatter.lang || this.$localeConfig.lang || en-US } get $localePath () { return this.$localeConfig.path || / }其取值优先级清晰可见页面 frontmatter 当前 locale 配置 站点顶层配置 最终兜底值$lang的兜底为en-US。其中$localeConfig的计算会遍历$site.locales依据当前页面路径匹配出最合适的语言配置而$site中每个 locale 的path字段则由 dataMixin.js 在客户端初始化时补全if (siteData.locales) { Object.keys(siteData.locales).forEach(path { siteData.locales[path].path path }) }第三步理解页面如何归属到某一种语言页面与语言的归属关系在构建期Node 端就已确定。每个页面实例都会在初始化阶段执行 i18n 解析// resolve i18n computed.setPage(this) this._computed computed this._localePath computed.$localePath这段逻辑位于 Page.js。$localePath即当前页面所属语言的路径如/zh/它随后参与buildPermalink()见 Page.js的最终 URL 生成并在页面数据中通过localePath字段暴露给客户端Page.js。简而言之文件落在哪个语言目录页面就归属哪种语言URL 前缀也就随之确定。默认主题多语言配置themeConfig.locales按语言定制主题文案与导航默认主题同样内置了多语言支持通过themeConfig.locales配置。该选项接受与站点级locales相同的{ path: config }格式每个键仍为语言子路径默认语言为/每个语言除了可以配置站点界面中出现的文字外还可以拥有自己独立的导航栏和侧边栏module.exports { locales: { /* ... */ }, themeConfig: { locales: { /: { selectText: Languages, label: English, ariaLabel: Languages, editLinkText: Edit this page on GitHub, serviceWorker: { updatePopup: { message: New content is available., buttonText: Refresh } }, algolia: {}, nav: [ { text: Nested, link: /nested/, ariaLabel: Nested } ], sidebar: { /: [/* ... */], /nested/: [/* ... */] } }, /zh/: { // 多语言下拉菜单的标题 selectText: 选择语言, // 该语言在下拉菜单中的标签 label: 简体中文, // 编辑链接文字 editLinkText: 在 GitHub 上编辑此页, // Service Worker 的配置 serviceWorker: { updatePopup: { message: 发现新内容可用., buttonText: 刷新 } }, // 当前 locale 的 algolia docsearch 选项 algolia: {}, nav: [ { text: 嵌套, link: /zh/nested/ } ], sidebar: { /zh/: [/* ... */], /zh/nested/: [/* ... */] } } } } }各配置项的实战含义配置项作用说明selectText多语言下拉菜单的标题文字语言切换器上的显示label该语言在下拉菜单中的标签名如简体中文、EnglishariaLabel语言切换器的无障碍标签供屏幕阅读器使用editLinkText页面「编辑此页」链接的文字通常指向 GitHub 仓库中的源文件serviceWorker.updatePopup配合官方 PWA 插件使用的更新弹窗文案message提示语 buttonText按钮文字algolia当前 locale 专属的 Algolia DocSearch 配置对象nav当前语言的导航栏配置sidebar当前语言的侧边栏配置{ 路径: 配置 }格式注意nav与sidebar中的链接也遵循语言路径约定英文导航指向/nested/中文导航则指向/zh/nested/从而保证切换到对应语言后导航栏与侧边栏能指向该语言下的页面。底层实现$themeLocaleConfig 按语言取配置默认主题的多语言文案之所以能做到「切换语言即切换界面文字」得益于客户端计算属性$themeLocaleConfigget $themeLocaleConfig () { return (this.$site.themeConfig.locales || {})[this.$localePath] || {} }该属性位于 ClientComputedMixin.js$themeLocaleConfig紧跟$localePath定义。它直接以当前页面的$localePath为键从themeConfig.locales中取出对应语言的配置若未命中则返回空对象此时主题组件会回退到无语言差异的默认行为。同理client/util.js 中的通用配置解析工具也遵循同一模式传入{ [localePath]: config }结构即可按当前语言精确取出对应配置。这正是「主题配置 站点配置」两层 locales 体系得以协同工作的基石。配置实战建议保持目录与 locales 键一一对应/zh/键对应zh目录缺失目录会导致语言页面 404反之存在目录却未声明 locales则页面不会被纳入任何语言配置。善用回退机制减少重复各语言都有的相同标题可直接放在顶层title仅在语言间有差异时才下沉到locales中覆盖。导航与侧边栏务必使用对应语言路径中文 locale 的nav、sidebar链接应以/zh/开头否则用户切换语言后仍会跳转到默认语言页面。语言切换器开箱即用默认主题的导航栏会自动根据themeConfig.locales渲染语言下拉菜单无需额外编码只需正确填写selectText、label等文案字段。扩展其他语言新增语言只需三步——新建docs/xx/目录、在顶层locales与themeConfig.locales各加一个/xx/配置块、将页面文件复制到新目录并翻译内容。小结VuePress 的多语言支持由「目录结构 双层 locales 配置」构成站点级locales负责语言元信息lang、title、description主题级themeConfig.locales负责界面文案与导航侧边栏的国际化而运行时计算属性$localePath、$localeConfig、$lang、$themeLocaleConfigClientComputedMixin.js将二者串联配合构建期 Page.js 的 i18n 解析最终把每个页面精确映射到对应语言。理解了这条从文件目录到 URL 前缀、再到主题文案的链路你就掌握了 VuePress 站点国际化的全部关键。【免费下载链接】vuepress Minimalistic Vue-powered static site generator项目地址: https://gitcode.com/gh_mirrors/vu/vuepress创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
