Repomix 多语言文档站维护指南基于 VitePress 的 15 语言内容架构与翻译工作流【免费下载链接】repomix Repomix is a powerful tool that packs your entire repository into a single, AI-friendly file. Perfect for when you need to feed your codebase to Large Language Models (LLMs) or other AI tools like Claude, ChatGPT, DeepSeek, Perplexity, Gemini, Gemma, Llama, Grok, and more.项目地址: https://gitcode.com/GitHub_Trending/rep/repomixRepomix 官网文档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/[lang]/guide/*.md纯文档内容例如 website/client/src/ja/guide/installation.md 与 website/client/src/zh-cn/guide/installation.md 对应同一篇安装指南。三、三层配置架构解析3.1 主配置 config.tslocales 注册表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: Editconfig/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站点地图根地址transformHeadcreatePageHead每页注入 canonical、hreflang、OpenGraph 与 JSON-LDthemeConfig.search本地搜索合并 13 份语言搜索翻译themeConfig.logo/footer/socialLinks/langMenuLabel全局 UI 与语言切换菜单vite插件VitePWAPWA 支持、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 结构化数据页面语言通过localeConfigBCP-47 形式映射保证hreflang与 Schema.orginLanguage一致搜索的本地化themeConfig.search使用 VitePress 内置的local搜索并将configDeSearch、configEsSearch、configJaSearch、configZhCnSearch等 13 份搜索翻译合并进locales选项使搜索弹窗的提示文案跟随界面语言英语 root 使用默认文案无需额外配置LLM 可发现性通过vitepress-plugin-llmsconfigShard.ts为英文站点生成llms.txt供 LLM 与 Agent 发现文档入口同时ignoreFiles: [guide/sponsors.md]排除非技术页面PWAvite-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/[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 的翻译部分只有三条但每一条都在仓库中能找到印证英语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. 即贡献者只需维护英文翻译由维护者协调完成代码示例与 CLI 选项保持原样。文档中的命令、参数、配置片段属于机器可读内容任何语言的翻译都不得改动保证文档可复制、可运行配置文件中的 UI 标签nav、sidebar、搜索弹窗需要翻译。这些文案出现在config[Lang].ts的themeConfig.nav/sidebar以及每份搜索翻译中属于界面文案需要随语言本地化。另有一个易被忽略的实现细节configShard.ts通过srcExclude: [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.tsPR 预览、分支构建与本地构建按设计不受此限制使用测试密钥静态资源优化构建时会生成stats.html体积分析报告rollup-plugin-visualizer的 treemap 视图可用于排查各语言包与组件对产物体积的影响。结语Repomix 文档站以主配置 共享配置 分语言配置的三层结构把 15 种语言的内容、导航与 SEO 元数据管理得清晰可控。无论是日常修改某个语言的文档、调整侧边栏还是从零新增一种语言只要沿着 website/client/.vitepress/config.ts →config/config[Lang].ts→src/[lang]/guide/这条链路操作就能在保持英文为唯一事实来源的前提下让每个语言的文档站保持结构一致、翻译规范、可被搜索引擎与 LLM 有效索引。【免费下载链接】repomix Repomix is a powerful tool that packs your entire repository into a single, AI-friendly file. Perfect for when you need to feed your codebase to Large Language Models (LLMs) or other AI tools like Claude, ChatGPT, DeepSeek, Perplexity, Gemini, Gemma, Llama, Grok, and more.项目地址: https://gitcode.com/GitHub_Trending/rep/repomix创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考