英文技术文档中文化

把英文技术文档（README、官方 Docs、教程）改写成中文开发者能直接照着做的版本。

核心不是翻译，是重写。

使用时机

• 官方文档只有英文，需要做中文教程
• 想把开源项目文档整理成中文站内容
• 需要把零散的英文说明整合成系统教程

三条铁律

铁律 1：术语分层处理

类型	处理方式	示例
产品名	保留英文	Hermes、OpenClaw、Docker、Nginx
协议/标准	保留英文	MCP、HTTP、OAuth、WebSocket
文件名/命令	保留原样	config.yaml、npm install
通用技术词	首次”英文（中文）“，后文中文	Agent（智能体）→ 后文用”智能体”
纯英文缩写	首次给全称	API → 应用程序接口（API）
行业黑话	用国内通行说法	deploy → 部署，not 布署

铁律 2：结构重组，不逐句翻

英文文档常见结构：

Installation
├─ Prerequisites
├─ Quick Start
└─ Advanced

中文读者更习惯：

一、安装前准备（对应 Prerequisites）
二、最快上手路径（对应 Quick Start）
三、进阶配置（对应 Advanced）
四、常见问题（原文没有，我们补）

关键补充：

• 国内网络环境提示（镜像源、代理）
• Windows 用户注意事项
• 国内平台差异（微信 vs Telegram）
• 原文没有但用户一定会问的问题

铁律 3：代码原样，注释翻译

• 代码一个字都不改
• 注释翻译成中文
• 命令后面的说明文字翻译
• 输出示例保留英文原文（不要”翻译”终端输出）

操作步骤

第 1 步：通读原文，建术语表

先扫一遍，列出：

英文	中文处理	理由
skill	技能（Skill 首次标注）	有官方中文译名
gateway	网关	通用译法
profile	配置档 / 档案	看上下文
plugin	插件	通用译法

同一术语全文必须统一，不能一会儿”技能”一会儿”技巧”。

第 2 步：拆解原文结构

把原文的章节列成大纲，判断：

• 哪些章节可以合并
• 哪些需要拆分（英文一段话，中文要分三点）
• 哪些需要补充（国内环境差异）
• 哪些可以删（对中文读者无用的内容）

第 3 步：逐节重写

每节按这个模板：

## 一、安装（Installation）

> 原文：链接
> 适用版本：v2.0+

【一句话说清这节解决什么问题】

### 前置条件

- 系统要求（补上 Windows 说明）
- 依赖（补上国内镜像源）

### 操作步骤

1. 第一步（命令 + 预期输出）
2. 第二步

### 注意事项

> ⚠️ 国内网络可能卡在下载阶段，先配镜像：
> ```bash
> export PIP_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple
> ```

### 常见问题

**Q：报错 xxx 怎么办？**
A：...

第 4 步：补充国内场景

原文通常假设：

• Linux + 国外网络
• Telegram / Discord / Slack

中文读者实际是：

• Windows 用户占多数
• 需要国内镜像
• 用微信 / 飞书 / 钉钉 / QQ

必须补充：

1. Windows 下的安装差异
2. 国内可用的镜像源
3. 国内平台对接方式
4. 中文编码问题（UTF-8、BOM）

第 5 步：校对

机翻腔识别清单：

机翻腔	改成
“这是被设计用来…”	“它的作用是…”
“你可以去…”	“你可以…”或直接命令
“请注意，…”	删除，直接说事
“在大多数情况下”	“通常”
“为了能够…”	“为了…”
长定语从句	拆成两句

中文排版：

• 中英文之间加空格：使用 Docker 部署
• 数字与单位之间加空格：10 分钟
• 全角标点：，。！？
• 不要中英文标点混用

输出格式

# 中文标题（含关键词）

> 译自：<原文链接>
> 适用版本：v2.x
> 更新日期：2026-XX-XX

## 一、...
## 二、...
## 常见问题
## 参考

常见坑

1. 逐句直译 → 中文读起来像外星文，必须重组
2. 术语前后不一致 → 一会儿”网关”一会儿”gateway”，读者懵
3. 翻译终端输出 → 命令输出必须保留原文，否则对不上
4. 删掉原文链接 → 必须保留，方便读者核对
5. 不标版本 → 官方迭代快，半年后内容就过时了
6. 忽略 Windows → 国内一半用户是 Windows，不写等于没写

验证方法

翻译完成后：

• 通读一遍，没有”的的不休”的长句
• 术语全文统一（搜索关键词确认）
• 所有命令都能直接复制执行
• 补了国内网络/Windows 说明
• 标注了原文链接和适用版本
• 中英文之间有空格