AI Helper 实战：从零搭建开源项目的双语 Wiki

AI Helper 实战：从零搭建开源项目的双语 Wiki# AI Helper 实战：从零搭建开源项目的双语 Wiki

一个开源项目，如何用一套 Markdown 源文件同时维护中英双语文档，并自动部署成文档站？本文以 AI Helper（GitHub 开源浏览器智能助手）为例，完整复盘双语 Wiki 从 0 到 1 的搭建过程：目录设计、i18n 机制、同步策略、Pages 部署，以及那些只有踩过坑才知道的经验。

一、为什么开源项目需要双语 Wiki

项目开源到 GitHub 之后，我很快意识到一个问题：文档的语言，决定了项目的边界。

中文开发者看中文文档，英文开发者看英文文档，两者都希望"打开就能读懂"；
一个只有中文 README 的仓库，海外用户大概率直接划走，Star、Issue、PR 都会少一大截；
反过来，如果只有英文文档，国内开发者会觉得门槛高、不友好。

所以，双语 Wiki 不是"锦上添花"，而是开源项目走向更广社区的基础设施。

AI Helper 是一个让大模型真正操作网页的开源浏览器智能体（Chrome / Edge 扩展 + 本地 Agent 服务），代码仓库在 GitHub 与 Gitee 双平台同步。项目从一开始就决定：文档必须中英双语，且用一套 Markdown 源文件维护，而不是维护两份互相脱节的文档。

二、整体设计：一套源文件，两种语言

双语 Wiki 最常见的失败模式是"各写各的"------中文文档和英文文档内容漂移，改了一边忘了另一边，最后两边的读者看到的都是过时信息。

AI Helper 的做法是以"同一份内容骨架"为锚，按语言各自成文：

bash 复制代码

ai-helper/
├── README.md              # 英文总览（面向海外用户）
├── README.zh-CN.md        # 中文总览（面向国内用户）
├── docs/
│   ├── zh/
│   │   └── DOCUMENTATION.md   # 中文完整技术文档（约 6 万字符）
│   ├── en/
│   │   └── DOCUMENTATION.md   # 英文完整技术文档（约 6 万字符）
│   ├── articles/              # 推广文章（按平台组织）
│   └── images/ videos/        # 图文与演示视频
└── scripts/
    └── deploy-pages.sh        # 文档站部署脚本

关键点在于：

结构镜像 ：docs/zh/ 与 docs/en/ 目录结构一一对应，章节顺序保持一致，方便对照维护；
顶部互链 ：每份文档顶部都放语言切换链接（中文文档 ↔ English Docs），读者一键跳转；
README 双语分文件 ：README.md 与 README.zh-CN.md 各自独立，避免在一个文件里塞两种语言造成阅读混乱；
内容同源：功能、配置、FAQ 等"事实性内容"保证两边一致，只是语言不同。

三、目录设计：让读者 30 秒找到想要的东西

文档不是越厚越好，而是结构越清晰越好。AI Helper 的完整文档（DOCUMENTATION.md）采用固定目录骨架：

复制代码

架构总览 → 核心数据流 → 项目结构 → 核心功能 → 内建工具
→ 技术栈 → 代理服务 → 快速开始 → 配置说明 → 状态管理设计 → 常见问题

这套目录的设计原则：

先讲"是什么"再讲"怎么用"：架构总览、数据流放在最前，让读者先建立整体认知；
"快速开始"独立成章：想立刻上手的读者不用翻完整份文档，直接跳到安装步骤；
配置说明用表格：参数名、默认值、说明三列，一眼扫完；
FAQ 兜底：把高频问题集中放在末尾，减少 Issue 重复提问。

一个实用技巧：文档里的代码块、架构图、表格尽量用"与语言无关"的形式（ASCII 架构图、命令、配置项），这样翻译时只需处理文字部分，工作量骤减。

四、i18n 机制：给模型看的和给人看的，分开处理

搭建双语 Wiki 时，最容易踩的坑是把"国际化"简单理解为"翻译"。实际上，开源项目的国际化包含多个层面：

1. 仓库文档层（Wiki）

README 与 DOCUMENTATION 按语言分文件维护；
用 Markdown 源文件，天然支持 GitHub / Gitee 渲染，也方便后续转 HTML 发布到技术社区。

2. 产品 UI 层（插件本身）

AI Helper 的插件 UI 也做了完整 i18n，这里用到了双轨机制：

manifest.json 的 name / description / commands ：走 Chrome 原生的 chrome.i18n（_locales/{en,zh}/messages.json + __MSG_xxx__ 占位符），这是 Chrome 扩展的强制要求；
JS 与 HTML 中的所有文案 ：自建轻量 i18n 模块 t(key, params)，支持点分嵌套 key、{name} 参数插值、运行时语言切换、订阅刷新。

3. 一条重要原则：给模型看的用英文，给人看的按语言切换

这一点在文档和产品里都适用：

给 LLM 看的工具描述、系统提示词：统一用英文，大模型理解英文无障碍，且固定英文能减少 Token 消耗；
给用户在 UI 上看的文案：走 i18n，按语言切换；
代码注释、logger 日志：保留中文，方便开发者维护，不影响用户。

这条原则帮我省了大量成本------如果连调试日志都要国际化，改造成本翻倍且没有实际收益。

五、内容同步：如何让两份文档不"漂移"

双语文档最大的敌人是内容漂移。我的实践方法：

1. 结构先行，内容跟随

先定章节骨架，再逐章翻译。每次新增功能时，先更新中文文档，再同步英文文档，保持"一次变更，两边落地"的节奏。

2. 用"事实性内容"做锚点

架构图、配置表、命令、FAQ 这类事实性内容，两边必须完全一致。翻译时只改语言，不改事实。这样即使文字风格有差异，信息也不会失真。

3. 借助 AI 提效

既然项目本身就是 AI Helper，我直接用 AI Helper 的划词翻译、文档撰写助手来辅助翻译------先让 AI 生成初稿，再人工校对术语。特别是英文文档，AI 初稿 + 人工润色，效率比纯手写高很多。

4. 发布前交叉检查

每次发布新版本前，用脚本对比两份文档的章节标题，确保结构一致；再抽查关键配置项，防止漏改。

六、文档站部署：GitHub Pages + Gitee Pages 双端

文档除了在仓库里，还要有一个可访问的文档站 。AI Helper 用 scripts/deploy-pages.sh 实现一键部署：

bash 复制代码

# 推送到 gh-pages 分支（Gitee Pages 需要）
bash scripts/deploy-pages.sh

# 预览将要推送的内容
bash scripts/deploy-pages.sh --dry

部署策略：

GitHub Pages ：从 main 分支的 docs/ 子目录自动部署，无需额外脚本；
Gitee Pages ：用 git subtree push --prefix docs 把 docs/ 推到 gh-pages 分支，再在 Gitee 后台点「更新」；
双远端 ：脚本同时支持 origin（GitHub）与 gitee 两个 remote，一次命令两端同步。

最终文档站地址：xiweicheng.github.io/ai-helper/

七、踩过的坑与经验教训

坑 1：i18n 改造越晚越痛

AI Helper 最初是纯中文硬编码，1500~2000 处文案，后期逐个替换非常痛苦。如果项目初期就建立 i18n 基础设施，新增功能时顺手用 t() 调用，成本会低一个数量级。

坑 2：工具返回给模型的消息也要 i18n

工具执行结果会作为上下文返回给模型，模型会参考这个语言来回复用户。如果工具返回中文错误消息，即使用户用英文提问，模型也可能用中文回复，体验很割裂。工具描述给模型用英文固定，返回给用户的消息走 i18n------双轨制解决了这个问题。

坑 3：文档"翻译"不等于"本地化"

翻译只是把文字换一种语言，本地化还要考虑：

术语表：建立中英术语对照（如 ReAct、MCP、Skill、Agent），全项目统一；
示例本地化：中文文档用国内读者熟悉的例子（如 DeepSeek、通义千问），英文文档用国际读者熟悉的例子；
链接本地化：中文文档链到中文文档，英文文档链到英文文档，别让读者跳转到错误语言页面。

坑 4：不要为了"双语"牺牲可维护性

有些项目用"同一文件里中英混排"或"自动机器翻译"来省事，短期看快，长期看维护成本极高。一套源文件 + 结构镜像 + 双轨 i18n，才是可持续的方案。

八、成果与收益

双语 Wiki 搭建完成后，最直观的收益：

海外用户能看懂：英文 README + 英文文档 + 英文 UI，海外开发者可以无障碍上手；
国内用户有归属感：中文文档 + 中文社区，国内开发者愿意参与贡献；
文档站统一入口：一个地址承载全部文档，配合 Edge 商店上架，形成"仓库 → 文档站 → 商店"的完整链路；
社区反馈更集中：FAQ 覆盖高频问题，Issue 质量明显提升。

九、写在最后

搭建双语 Wiki 没有太多"高深技术"，更多是结构设计 + 持续维护 的耐心活。但它是开源项目走向更广社区的关键一步------文档的语言，就是项目的边界；打破语言边界，就是打破社区边界。

如果你也在维护开源项目，不妨从今天开始：

先搭好 README.md + README.zh-CN.md 的双语骨架；
建立 docs/zh 与 docs/en 的结构镜像；
定一份中英术语表；
用 Pages 把文档站跑起来。

项目信息：

GitHub ：github.com/xiweicheng/...
Gitee ：gitee.com/xiweicheng/...
文档站 ：xiweicheng.github.io/ai-helper/
Edge 商店：已上架 Microsoft Edge Add-ons
开源协议：MIT License

欢迎 Star、试用、提 Issue、提 PR ------ 开源项目，一起把它做得更好。

本文基于 AI Helper 开源项目实战经验撰写，欢迎转载，请注明出处。