1. 为什么我要给一个开源项目从零搭双语 Wiki先交代背景。我手上维护着一个叫 AI Helper 的开源项目定位是给开发者提供一套轻量的 AI 辅助工具集包含文本处理、提示词管理、简单的工作流编排这些模块。项目本身代码量不算大但 issue 和讨论区里反复出现同一类问题新用户不知道怎么配置、某个函数参数到底填什么、示例跑不通是环境问题还是用法问题。文档散落在 README、代码注释和几个零散的 Markdown 文件里中文用户和英文用户看到的内容还不一致。这种状态下我做了个决定给项目从零搭一套双语 Wiki。所谓双语不是简单地把中文机翻成英文丢上去而是中英两套内容结构对齐、术语统一、互相可跳转任何一边更新另一边能同步跟进。这件事听起来像个文档工作实际上它是一套完整的工程实践涉及静态站点选型、目录结构设计、多语言路由、搜索、部署流水线以及最容易被忽略的——长期维护机制。我写这篇东西是想把整个搭建过程完整复盘一遍。适合谁看如果你手上有一个开源项目文档已经开始失控或者你正准备给项目补一套像样的文档站那这篇基本可以照着抄。哪怕你只是想给自己的小工具写个说明页里面的选型思路和避坑经验也能用上。全文我会按“为什么这么设计—核心细节—实操落地—问题排查”的顺序讲中间穿插我踩过的坑和实测有效的做法。2. 整体方案设计与选型思路拆解2.1 先想清楚双语 Wiki 到底要解决什么问题很多人一上来就纠结用什么框架我觉得顺序反了。先明确需求选型是水到渠成的事。我给 AI Helper 的 Wiki 列了这么几条硬需求中英内容结构必须一致。同一个功能点中文页面和英文页面要能一一对应不能中文有五个章节英文只有三个。写作体验要接近纯 Markdown。我不想让贡献者去学一套复杂的模板语法开源项目靠的是社区贡献门槛越低越好。支持全文搜索。文档一多没有搜索等于没有文档。部署要免费且自动化。开源项目没有预算能白嫖的静态托管优先。后续能扩展。今天双语明天可能加日文结构上要留口子。把这五条摆出来方案范围其实就收窄了。纯手写 HTML 不现实重型 CMS 又太重静态站点生成器SSG是最合适的中间地带。2.2 静态站点生成器怎么选我的对比过程我实际对比了三个主流方向这里把关键维度列成表方便你直接对照自己的项目。维度方案A文档型框架方案B通用型框架方案C轻量型框架多语言支持内置 i18n配置即用需插件或手动路由需自行组织目录学习成本低约定优于配置中需要理解路由低搜索集成官方插件成熟需自行接入需自行接入主题定制中等够用高自由度高高构建速度快中等极快适合场景文档站首选官网文档混合极简文档我最后选了方案A这一类文档型框架。理由很直接AI Helper 的核心诉求就是文档不需要花哨的首页动画和复杂交互文档型框架内置的多语言、侧边栏、搜索、版本管理这些能力正好命中我的需求。用通用型框架虽然自由但多语言路由和搜索都要自己搭属于重复造轮子。提示选型时不要被“功能最全”迷惑要看“默认配置是否覆盖你 80% 的需求”。文档站这类项目约定优于配置能省下大量时间。2.3 双语目录结构的设计逻辑这是整个项目里最值得说道的部分。多语言文档有两种常见组织方式第一种是按语言分目录比如docs/zh/和docs/en/各放一套完整内容。第二种是按内容分目录语言作为文件后缀比如guide.zh.md和guide.en.md放在一起。我选了第一种原因是它和文档型框架的 i18n 约定天然契合而且贡献者心智负担小——中文贡献者只进zh目录英文贡献者只进en目录互不干扰。第二种方式虽然文件相邻便于对照但目录里中英文件混在一起时间一长容易乱。具体结构大概是这样docs/ zh/ index.md guide/ getting-started.md configuration.md api/ text-utils.md en/ index.md guide/ getting-started.md configuration.md api/ text-utils.md关键在于两边的相对路径必须完全一致。zh/guide/getting-started.md对应的就是en/guide/getting-started.md。这样语言切换时框架能自动把当前页面映射到另一种语言的同一路径用户不会跳回首页。这个约束我会写进贡献指南作为硬性规则。2.4 术语统一双语项目最容易翻车的地方我见过太多双语项目中文叫“提示词”英文一会儿叫 prompt 一会儿叫 instruction读者直接懵。所以在动手写内容之前我先建了一份术语对照表放在仓库根目录作为翻译和写作的唯一标准。中文术语英文术语说明提示词prompt统一用 prompt不用 instruction工作流workflow不译作 flow文本处理text processing固定搭配配置项configuration option不简写为 config item这份表看起来不起眼但它是双语 Wiki 能长期保持一致的地基。每次新增术语先补表再写内容避免后期大规模返工。3. 核心细节解析与实操要点3.1 环境准备与项目初始化动手之前先把本地环境理清楚。我用的运行时是当前主流的长期支持版本包管理器选了生态兼容性最好的那个。这里不写死具体版本号因为版本迭代快你按官方文档装最新的稳定版就行。初始化步骤大致是在 AI Helper 仓库里新建一个docs-site目录和源码目录平级保持文档工程和代码工程分离。进入目录用包管理器初始化项目安装文档框架及其多语言、搜索相关依赖。创建配置文件声明站点标题、语言列表、导航结构。建立docs/zh和docs/en两个内容目录各放一个index.md作为首页。这里有个细节值得说为什么把文档站单独放一个目录而不是塞进源码里因为文档的构建依赖和源码的构建依赖往往是两套东西混在一起会让依赖树变得臃肿CI 也不好拆分。分开之后文档可以独立构建、独立部署源码仓库的贡献者也不会被文档依赖干扰。3.2 配置文件的关键参数怎么填配置文件是整个站点的中枢我挑几个容易填错的参数讲。语言列表要同时声明默认语言和所有支持的语言。默认语言决定了根路径/指向哪套内容。我建议把英文设为默认因为开源项目的国际访客占比通常更高中文作为第二语言挂在/zh/下。导航与侧边栏不要手动维护一份巨大的侧边栏配置而是让框架根据目录结构自动生成。手动维护的侧边栏在双语场景下是灾难——你改了一边忘了另一边两边导航就对不上了。自动生成的前提就是前面说的“两边目录结构完全一致”。搜索文档型框架一般有官方搜索插件支持本地索引不需要外部服务。配置时注意把两种语言都纳入索引范围否则中文用户搜不到英文内容反之亦然。如果你的用户群体确实需要跨语言搜索可以开启如果不需要按语言隔离搜索体验更清爽。注意搜索索引是在构建时生成的内容更新后必须重新构建才会生效。本地开发时热更新可能不刷新索引测试搜索功能记得跑一次完整构建。3.3 内容写作规范让贡献者不跑偏文档站搭好只是开始真正决定质量的是内容规范。我给 AI Helper 定了几条写作规则写进了贡献指南每个页面开头必须有一句话概述说明这个页面解决什么问题方便搜索引擎和用户快速判断。代码示例必须可运行且中英两版代码完全一致只有注释语言不同。截图和示意图统一存放在docs/public下中英共用避免重复资源。内部链接使用相对路径不要写死语言前缀让框架自动处理语言映射。这几条里最后一条最容易被忽略。如果你在中文页面里写死了/en/guide/xxx这样的绝对链接用户从中文页点过去会直接跳到英文页体验割裂。用相对路径框架会根据当前语言自动补全前缀。3.4 版本管理与内容同步机制开源项目的文档会随版本变化。我的做法是主分支的文档永远对应最新开发版发布版本通过标签或分支冻结。文档框架一般支持版本化配置可以同时展示多个版本的文档用户在页面顶部切换。内容同步方面我不追求“实时同步”而是采用以中文为主、英文跟进的策略。原因很现实核心维护者写中文更快英文翻译依赖社区。具体流程是中文内容先合并然后在英文目录建一个占位文件标注“待翻译”并开一个对应的 issue 跟踪。这样既保证了结构完整路径存在语言切换不报错又不会因为翻译滞后阻塞中文更新。4. 实操过程与核心环节实现4.1 从零到本地跑通完整命令流程下面是我实际操作的完整流程你可以直接照着走。假设你已经装好了运行时和包管理器。第一步创建并进入文档工程目录mkdir docs-site cd docs-site第二步初始化项目并安装依赖。不同框架的初始化命令不一样文档型框架通常提供一个交互式脚手架按提示选择“文档模式”和需要的语言即可。安装完成后你会得到一个带默认配置的项目骨架。第三步调整目录结构把默认生成的内容目录改造成zh和en双目录mkdir -p docs/zh docs/en第四步修改配置文件声明语言和导航。核心是设置默认语言、语言列表以及让侧边栏从目录自动生成。第五步启动本地开发服务器npm run docs:dev浏览器打开本地地址你应该能看到默认语言的首页。手动访问/zh/路径确认中文首页也能正常渲染。这一步验证的是多语言路由是否生效。4.2 语言切换与路由映射的验证方法多语言最容易出问题的地方就是路由映射。我设计了一个简单的验证清单每次改完配置都跑一遍在中文首页点击语言切换看是否跳到英文首页而不是英文的某个子页面。在中文的深层页面比如zh/guide/configuration切换语言看是否跳到en/guide/configuration路径层级完全对应。如果某个英文页面还没翻译切换过去应该显示占位内容或 404 提示而不是白屏或报错。第 3 点特别重要。很多项目在翻译不全的时候语言切换直接 404用户以为站点坏了。我的做法是给未翻译页面放一个统一的占位模板写明“该页面英文版正在翻译中欢迎贡献”并附上贡献入口。这样既诚实又能把访客转化成贡献者。4.3 搜索功能的接入与调优搜索是文档站的生命线。我接入的是框架官方搜索插件配置过程不复杂但有几个调优点值得说。索引范围默认可能只索引默认语言。要在配置里显式声明索引所有语言否则中文用户搜不到中文内容。分词问题中文和英文的分词逻辑不同。英文按空格切词中文需要专门的分词支持。好在主流文档框架的搜索插件对中文支持已经比较成熟配置时确认开启了中文分词选项即可。结果排序默认按匹配度排序但文档站里“标题命中”通常比“正文命中”更重要。如果插件支持权重配置把标题权重调高用户搜一个功能名对应的页面会排在前面。实测下来搜索配置好之后用户查配置项、查函数名的效率提升非常明显issue 里“这个参数怎么用”这类问题少了一大截。4.4 自动化部署流水线搭建部署我选的是静态托管平台和代码仓库打通推送到主分支自动构建发布。核心是一份 CI 配置文件大致逻辑是# 伪代码示意具体语法按平台文档调整 steps: - 检出代码 - 安装运行时和依赖 - 执行文档构建命令 - 将构建产物发布到托管平台这里有几个实操要点构建命令要区分开发和生产。开发用docs:dev生产用docs:buildCI 里必须用后者。缓存依赖目录。文档站依赖安装可能比较慢缓存node_modules能显著缩短构建时间。构建失败要能通知。配置构建失败时发送通知到项目讨论区或邮件避免文档悄悄挂掉没人知道。我踩过的一个坑是本地构建正常CI 上却失败最后发现是 CI 环境的运行时版本和本地不一致。解决办法是在 CI 配置里锁定运行时版本和本地保持一致。4.5 自定义域名与访问路径处理如果项目托管在子路径下比如example.com/ai-helper/需要在配置里设置基础路径否则所有静态资源CSS、JS、图片都会 404。这个参数叫base或baseUrl不同框架叫法不同但作用一样。设置之后本地开发时可能反而访问异常因为本地是根路径。所以我的习惯是本地开发不设基础路径生产构建时通过环境变量注入。这样两边都不受影响。5. 常见问题与排查技巧实录5.1 双语 Wiki 高频问题速查表下面这张表是我在实际维护中整理出来的基本覆盖了 90% 的常见故障。现象可能原因排查与解决语言切换跳回首页两边目录结构不一致检查对应路径的文件是否都存在静态资源 404基础路径未配置设置 base 参数为部署子路径搜索搜不到中文索引未包含中文或未开分词检查搜索插件语言配置侧边栏中英不一致手动维护了侧边栏改为目录自动生成构建成功但页面空白路由或组件配置错误本地跑生产构建预览排查内部链接跳到错误语言使用了绝对路径改为相对路径5.2 我踩过的三个真实坑第一个坑目录结构不一致导致语言切换失效。早期我在英文目录少建了一个api子目录结果中文 API 页面切换语言时直接 404。后来我写了个简单的校验脚本在 CI 里对比两个语言目录的文件列表不一致就构建失败。这个脚本不长但省了无数手动检查。第二个坑图片路径写死语言前缀。我在中文页面里写了/zh/images/xxx.png结果英文页面引用同一张图时路径不对。正确做法是把图片放在公共目录用相对路径引用让框架统一处理。第三个坑翻译滞后导致内容误导。有一次中文文档更新了配置项说明英文还是旧的英文用户按旧文档操作直接报错。从那以后我养成了习惯中文内容有破坏性变更时同步更新英文哪怕只是加一句“此页面内容已过期请参考中文版”。5.3 让贡献者愿意写文档的几个小设计文档站搭得再好没人写内容也是空的。我做了几件事来降低贡献门槛在页面底部加“编辑此页”链接直接跳到对应 Markdown 文件的编辑界面省去贡献者找文件的时间。提供页面模板新建文件时复制模板自动带上概述、章节结构、术语规范提示。在贡献指南里明确“翻译不算低人一等”把翻译和原创内容同等对待鼓励双语贡献者。实测下来“编辑此页”这个链接带来的贡献转化最明显。用户看到文档里有个错别字顺手就能改不用去研究仓库结构。5.4 内容更新后的回归检查清单每次合并文档改动我会跑一遍这个清单确保没有引入回归本地生产构建是否通过。中英目录结构是否仍然一致。语言切换在首页和深层页面是否都正常。搜索能否搜到新加的内容。内部链接是否都能点通没有死链。移动端布局是否正常文档站移动端访问占比不低。这套清单跑下来大概五分钟但能挡住绝大多数低级错误。我把它写进了 CI能自动化的部分构建、死链检查自动跑剩下的人工确认。6. 后续可扩展的方向与个人体会这套双语 Wiki 跑了大半年整体是稳的。如果后面要继续扩展我脑子里有几个方向。一是加第三语言结构上已经留好了口子无非是多一个语言目录和一份术语表。二是把 API 文档从手写改成从代码注释自动生成减少人工维护成本但前提是代码注释规范要跟上。三是接入文档质量检查工具自动检测死链、拼写错误和术语不一致。我个人在实际操作中的体会是搭文档站这件事技术难度不高难的是长期一致性。双语项目尤其如此两套内容就像两条腿任何一条落后都会让整体走不稳。所以与其追求一次搭得多完美不如先把结构约束和同步机制定死让后续每一次更新都有章可循。工具会过时框架会换代但“结构对齐、术语统一、更新有据”这三条原则换什么工具都成立。最后再分享一个小技巧如果你也在维护开源项目不妨在 README 顶部放一个显眼的文档站入口并且在每个 issue 的自动回复里附上相关文档链接。文档写得再好用户找不到也是白搭。入口这件事怎么强调都不过分。