MaraPython

简体中文

English

简体中文

English

主题

Alowree XU2026-04-20
0

本站 - 国际化 ​

本文档介绍如何将默认的中文站点迁移为支持多语言（中文和英文）的站点。

背景 ​

最初，本站的 VitePress 配置全部集中在 .vitepress/config.mts 文件中。随着站点内容的扩展，我们决定支持多语言，以更好地服务全球用户。

迁移步骤 ​

1. 配置文件的拆分 ​

原有结构 ​

  • .vitepress/config.mts：包含所有配置，包括主题配置、导航、侧边栏等。

新结构 ​

  • .vitepress/config.mts：主配置文件，导入并组合各个语言配置。
  • .vitepress/locales/shared.ts：共享配置，包含通用设置和主题配置。
  • .vitepress/locales/zh.ts：中文语言特定配置。
  • .vitepress/locales/en.ts：英文语言特定配置。

2. 新增文件介绍 ​

shared.ts ​

此文件包含站点的基础配置和 Teek 主题的配置。这些配置适用于所有语言版本：

  • 站点标题、描述
  • 头部信息（favicon、字体等）
  • Markdown 配置
  • Teek 主题配置（横幅、博主信息、评论等）

zh.ts ​

中文语言配置，包含：

  • 语言设置为 zh-CN
  • 主题配置的中文本地化（如菜单标签、文档页脚等）
  • 中文导航菜单

en.ts ​

英文语言配置，包含：

  • 语言设置为 en-US
  • 主题配置的英文本地化
  • 英文导航菜单

3. 内容文件夹 ​

docs/en/ 文件夹 ​

新增的 docs/en/ 文件夹用于存放英文版本的内容。与中文内容（位于 docs/ 根目录）对应。

例如：

  • 中文文章：docs/08.Frontend/01.HTML/01.基础.md
  • 英文文章：docs/en/08.Frontend/01.HTML/01.Basics.md

4. 语言选择实现 ​

VitePress 和 Teek 主题自动提供语言切换功能：

  • 在导航栏中会显示语言切换按钮
  • 用户可以轻松在中文和英文版本之间切换
  • URL 路径会自动添加语言前缀（如 /en/）

配置示例 ​

config.mts ​

typescript
import shared, { teekConfig } from "./locales/shared";
import zh from "./locales/zh";
import en from "./locales/en";

export default defineConfig({
  ...shared,
  locales: {
    root: { label: "简体中文", ...zh },
    en: { label: "English", ...en },
  },
  themeConfig: {
    socialLinks: [{ icon: "github", link: "https://github.com/Alowree/marapython-teek" }],
  },
  extends: teekConfig,
});

shared.ts ​

包含共享的配置和主题设置。

zh.ts 和 en.ts ​

分别包含各自语言的本地化配置和导航。

注意事项 ​

  1. 确保 docs/en/ 文件夹存在，即使暂时为空。
  2. 导航链接需要根据语言调整路径（中文使用根路径 /，英文使用 /en/ 前缀）。
  3. 主题配置中的标签需要根据语言进行本地化。
  4. 构建时会为每个语言版本生成单独的站点。

后续步骤 ​

  1. 将现有中文内容复制到 docs/en/ 并翻译为英文。
  2. 根据需要调整导航和侧边栏配置。
  3. 测试语言切换功能。
  4. 部署更新后的站点。

通过此迁移，站点现在支持多语言，为不同语言的用户提供更好的体验。

中文/英文内容维护建议 ​

要保持中文和英文版本同步，建议使用相同目录结构、相同页面文件名（或等价 slug），并在英文版本中使用对应的 /en 转换路径。

NOTE

所谓 slug，是指页面 URL 中的最后一段路径标识，它通常来自文件名或页面标题。保持中文和英文页面的 slug 一致，有助于语言切换时找到对应页面。

目录结构建议 ​

  • 中文页面放在 docs/ 根目录下。
  • 英文页面放在 docs/en/ 下。
  • 同一类页面使用一致的子目录结构，例如：
    • docs/10.Marketing/01.极简市场营销.md
    • docs/en/10.Marketing/01.Minimal-Marketing.md

对于测试或正式站点，都建议将英文目录结构与中文目录结构平行，以便语言切换逻辑更清晰。

如何创建英文目录 ​

如果你使用 10.Marketing 作为范例：

  1. 在 docs/en/ 下创建相同的目录：
    • docs/en/10.Marketing/
  2. 在该目录下创建英文对应页面。
  3. 确保英文页面路径与中文页面结构一致。

对于 permalink，建议英文页面保留与中文页面一致的 slug，但可在中文页面中保留原始根路径，在英文页面中使用对应 en 前缀路径；例如：

  • 中文页面：
    • permalink: /10.Marketing/01.minimal-marketing
  • 英文页面：
    • permalink: /en/10.Marketing/01.minimal-marketing

这样做的好处：

  • 中文页面仍然保留原始根路径。
  • 英文页面具有明确的 /en 前缀。
  • 语言按钮可以更容易将用户从中文页面切换到对应英文页面。

在语言切换时跳转到对应页面 ​

理想情况下，语言切换应根据页面路径的 slug 部分进行映射：

  • docs/10.Marketing/01.极简市场营销.md → /10.Marketing/01.minimal-marketing
  • docs/en/10.Marketing/01.Minimal-Marketing.md → /en/10.Marketing/01.minimal-marketing

如果你的主题或插件支持 localeLinks 或语言映射配置，也可以进一步绑定中文页面与英文页面的对应关系。

维护建议 ​

  1. 页面命名一致：尽量使用相同的序号和文件名格式，便于查找和同步。
  2. slug 对应：保持中文与英文页面的 slug 一致，只在 URL 前缀上区分语言。
  3. 同步更新：新增中文页面后，及时在 docs/en/ 下创建相应英文页面；反之亦然。
  4. 避免重复逻辑：配置文件中共享内容放在 .vitepress/locales/shared.ts，语言特定内容放在各自的 zh.ts / en.ts。

通过以上方式，可以让中文和英文版本的页面保持清晰对应，语言切换时也能自动跳转到正确的页面。

迁移到平行目录结构的操作步骤 ​

如果你要把默认语言的中文内容放到 docs/zh/，同时保留英文内容在 docs/en/，可以按下面步骤操作：

  1. 在 docs/ 根目录中创建两个独立目录：

    • docs/zh/
    • docs/en/

  2. 将现有中文文档从 docs/ 根目录搬到 docs/zh/，并保持目录结构一致。例如：

    • docs/10.Marketing/01.极简市场营销.md → docs/zh/10.Marketing/01.极简市场营销.md
    • docs/20.关于/20.关于 - 本站/23.本站 - 国际化.md → docs/zh/20.关于/20.关于 - 本站/23.本站 - 国际化.md

  3. 在 docs/en/ 下创建和中文平行的英文页面目录，这样两个语言目录结构一致，语言切换时更容易对应。

  4. 更新每个页面的 permalink：

    • 中文页面使用 /zh/... 前缀，例如：/zh/10.Marketing/01.minimal-marketing
    • 英文页面使用 /en/... 前缀，例如：/en/10.Marketing/01.minimal-marketing

  5. 修改 .vitepress/config.mts：

    • 将 locales 配置改为：
      ts
      locales: {
  root: { label: "简体中文", ...zh },
  "/zh/": { label: "简体中文", ...zh },
  "/en/": { label: "English", ...en },
},
    • 添加 rewrites：
      ts
      rewrites: {
  "zh/:rest*": ":rest*",
},

  6. 修改 .vitepress/locales/shared.ts：

    • 在 vitePlugins 中添加 sidebarOption.localeRootDir: "zh"
    • 让 Teek 正确识别默认语言内容所在的 docs/zh/ 目录

  7. 重新构建并测试：

    • pnpm run docs:build
    • pnpm run docs:dev

  8. 如果发生 404 或语言切换异常，优先检查：

    • locales 中是否包含 root、/zh/ 和 /en/
    • rewrites 是否存在且生效
    • sidebarOption.localeRootDir 是否已设置为 zh

迁移后的效果 ​

  • docs/zh/ 作为中文文档根目录
  • docs/en/ 作为英文文档根目录
  • 中文站点 URL 规范为 /zh/...
  • 英文站点 URL 规范为 /en/...

这样可以让默认语言和英文语言都拥有独立、平行的目录结构，便于管理和语言切换。

最近更新