# 贡献指南

欢迎参与《Agentic Design Patterns》中文翻译项目！本指南将帮助您了解如何为项目做出贡献。

## 🎯 项目概览

本项目是《Agentic Design Patterns》一书的中文翻译，涵盖21个核心AI Agent设计模式及7个附录章节。所有翻译内容将通过GitHub Pages在线发布。

**在线访问**: [https://adp.xindoo.xyz/](https://adp.xindoo.xyz/)

## 📋 翻译标准

### 准确性原则
- **技术准确性**: 确保技术概念和术语的准确传达
- **语义完整性**: 不遗漏重要信息，保持原文的技术深度
- **文化适应性**: 适当本土化文化差异内容，保持技术准确性

### 语言风格
- **自然流畅**: 使用符合中文表达习惯的句式
- **专业严谨**: 保持技术文档的专业性和严谨性
- **统一风格**: 全书保持一致的翻译风格和语气

## 🔤 术语规范

### 术语统一
- **参考术语表**: 所有术语必须参考 [`glossary.md`](glossary.md) 中的统一译法
- **首次出现**: 新术语首次出现时可标注英文原文，格式：`中文译名(英文原文)`
- **一致性检查**: 提交前使用搜索功能检查术语使用的一致性

### 常见术语处理
- **代码相关**: 变量名、函数名、类名保持英文原样
- **框架名称**: LangChain、Google ADK等框架名称保持英文
- **技术概念**: Agent、Prompt、RAG等技术概念使用统一译法

## 📝 格式要求

### Markdown格式
- **标题层级**: 保持与原文一致的标题层级结构（# H1, ## H2, ### H3）
- **代码块**: 使用正确的语言标识符，保持代码格式完整
- **列表**: 有序列表和无序列表保持原有缩进结构
- **表格**: 确保表格对齐，表头使用中文

### 代码处理
```markdown
```python
# 代码注释可以翻译为中文
def example_function():
    # 函数和变量名保持英文
    return "结果"
```
```

### 图片引用
- **路径格式**: `![图片描述](../images/chapter-XX/image-name.png)`
- **图片描述**: 使用准确的中文描述
- **图片处理**: 如原图包含英文文字，需创建中文版本图片

## 🔄 工作流程

### 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
```

### 格式验证
```bash
# 验证Markdown格式
npx markdownlint-cli chapters/
```

### 链接检查
```bash
# 检查内部链接有效性
npx markdown-link-check chapters/your-chapter.md
```

## 📚 学习资源

- [翻译指南](translation-guide.md) - 详细的翻译规范和技巧
- [术语表](glossary.md) - 统一的技术术语翻译
- [项目结构](PROJECT_STRUCTURE.md) - 项目文件组织说明
- [进度追踪](progress.md) - 实时翻译状态更新

## 🤝 社区准则

### 沟通方式
- **问题讨论**: 使用GitHub Issues进行技术讨论
- **代码审查**: 在Pull Request中进行代码审查和讨论
- **紧急联系**: 通过邮件联系维护者

### 行为准则
- **尊重他人**: 保持专业和尊重的沟通态度
- **建设性反馈**: 提供具体、建设性的反馈意见
- **共同学习**: 这是一个共同学习进步的过程

### 认可贡献
所有贡献者将在项目README中列出，重大贡献将在发布说明中特别致谢。

## 🆘 获取帮助

如果您在翻译过程中遇到困难，可以通过以下方式获取帮助：

1. **查阅文档**: 首先查看相关指南文档
2. **搜索问题**: 在Issues中搜索类似问题
3. **创建Issue**: 描述具体问题和技术难点
4. **联系维护者**: 
   - 邮箱: ixindoo@gmail.com
   - GitHub: [xindoo](https://github.com/xindoo)

## 📄 许可证说明

本翻译项目遵循原书的许可证条款。翻译内容仅供学习交流使用，请勿用于商业用途。

---

感谢您为开源社区做出的贡献！您的每一份努力都让中文技术文档更加丰富和完善。