translate-prd

PRD 中译英 流程

将中文 PRD 翻译为英文，源文件是什么格式，输出就是什么格式，保持格式和排版不变，另存为同名带 _en 的文件，然后对比中文版本检查翻译错误、原文忠实度和幻觉，修复后 push to main。

参数

$ARGUMENTS 可指定源文件路径（相对或绝对）。若为空，自动搜索项目中的 PRD 文件：

1. docs/ 目录下的 PRD* 文件
2. 项目根目录的 PRD* 文件
3. 任何 **/PRD* 文件

若找到多个候选，询问用户选择。

Step 1: 定位源文件并检测格式

1. 若 $ARGUMENTS 指定了文件路径，直接使用
2. 否则按优先级搜索：
   • docs/PRD*
   • PRD*（项目根目录）
   • **/PRD*
3. 检测格式：根据文件扩展名判断（.md = Markdown，.html/.htm = HTML，.rst = reStructuredText，.adoc = AsciiDoc，无扩展名则看内容）
4. 确定输出文件：源文件同目录，文件名加 _en 后缀，保持原扩展名（如 PRD.md → PRD_en.md，PRD.html → PRD_en.html，PRD → PRD_en）
5. 展示源文件路径、检测到的格式、输出文件路径，让用户确认

若文件不存在： 提示用户指定正确的 PRD 文件路径。

Step 2: 翻译

读取源文件全文，保持源格式不变，只翻译文本内容。

核心原则：格式原样保留

无论源文件是什么格式，翻译时只替换文本内容，格式结构完全不动：

• Markdown：标题 #、列表 -/1.、代码块 ```、表格 |、引用 >、分隔线 --- 等原样保留
• HTML：所有标签 <div>、属性 class="..."、style="..." 原样保留，只翻译标签间的可见文本
• reStructuredText：指令 .. directive::、角色 :role:`text` 、引用 ____ 等原样保留
• AsciiDoc：标题 =、块 ----、角色 &text& 等原样保留
• 纯文本：保持原有的空行、缩进、对齐方式

格式内不可翻译内容

• 代码块（任何格式）：代码保持原样
• 内联代码：反引号、等宽字体中的内容不翻译
• 链接 URL、图片路径、文件路径：保持原样
• HTML/CSS/JS：<script>、<style> 标签内容、CSS 属性值不翻译
• 属性值：class、id、href、src、style 等属性值不翻译
• meta 标签：<meta name="description"> 等 SEO 内容翻译为英文

通用翻译原则

• 专有名词保留：产品名（如 "i-Write"）、技术术语（如 "RAG"、"LLM"、"IndexedDB"）、API 名称等不翻译
• 中文标注保留：括号中的中文说明可保留为 (Chinese explanation) 格式，便于对照
• 文件名/路径不翻译：代码和属性中的文件名、目录路径保持原样

翻译质量要求：

• 语句通顺自然，符合英文技术文档风格
• 不遗漏任何段落或要点
• 不添加原文没有的内容

将翻译结果写入输出文件。

Step 3: 逐段对比审查

翻译完成后，逐段对比中英文版本，检查三类问题：

3a. 翻译错误（Translation Errors）

• 误译：关键词含义翻错
• 漏译：遗漏原文段落或要点
• 多译：添加了原文没有的内容
• 语法错误：英文语法不通顺

3b. 原文忠实度（Fidelity）

• 语义偏差：翻译后含义与原文不一致
• 程度变化：原文是"必须"翻译成"建议"等弱化/强化
• 逻辑关系：条件、因果、转折等逻辑关系是否正确传达

3c. 幻觉（Hallucination）

• 无中生有：原文不存在的功能/特性被翻译出来
• 数据捏造：原文的数字、百分比在翻译中被篡改
• 概念混淆：将 A 概念翻译成了 B 概念

审查方法：

1. 将中英文按段落/小节对齐
2. 逐段阅读英文，对照中文检查
3. 记录所有问题，标注位置和类型

Step 4: 修复问题

根据 Step 3 发现的问题，逐个修复英文翻译：

• 误译 → 重新翻译该段，确保语义准确
• 漏译 → 补充遗漏内容
• 多译 → 删除多余内容
• 幻觉 → 修正为原文实际内容
• 语法问题 → 修正英文语法

修复后，重新读取修复位置，确认问题已解决。

修复原则：

• 只修改有问题的部分，不改动已正确的翻译
• 修复时保持上下文连贯
• 修复后重新对比确认

Step 5: 提交并推送

将修改后的文件（源文件 + 翻译文件）提交并推送到 main：

git add <源文件> <翻译文件>
git commit -m "docs: translate <源文件名> to English"
git push origin main

推送后验证 git status 确认成功。

注意事项

• 不修改源文件：中文 PRD 不做任何改动，只读取和对比
• 大文件分段处理：如果 PRD 内容很长（超过 500 行或等效长度），分段翻译和审查，每段完成后确认再继续
• 保留变更历史：如果 _en 文件已存在，对比 git diff 确认翻译变更合理
• 编码保留：保持原始文件的字符编码（UTF-8 等）