VitePress 国际化(i18n)实战:多语言目录结构、locales 配置与 RTL 布局支持

发布时间:2026/11/17 10:16:14

VitePress 国际化(i18n)实战:多语言目录结构、locales 配置与 RTL 布局支持 VitePress 国际化i18n实战多语言目录结构、locales 配置与 RTL 布局支持【免费下载链接】vitepressVite Vue powered static site generator.项目地址: https://gitcode.com/gh_mirrors/vi/vitepressVitePress 内置了一整套开箱即用的国际化i18n能力通过目录结构与locales配置的配合你可以为站点提供多种语言版本包括独立的标题、描述、主题配置乃至 Markdown 渲染文案。本文以官方指南为基础结合当前仓库中的类型定义、波斯语站点真实配置与端到端测试完整讲解多语言站点的搭建流程、每种语言可覆盖的配置项以及从右到左RTL语言的布局支持方案让你读完即可在自己的 VitePress 项目中落地一套可维护的多语言文档站。理解 VitePress 的 i18n 机制目录即语言VitePress 使用基于文件的路由路由指南Markdown 文件的目录结构直接映射为站点 URL。国际化正是建立在这一机制之上——每个语言目录对应locales配置中的一个 key该 key 同时也是 URL 路径前缀。要启用内置的 i18n 特性首先需要创建如下目录结构docs/ ├─ es/ │ ├─ foo.md ├─ fr/ │ ├─ foo.md ├─ foo.md默认语言这里是es以外的内容放在docs根目录作为rootlocalees/、fr/等子目录则是各自的语言版本。访问路径随之变为/fooroot、/es/foo、/fr/foo。关于根目录的语义从 types/shared.d.ts 中的LocaleConfig类型可以看出locales是一个以语言目录为 keyroot表示默认语言的记录类型每个条目都基于LocaleSpecificConfig并额外要求label、可选的link与markdown字段。配置 locales以 docs/.vitepress/config.ts 为例在docs/.vitepress/config.ts中通过locales字段声明每种语言import { defineConfig } from vitepress export default defineConfig({ // 共享的、作用于所有语言的顶层配置... locales: { root: { label: English, lang: en }, fr: { label: French, lang: fr, // 可选会被作为 lang 属性添加到 html 标签上 link: /fr/guide // 默认为 /fr/ —— 显示在导航栏的翻译菜单中也可以是外部链接 // 其他语言专属配置... } } })各字段含义如下字段说明label语言在翻译菜单中显示的名称必填。lang该语言的 BCP 47 语言标签会被写入渲染后 HTML 的html标签lang属性对 SEO 与无障碍访问至关重要。link翻译菜单中该语言入口的链接默认指向该语言目录如/fr/也可以指向站内任意页面或外部地址。root键比较特殊它代表默认语言通常对应docs根目录下的内容没有 URL 前缀。站点级顶层配置如title、description默认即为root的取值。每种语言可覆盖的属性LocaleSpecificConfig对于每个语言包括 root都可以独立覆盖以下属性interface LocaleSpecificConfigThemeConfig any { lang?: string dir?: string title?: string titleTemplate?: string | boolean description?: string head?: HeadConfig[] // 会与已有的 head 条目合并重复的 meta 标签会被自动移除 themeConfig?: ThemeConfig // 浅合并公共信息可以放在顶层的 themeConfig 条目中 }结合 types/shared.d.ts 中的定义这些属性的语义可以进一步明确lang该语言的lang属性值default en-US写入html lang...。dir文本方向取值为ltr | rtl | autodefault ltr写入html dir...见下文 RTL 章节。title/titleTemplate/description站点标题、标题模板与描述均可按语言替换。head追加的head条目HeadConfig形如[tag, attrs]或[tag, attrs, innerHTML]。与已有 head 条目合并重复的 meta 标签会自动去重——例如你在顶层声明了og:description而某个语言又声明了自己的版本后者会安全替换前者。themeConfig主题配置的浅合并覆盖。这意味着公共的导航、侧边栏结构可以放在顶层themeConfig中每种语言只覆盖有差异的部分。默认主题文案的定制默认主题中大量占位文案如上一页/下一页、编辑此页、在页面内等的定制方式请参考DefaultTheme.Config接口定义见 types/default-theme.d.ts。该文件给出了所有可翻译字段的类型与默认值。需要注意两个禁止在语言级别覆盖的项themeConfig.algolia不要按语言覆盖否则会导致多语言搜索配置错乱themeConfig.carbonAds同样应在顶层配置。多语言站点的 Algolia 全文搜索含语言级locales配置与translations使用方法请参阅搜索功能文档。专业提示用 config/index.ts 拆分多语言配置当语言很多、每种语言的导航/侧边栏配置都很长时单个config.ts会迅速膨胀。VitePress 支持把配置文件存放在docs/.vitepress/config/index.ts此时可以为每种语言各建一个配置文件再在index.ts中合并导出。当前仓库的波斯语站点正是这样组织的——它在 docs/fa/config.ts 中通过defineAdditionalConfig声明波斯语专属的导航、侧边栏、编辑链接、页脚、404 文案与搜索翻译再由docs/config.ts统一汇总所有语言。本地化 Markdown 渲染文案容器标签与代码复制按钮除了站点级文案Markdown 渲染器内嵌的字符串也可以按语言覆盖字段位于 locale 条目的markdown键下。这些字符串包括自定义容器与 GitHub 风格告警GitHub-flavored alerts的默认标题以及代码块复制按钮的提示文案。下面以简体中文为例import { defineConfig } from vitepress export default defineConfig({ locales: { root: { label: English, lang: en }, zh: { label: 简体中文, lang: zh-Hans, markdown: { container: { tipLabel: 提示, warningLabel: 警告 // ...其他标签以及 customContainers 的标题 }, codeCopyButton: { tooltipText: 复制代码, copiedText: 已复制 } } } } })关于这套机制的边界types/shared.d.ts 给出了明确的类型契约回退规则某语言未设置的项会回退到顶层markdown选项的取值。可覆盖范围container支持infoLabel、noteLabel、tipLabel、warningLabel、dangerLabel、detailsLabel、importantLabel、cautionLabel分别对应::: info、 [!NOTE]、::: tip、::: warning、::: danger、::: details、 [!IMPORTANT]、 [!CAUTION]以及customContainers中已注册容器的标题codeCopyButton支持tooltipTextdefault Copy code与copiedTextdefault Copied。限制一语言级别只能修改 root 已注册容器的标题不支持在某个语言里注册新容器。限制二由于整个站点的 Markdown 渲染器只创建一次这些配置只能写在主配置文件docs/.vitepress/config.ts或config/index.ts中不能放在按需加载的附加配置里。当前仓库的波斯语文档就是这套能力的真实用例在 docs/fa/config.ts 中波斯语版本将tipLabel译为「نکته」、warningLabel译为「اخطار」、复制按钮译为「کپی کد / کپی شد」共覆盖全部 8 类容器标签。为每种语言使用独立目录根路径重定向与语言记忆另一种完全合理的结构是为每种语言建独立目录包括默认语言docs/ ├─ en/ │ ├─ foo.md ├─ es/ │ ├─ foo.md ├─ fr/ ├─ foo.md这种结构下locales需要把en也显式声明为一个语言条目。VitePress 不会自动重定向VitePress 默认不会把/重定向到/en/——根路径 404 与否取决于你的部署。这需要在服务器层配置。例如在 Netlify 上可以新建docs/public/_redirects文件/* /es/:splat 302 Languagees /* /fr/:splat 302 Languagefr /* /en/:splat 302该规则的含义根据请求的Language头浏览器会随请求发送Accept-Language派生的语言偏好把根路径下的资源分别 302 重定向到对应语言前缀/en/作为兜底。其他平台Nginx、Vercel、Cloudflare Pages 等可参考各自的重定向语法实现同样的逻辑。专业提示用 nf_lang cookie 记忆用户语言选择使用上述 Netlify 重定向方案时每次访问/都会依据请求头重新决定语言用户的选择无法保持。Netlify 提供了nf_langcookie 约定只要在浏览器种下nf_langcookie重定向规则就会优先按 cookie 值分流。可以通过自定义主题的 Layout 组件写入该 cookieimport DefaultTheme from vitepress/theme import Layout from ./Layout.vue export default { extends: DefaultTheme, Layout }script setup langts import DefaultTheme from vitepress/theme import { useData, inBrowser } from vitepress import { watchEffect } from vue const { lang } useData() watchEffect(() { if (inBrowser) { document.cookie nf_lang${lang.value}; expiresMon, 1 Jan 2030 00:00:00 UTC; path/ } }) /script template DefaultTheme.Layout / /template要点说明useData()暴露的lang是当前激活 locale 的lang值见 types/shared.d.ts 中的VitePressData与重定向规则中Language匹配的是同一个维度。必须通过inBrowser守卫只在客户端执行 cookie 写入避免 SSR 阶段访问document报错由于lang是响应式 refwatchEffect会在切换语言后自动更新 cookie。支持从右到左RTL的语言对阿拉伯语、波斯语、希伯来语等从右到左书写的语言需要让整个页面镜像排布。基础配置dir: rtl在配置中设置dir: rtl即可export default { lang: fa-IR, dir: rtl }对于多语言站点则在locales中按语言分别设置dir它也可以通过在单页 frontmatter 中设置dir来覆盖见 frontmatter-config 文档 中的dir选项。当前版本默认主题基于 CSS 逻辑属性自适配无需 PostCSS 插件需要特别说明的是官方指南的波斯语版本即本文对应的源文档将 RTL 标注为「实验性」特性并建议配合 RTLCSS 类 PostCSS 插件如 rtlcss、postcss-rtl、postcss-rtlcss使用同时提示要用:where([dirltr])与:where([dirrtl])作为选择器前缀以避免 CSS 优先级问题。而当前仓库的最新实现已经演进默认主题的样式基于 CSS 逻辑属性CSS logical properties布局布局、导航与方向性图标会自动跟随文档方向翻转不再需要任何 PostCSS 插件——如果保留了 RTLCSS 插件反而会把已经镜像过的样式二次翻转。这一点有源码与测试双重佐证单元测试 logical-properties.test.ts 验证了默认主题样式对逻辑属性的使用端到端测试 rtl/index.test.ts 完整验证了 RTL 行为html标签的dir属性正确输出、页面从右侧布局侧边栏贴合右缘、大纲指示器停留在阅读侧、侧边栏折叠箭头水平镜像scale: -1 1、外部链接图标镜像、移动端侧边栏从右侧滑入以及代码块始终从左到右div[class*language-]强制dirltr。编写自定义样式时的 RTL 注意事项当添加自己的样式时请遵循两条约定优先使用逻辑属性用margin-inline-start而不是margin-left用padding-inline-end而不是padding-right这样在 LTR/RTL 两种方向下都自动正确。镜像方向性图标例如箭头类图标在 RTL 布局下需要水平翻转[dirrtl] .my-arrow-icon { scale: -1 1; }另外记住无论页面方向如何代码块始终保持在左到右避免源代码缩进与行号错乱。仓库中的真实落地案例docs/目录本身就是当前仓库多语言实践的样板docs/en、docs/es、docs/fa、docs/ja、docs/ko、docs/pt、docs/ru、docs/zh各自对应一种语言共享同一套 guide/reference 文档骨架。其中docs/fa/config.ts 展示了波斯语RTL站点的完整配置导航与侧边栏、编辑链接文案、页脚、404 文案、大纲标签、上一页/下一页文案、深浅色切换标签以及完整的中文搜索框翻译含 Ask AI 界面可作为themeConfig按语言覆盖的参考范本docs/config.ts 负责将所有语言的配置合并汇总tests/e2e/rtl/ 的测试夹具rtl/index.md与测试用例共同演示了 RTL 站点的标准写法与可验证的布局断言。小结VitePress 的国际化不是简单的内容翻译而是一套贯穿目录结构、站点配置、主题文案与渲染字符串的完整机制root 语言目录决定了 URL 与路由locales中每个条目可独立覆盖lang、dir、title、description、head与themeConfigmarkdown键还能本地化容器标签和复制按钮文案配合服务器重定向与nf_langcookie 可以实现默认语言分流与语言记忆而基于 CSS 逻辑属性的默认主题让 RTL 语言的开箱即用成为现实。参照本文的配置示例与仓库源码证据你可以快速搭建出结构清晰、体验完整的多语言 VitePress 站点。【免费下载链接】vitepressVite Vue powered static site generator.项目地址: https://gitcode.com/gh_mirrors/vi/vitepress创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考
延伸阅读

更多相关文章

2026/11/17 10:14:38

安徽特种工挂靠证过期了怎么处理?出安徽特种工挂靠在哪考最靠谱

安徽特种工挂靠证过期了怎么处理?出安徽特种工挂靠在哪考最靠谱 证书过期了不知道怎么复审延期?很多在安徽从事特种作业的朋友,特别是三门峡地区中小型施工企业的负责人,都遇到过这样的问题。特种作业操作证一旦过期,不仅影响日常工作,还可能面临处罚。…

2026/11/17 10:14:38

马尾哪里有办电工证真实经历:工地太忙根本没时间复习考试怎么办?

马尾哪里有办电工证真实经历:工地太忙根本没时间复习考试怎么办? 工地太忙根本没时间复习考试,这几乎是每个一线施工人员的共识。尤其是像我在南阳卧龙区从事公路工程的同事,天天在工地上跑来跑去,哪还有心思去翻教材、做题?但偏偏特种作业操作证,比如…

2026/11/17 10:14:38

工作可以考电工证吗真实经历告诉你怎么处理过期证书

工作可以考电工证吗真实经历告诉你怎么处理过期证书 证书过期了不知道怎么复审延期,这种情况真的太常见了。去年我就因为没及时处理低压电工证复审,差点被单位停岗,那段时间整个人都慌了。现在回头看,其实只要提前准备,问题并不大。如果你也在找“工作可…

2026/11/17 10:14:38

电工证几个月能上网 2026河南最新政策下如何快速拿到证上岗

电工证几个月能上网 2026河南最新政策下如何快速拿到证上岗 你是不是也正被“电工证几个月能上网”这个问题困扰着?特别是在2026河南最新政策下,越来越多的工地和企业明确要求持证上岗,没有电工证连面试资格都没有。别再等了,今天就告诉你怎么快…

2026/11/17 10:09:38

特种工退休资料考前押题怎么拿?别怕考不过白交培训费

特种工退休资料考前押题怎么拿?别怕考不过白交培训费 你是不是也担心,花了几千块报的特种作业培训,最后考试不过,钱就打水漂了?尤其是像我们这种在鹤壁做中小型施工企业的,特种作业证关系到项目能不能顺利开工,考不过不仅耽误工期,还影响公司信誉。所…

2026/11/16 7:29:52

电工证考试口诉怎么准备值不值得考

电工证考试口诉怎么准备值不值得考 实操考试心里没底怕挂科,这是大多数准备考电工证的人心里最真实的感受。尤其是面对【电工证考试口诉】环节,很多人不知道该怎么准备,甚至担心自己说不好就被淘汰。其实,只要掌握方法, 值不值得考…

2026/11/16 5:30:20

桑植县考电工证千万别踩坑!报名全流程教你避坑

桑植县考电工证千万别踩坑!报名全流程教你避坑 你是不是也遇到过这种情况:想考个电工证,但不知道从哪儿下手,怕被中介坑,怕花冤枉钱,更怕考了证还不能用?别急,这正是你该看这篇文章的原因。在桑植县考电工证,确实有很多人被坑过,但只要你知道流程、…

2026/11/17 0:02:41

电工证操作和资格证有效期多久?真实经历告诉你怎么复审延期

电工证操作和资格证有效期多久?真实经历告诉你怎么复审延期 证书过期了不知道怎么复审延期,这种情况在电工圈里太常见了。我有个同事,去年刚把低压电工证给弄丢了,直到单位查岗才发现证书已经过期,差点被停工处理。今天就用我真实经历给你讲讲电工证操作…

2026/11/17 0:02:41

机修需不需要电工证 在哪考最靠谱 这些细节必须知道

机修需不需要电工证 在哪考最靠谱 这些细节必须知道 之前考的证在外省能不能转过来?这个问题几乎每个特种作业从业者都问过。特别是像你这样,之前在外省考了证,现在想在本地扎根,或者想换证、换岗的机修人员,最关心的就是【机修需不需要电工证】和【在…

2026/11/17 0:02:41

工地太忙根本没时间复习考试?真实经历告诉你电工证年检步骤是什么

工地太忙根本没时间复习考试?真实经历告诉你电工证年检步骤是什么 工地太忙根本没时间复习考试,我理解你。作为一名刚从焦作工程类院校毕业的学生,我也经历过这种困扰。电工证年检步骤是什么,听起来简单,但实际操作中,很多人因为流程不清楚、资料准备不…

2026/11/17 0:49:41

面向复杂光照与角度的宠物面部识别鲁棒性增强策略

在智慧养宠时代,基于视觉的宠物身份识别技术正逐步从实验室走向家庭应用。然而,与配合度高的人类不同,宠物是典型的“非合作生物识别对象”——它们不会主动配合摄像头调整姿态,更无法控制光照环境。实际应用中,我们常…

2026/11/16 3:17:47

SSM电子书店源码全解析:结构、原理、部署与排错实战

/* MD / 富文本中的 .toc(含博客园搬家等嵌套结构);.toc-box 在侧栏,不受影响 */#content_views .toc,/* 编辑器常在目录前后插入空 p(:empty 仍占 20px),一并去掉避免顶空隙 */#content_views.markdown_views > p:empty:has(+ .toc),#content_views.markdown_views …

还想了解更多?直接咨询顾问

免费诊断 + 免费方案 + 透明报价。

全国咨询热线400-8866-253
免费获取方案
☎咨询二维码 ☎ ↑