Repomix 多语言文档站维护指南：基于 VitePress 的 15 语言内容架构与翻译工作流

Repomix 官网文档（website/ 目录）是一个基于 VitePress 构建的多语言静态站点，目前注册了包括英语（站点根）在内的 15 个 locale。本文以 website/.claude/skills/website-maintainer/SKILL.md 为骨架，结合仓库中的真实配置与源码，完整讲解文档站的目录结构、"配置与内容分离"的三层配置架构、新增语言的标准流程、内容编辑规范与翻译准则，并给出本地开发与生产构建的实操命令。读完本文，你将能够独立维护 Repomix 文档站的任意语言版本，并可为站点新增一种语言。

一、站点概览：一套 VitePress 配置，驱动十五种语言

Repomix 文档站的技术栈为 VitePress（静态站点生成器）+ Vue.js（页面组件），见 website/README.md。SKILL.md 开头即声明这是 "VitePress documentation site with 14 languages"；而从当前仓库的源码看，语言规模已经增长：

• 主配置 website/client/.vitepress/config.ts 的 locales 中注册了 15 个条目：root（英语）、zh-cn、zh-tw、ja、es、pt-br、ko、de、fr、it、hi、id、vi、ru、tr；
• 内容目录 website/client/src 下同样存在 15 个语言目录（de、en、es、fr、hi、id、it、ja、ko、pt-br、ru、tr、vi、zh-cn、zh-tw），每个目录内是 guide/ 下的 26 篇指南文档加一个 index.md。

即 SKILL.md 撰写时列出的 14 种语言已不包含土耳其语（tr），当前仓库实际为 15 个 locale。维护时以实际配置文件为准，下文涉及语言清单处均以源码为准。

二、目录结构：配置与内容严格分离

SKILL.md 给出了文档站的目录骨架，结合仓库实际，完整结构如下：

website/client/
├── .vitepress/
│   ├── config.ts                 # 主配置：导入全部语言配置并注册 locales
│   └── config/
│       ├── configShard.ts        # 共享设置：PWA、sitemap、搜索、SEO 等
│       └── config[Lang].ts       # 分语言配置：nav、sidebar、search
└── src/
    └── [lang]/                   # de, en, es, fr, hi, id, it, ja, ko,
                                  # pt-br, ru, tr, vi, zh-cn, zh-tw
        ├── index.md
        └── guide/                # 各语言的 26 篇指南文档

职责划分非常清晰：

• .vitepress/config.ts：整个站点的唯一入口配置，负责把共享配置与各语言配置合并为一个完整的 VitePress 配置对象；
• .vitepress/config/configShard.ts：所有语言公用的设置（站点元信息、主题、SEO、搜索、PWA、sitemap 等）；
• .vitepress/config/config[Lang].ts：每个语言一份，导出该语言的 config 与 search 翻译两份内容；
• src/<a href="https://link.gitcode.com/i/46e0aad61549f07f0f323a48ce95f886" target="_blank">lang]/guide/*.md：纯文档内容，例如 [website/client/src/ja/guide/installation.md 与 website/client/src/zh-cn/guide/installation.md 对应同一篇"安装"指南。

三、三层配置架构解析

3.1 主配置 config.ts：locales 注册表

website/client/.vitepress/config.ts 是配置聚合的枢纽：先导入 configShard，再用展开语法把每个语言配置挂到 locales 下：

export default defineConfig({
  ...configShard,
  locales: {
    root: { label: 'English', ...configEnUs },
    'zh-cn': { label: '简体中文', ...configZhCn },
    'zh-tw': { label: '繁體中文', ...configZhTw },
    ja: { label: '日本語', ...configJa },
    es: { label: 'Español', ...configEs },
    'pt-br': { label: 'Português', ...configPtBr },
    ko: { label: '한국어', ...configKo },
    de: { label: 'Deutsch', ...configDe },
    fr: { label: 'Français', ...configFr },
    it: { label: 'Italiano', ...configIt },
    hi: { label: 'हिन्दी', ...configHi },
    id: { label: 'Indonesia', ...configId },
    vi: { label: 'Tiếng Việt', ...configVi },
    ru: { label: 'Русский', ...configRu },
    tr: { label: 'Türkçe', ...configTr },
  },
});

两个值得注意的实现细节：

• 英语是站点根：root 挂载 configEnUs，配合共享配置中的 rewrites: { 'en/:rest*': ':rest*' }（见 configShard.ts），磁盘上位于 en/ 的文档被重写到站点根路径，因此英语页面 URL 不带语言前缀，而其他语言保留 /zh-cn/、/ja/ 这样的前缀；
• 生产部署守卫：config.ts 在模块加载阶段判断 Cloudflare Pages / Workers 生产部署（CF_PAGES_BRANCH === 'main' 或 WORKERS_CI_BRANCH === 'main'），若缺少 VITE_TURNSTILE_SITE_KEY 环境变量则直接 throw，让构建立刻失败。原因是 VitePress 的 SSR 会吞掉组件内抛出的错误并返回退出码 0，若不在配置阶段拦截，缺失站点密钥会静默上线一个"永远通过"的测试用 Turnstile 校验。

3.2 分语言配置 config[Lang].ts：导航、侧边栏与搜索

每个语言文件同时导出站点配置与搜索翻译两份内容，这正是 SKILL.md 中 "exports config + search translations" 所指。以 website/client/.vitepress/config/configEnUs.ts 为例：

export const configEnUs = defineConfig({
  lang: 'en-US',
  description: 'Pack your codebase into AI-friendly formats',
  themeConfig: {
    nav: [
      { text: 'Guide', link: '/guide/', activeMatch: '^/guide/' },
      { text: 'Chrome Extension', link: 'https://chromewebstore.google.com/...' },
      { text: 'Join Discord', link: 'https://discord.gg/wNYzTwZFku' },
    ],
    sidebar: {
      '/guide/': [
        { text: 'Introduction', items: [/* Getting Started、Installation、Usage ... */] },
        { text: 'Guide', items: [/* Output Formats、Configuration、Security ... */] },
        { text: 'Advanced', items: [/* MCP Server、GitHub Actions ... */] },
        { text: 'Community', items: [/* Sponsors、Privacy Policy ... */] },
      ],
    },
  },
});

themeConfig.sidebar 按 /guide/ 前缀挂载，组成了每个语言的完整文档导航树。修改导航、侧边栏就是在对应语言的这个文件里操作（对应 SKILL.md 的 "Navigation/Sidebar: Edit config/config[Lang].ts → themeConfig.sidebar"）。

3.3 共享配置 configShard.ts：一处修改，全站生效

website/client/.vitepress/config/configShard.ts 承载了所有语言共用、以及跨语言统一管理的设置，主要包含：

配置项	作用
title / srcDir: 'src' / srcExclude: ['shared/**']	站点名、内容目录、排除 shared/ 共享片段
rewrites	将 en/:rest* 重写到站点根，英语 URL 无前缀
lastUpdated / cleanUrls / metaChunk	文档更新时间、无后缀 URL、元数据分包
sitemap.hostname	站点地图根地址
transformHead（createPageHead）	每页注入 canonical、hreflang、OpenGraph 与 JSON-LD
themeConfig.search	本地搜索，合并 13 份语言搜索翻译
themeConfig.logo/footer/socialLinks/langMenuLabel	全局 UI 与语言切换菜单
vite 插件	VitePWA（PWA 支持）、llmstxt（生成 llms.txt）、visualizer（打包体积分析）

几个与"可被搜索引擎、Agent 和 LLM 理解"直接相关的实现值得展开：

• SEO head 生成：configShard.ts 中的 createPageHead 为每个页面生成 canonical 链接、全语言 hreflang 交替链接（含 x-default 回退到英语）、og:title/url/description/locale 及 og:locale:alternate，并为文档页输出 TechArticle 类型的 JSON-LD 结构化数据；页面语言通过 localeConfig（BCP-47 形式）映射，保证 hreflang 与 Schema.org inLanguage 一致；
• 搜索的本地化：themeConfig.search 使用 VitePress 内置的 local 搜索，并将 configDeSearch、configEsSearch、configJaSearch、configZhCnSearch 等 13 份搜索翻译合并进 locales 选项，使搜索弹窗的提示文案跟随界面语言（英语 root 使用默认文案，无需额外配置）；
• LLM 可发现性：通过 vitepress-plugin-llms（configShard.ts）为英文站点生成 llms.txt，供 LLM 与 Agent 发现文档入口，同时 ignoreFiles: ['guide/sponsors.md'] 排除非技术页面；
• PWA：vite-plugin-pwa 注册 autoUpdate 模式，manifest 使用 pwa/repomix-192x192.png 与 512px 图标（见 website/client/src/public/images/pwa）。

四、新增语言：标准四步流程

SKILL.md 给出了新增语言的操作流程，逐条对照仓库源码验证如下：

第 1 步：创建 config/configXx.ts。以现有语言文件为模板，导出该语言的 config（含 lang、description、themeConfig.nav/sidebar）与 search 翻译。可参考 configEnUs.ts 的结构。

第 2 步：在主配置中注册。在 config.ts 顶部 import { configXx } from './config/configXx'，并在 locales 对象中新增 'xx': { label: '本地语言名', ...configXx }。注意主配置的导入语句分散在文件中部（首条 import 之后才做环境变量守卫的 throw），新增导入应保持同样位置。

第 3 步：把搜索配置合并进 configShard.ts。在 configShard.ts 的 themeConfig.search.options.locales 中展开 ...configXxSearch。这一步决定了新语言的搜索弹窗是否被本地化。

第 4 步：创建 src/xx/ 内容目录。复制 en/ 的内容到新语言目录，逐个翻译 index.md 与 guide/ 下的 26 篇文档。

补充两点基于源码的注意项：

• URL 前缀是自动形成的：supportedLocales 与 buildLocaleUrl（见 configShard.ts）会自动为新语言生成 /xx/ 前缀的 URL，并在每个页面的 hreflang 交替链接中带上新语言，无需手工维护语言跳转；
• localeConfig 需要同步登记：configShard.ts 的 localeConfig 集中维护每个语言的 BCP-47 与 OpenGraph 形式（如 'pt-br': { bcp47: 'pt-BR', og: 'pt_BR' }），注释明确指出"三份信息放在一起防止新增语言时漂移"，新增语言时应在此登记。

五、内容编辑指南

SKILL.md 把日常维护工作分成三类，仓库中的对应位置如下：

要改什么	改哪里
文档正文	src/<a href="https://link.gitcode.com/i/a90b0aa3d9c852b48e99fb443adfc0a1" target="_blank">lang]/guide/*.md，例如 [website/client/src/en/guide/configuration.md
导航 / 侧边栏	config/config[Lang].ts 中的 themeConfig.sidebar 与 nav
共享设置（logo、footer 等）	website/client/.vitepress/config/configShard.ts

其中"共享设置"一节值得特别说明：logo、footer、社交链接、语言菜单标签都集中在 configShard.ts 的 themeConfig（见 configShard.ts），修改一次即可全站生效，这正是 SKILL.md 把它单列为编辑入口的原因。

六、翻译准则

SKILL.md 的翻译部分只有三条，但每一条都在仓库中能找到印证：

1. 英语（src/en/）是唯一事实来源。这与 website/README.md 的说明一致："When updating documentation, you only need to update the English version (client/src/en/). The maintainers will handle translations to other languages." 即贡献者只需维护英文，翻译由维护者协调完成；
2. 代码示例与 CLI 选项保持原样。文档中的命令、参数、配置片段属于机器可读内容，任何语言的翻译都不得改动，保证文档"可复制、可运行"；
3. 配置文件中的 UI 标签（nav、sidebar、搜索弹窗）需要翻译。这些文案出现在 config[Lang].ts 的 themeConfig.nav / sidebar 以及每份搜索翻译中，属于界面文案，需要随语言本地化。

另有一个易被忽略的实现细节：configShard.ts 通过 srcExclude: <a href="https://link.gitcode.com/i/da84d564921daebb61a8787e84324560" target="_blank">'shared/**'] 把 src/shared/ 目录（如 [website/client/src/shared/sponsors-section.md）排除出构建，该目录用于存放跨语言复用的公共片段，这也是"共享设置"类内容的第三种存放位置。

七、本地开发、构建与部署

7.1 开发环境

仓库根目录提供了聚合脚本（见 website/README.md），前置条件为安装 Docker：

# 启动文档站开发服务器
npm run website

# 访问 http://localhost:5173/

若直接在 website/client 目录内工作，website/client/package.json 提供了 VitePress 原生脚本：

npm run docs:dev       # vitepress dev，启动开发服务器
npm run docs:build     # vitepress build，产出静态文件
npm run docs:preview   # vitepress preview，本地预览构建产物
npm run lint-tsc       # tsc --noEmit 类型检查

7.2 生产构建

npm run website:build

构建产物输出到 client/dist 目录。文档站的构建链路中还有两个生产环境专属要求：

• Cloudflare 部署密钥：生产分支（main）部署到 Cloudflare Pages / Workers 时，必须配置 VITE_TURNSTILE_SITE_KEY 环境变量，否则构建在配置加载阶段直接失败（见 config.ts）；PR 预览、分支构建与本地构建按设计不受此限制，使用测试密钥；
• 静态资源优化：构建时会生成 stats.html 体积分析报告（rollup-plugin-visualizer 的 treemap 视图），可用于排查各语言包与组件对产物体积的影响。

结语

Repomix 文档站以"主配置 + 共享配置 + 分语言配置"的三层结构，把 15 种语言的内容、导航与 SEO 元数据管理得清晰可控。无论是日常修改某个语言的文档、调整侧边栏，还是从零新增一种语言，只要沿着 website/client/.vitepress/config.ts → config/config[Lang].ts → src/[lang]/guide/ 这条链路操作，就能在保持英文为唯一事实来源的前提下，让每个语言的文档站保持结构一致、翻译规范、可被搜索引擎与 LLM 有效索引。