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），仅供参考 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），仅供参考