贡献指南
欢迎参与《Agentic Design Patterns》中文翻译项目!本指南将帮助您了解如何为项目做出贡献。
🎯 项目概览
本项目是《Agentic Design Patterns》一书的中文翻译,涵盖21个核心AI Agent设计模式及7个附录章节。所有翻译内容将通过GitHub Pages在线发布。
在线访问: https://adp.xindoo.xyz/
📋 翻译标准
准确性原则
- 技术准确性: 确保技术概念和术语的准确传达
- 语义完整性: 不遗漏重要信息,保持原文的技术深度
- 文化适应性: 适当本土化文化差异内容,保持技术准确性
语言风格
- 自然流畅: 使用符合中文表达习惯的句式
- 专业严谨: 保持技术文档的专业性和严谨性
- 统一风格: 全书保持一致的翻译风格和语气
🔤 术语规范
术语统一
- 参考术语表: 所有术语必须参考
glossary.md中的统一译法 - 首次出现: 新术语首次出现时可标注英文原文,格式:
中文译名(英文原文) - 一致性检查: 提交前使用搜索功能检查术语使用的一致性
常见术语处理
- 代码相关: 变量名、函数名、类名保持英文原样
- 框架名称: LangChain、Google ADK等框架名称保持英文
- 技术概念: Agent、Prompt、RAG等技术概念使用统一译法
📝 格式要求
Markdown格式
- 标题层级: 保持与原文一致的标题层级结构(# H1, ## H2, ### H3)
- 代码块: 使用正确的语言标识符,保持代码格式完整
- 列表: 有序列表和无序列表保持原有缩进结构
- 表格: 确保表格对齐,表头使用中文
代码处理
```python
# 代码注释可以翻译为中文
def example_function():
# 函数和变量名保持英文
return "结果"
### 图片引用
- **路径格式**: ``
- **图片描述**: 使用准确的中文描述
- **图片处理**: 如原图包含英文文字,需创建中文版本图片
## 🔄 工作流程
### 1. 准备工作
1. Fork本仓库到您的GitHub账户
2. 克隆仓库到本地:`git clone https://github.com/您的用户名/agentic-design-patterns.git`
3. 创建特性分支:`git checkout -b feature/translate-chapter-XX`
### 2. 认领任务
1. 查看 [`progress.md`](progress.md) 了解可认领的章节
2. 在Issues中创建新issue或评论现有issue表示认领
3. 等待维护者分配任务
### 3. 翻译过程
1. **准备原文**: 从 [`original/`](original/) 目录获取对应章节原文
2. **创建文件**: 在 [`chapters/`](chapters/) 目录创建翻译文件
3. **分段翻译**: 逐段翻译,保持原文结构
4. **处理图片**: 更新图片引用路径,确保指向正确位置
5. **自我检查**: 完成翻译后进行自我质量检查
### 4. 提交审核
1. 提交更改:`git commit -am '完成第XX章翻译'`
2. 推送分支:`git push origin feature/translate-chapter-XX`
3. 创建Pull Request
4. 在PR描述中说明:
- 翻译的章节名称
- 主要翻译内容概述
- 任何需要特别注意的技术难点
### 5. 审核流程
1. **技术审核**: 至少一位技术背景的贡献者审核技术准确性
2. **语言审核**: 至少一位语言背景的贡献者审核语言质量
3. **修改完善**: 根据审核意见修改翻译
4. **合并发布**: 审核通过后合并到主分支
## ✅ 质量检查清单
在提交PR前,请确保完成以下检查:
### 技术准确性
- [ ] 技术概念翻译准确无误
- [ ] 代码示例保持原样,注释翻译正确
- [ ] 专业术语使用统一译法
- [ ] 技术细节无遗漏或误解
### 语言质量
- [ ] 语言流畅自然,符合中文表达习惯
- [ ] 无语法错误和错别字
- [ ] 标点符号使用规范
- [ ] 段落结构清晰合理
### 格式规范
- [ ] Markdown格式正确
- [ ] 标题层级结构完整
- [ ] 图片引用路径正确
- [ ] 代码块格式完整
### 一致性检查
- [ ] 术语使用与术语表一致
- [ ] 风格与已翻译章节保持一致
- [ ] 全章翻译风格统一
## 🛠️ 实用工具推荐
### 术语检查
```bash
# 检查术语一致性
grep -r "术语" chapters/ | head -10
格式验证
# 验证Markdown格式
npx markdownlint-cli chapters/
链接检查
# 检查内部链接有效性
npx markdown-link-check chapters/your-chapter.md
📚 学习资源
🤝 社区准则
沟通方式
- 问题讨论: 使用GitHub Issues进行技术讨论
- 代码审查: 在Pull Request中进行代码审查和讨论
- 紧急联系: 通过邮件联系维护者
行为准则
- 尊重他人: 保持专业和尊重的沟通态度
- 建设性反馈: 提供具体、建设性的反馈意见
- 共同学习: 这是一个共同学习进步的过程
认可贡献
所有贡献者将在项目README中列出,重大贡献将在发布说明中特别致谢。
🆘 获取帮助
如果您在翻译过程中遇到困难,可以通过以下方式获取帮助:
- 查阅文档: 首先查看相关指南文档
- 搜索问题: 在Issues中搜索类似问题
- 创建Issue: 描述具体问题和技术难点
- 联系维护者:
- 邮箱: ixindoo@gmail.com
- GitHub: xindoo
📄 许可证说明
本翻译项目遵循原书的许可证条款。翻译内容仅供学习交流使用,请勿用于商业用途。
感谢您为开源社区做出的贡献!您的每一份努力都让中文技术文档更加丰富和完善。