Skip to content

TRANSLATION-PLAN.md

Latest commit

 

History

History
508 lines (401 loc) · 19 KB

TRANSLATION-PLAN.md

File metadata and controls

508 lines (401 loc) · 19 KB
Raw

Synkra AIOX 中文文档翻译计划

🌐 EN | PT | ES | ZH

概述

本文档描述了将 Synkra AIOX 文档翻译成中文的完整计划。

翻译范围统计

指标 数值
总文档数量 ~980 个文件
文档行数 ~473,000 行
总大小 ~13.4 MB
优先翻译文档 ~150 个文件
预计总词数 ~500,000 字

阶段规划

第一阶段：核心文档 (Tier 1 - Critical)

目标： 让中文用户能够安装和开始使用 AIOX

预计文件数： 25 个文件 优先级： 最高

文档 原文路径 译文路径 状态
快速入门 getting-started.md zh/getting-started.md ⬜
安装指南 - macOS installation/macos.md zh/installation/macos.md ⬜
安装指南 - Linux installation/linux.md zh/installation/linux.md ⬜
安装指南 - Windows installation/windows.md zh/installation/windows.md ⬜
安装故障排除 installation/troubleshooting.md zh/installation/troubleshooting.md ⬜
常见问题 installation/faq.md zh/installation/faq.md ⬜
核心架构 core-architecture.md zh/core-architecture.md ⬜
元代理命令 meta-agent-commands.md zh/meta-agent-commands.md ⬜
代理参考指南 agent-reference-guide.md zh/agent-reference-guide.md ⬜
README README.md zh/README.md ⬜
环境配置 ENVIRONMENT.md zh/ENVIRONMENT.md ⬜
指导原则 GUIDING-PRINCIPLES.md zh/GUIDING-PRINCIPLES.md ⬜

框架文档：

文档 原文路径 译文路径 状态
框架 README framework/README.md zh/framework/README.md ⬜
编码标准 framework/coding-standards.md zh/framework/coding-standards.md ⬜
技术栈 framework/tech-stack.md zh/framework/tech-stack.md ⬜
源码树 framework/source-tree.md zh/framework/source-tree.md ⬜

指南文档：

文档 原文路径 译文路径 状态
指南 README guides/README.md zh/guides/README.md ⬜
API 参考 guides/api-reference.md zh/guides/api-reference.md ⬜
开发环境设置 guides/development-setup.md zh/guides/development-setup.md ⬜
质量门控 guides/quality-gates.md zh/guides/quality-gates.md ⬜
工作流指南 guides/workflows-guide.md zh/guides/workflows-guide.md ⬜

第二阶段：代理系统 (Tier 2 - Important)

目标： 完整理解代理系统和工作流

预计文件数： 35 个文件 优先级： 高

代理流程文档 (aiox-agent-flows/)：

文档 原文路径 译文路径 状态
代理流程 README aiox-agent-flows/README.md zh/aiox-agent-flows/README.md ⬜
AIOX Master 系统 aiox-agent-flows/aiox-master-system.md zh/aiox-agent-flows/aiox-master-system.md ⬜
开发者系统 aiox-agent-flows/dev-system.md zh/aiox-agent-flows/dev-system.md ⬜
架构师系统 aiox-agent-flows/architect-system.md zh/aiox-agent-flows/architect-system.md ⬜
QA 系统 aiox-agent-flows/qa-system.md zh/aiox-agent-flows/qa-system.md ⬜
UX 设计专家系统 aiox-agent-flows/ux-design-expert-system.md zh/aiox-agent-flows/ux-design-expert-system.md ⬜
数据工程师系统 aiox-agent-flows/data-engineer-system.md zh/aiox-agent-flows/data-engineer-system.md ⬜
分析师系统 aiox-agent-flows/analyst-system.md zh/aiox-agent-flows/analyst-system.md ⬜
产品经理系统 aiox-agent-flows/pm-system.md zh/aiox-agent-flows/pm-system.md ⬜
Scrum Master 系统 aiox-agent-flows/sm-system.md zh/aiox-agent-flows/sm-system.md ⬜
DevOps 系统 aiox-agent-flows/devops-system.md zh/aiox-agent-flows/devops-system.md ⬜
Squad 创建者系统 aiox-agent-flows/squad-creator-system.md zh/aiox-agent-flows/squad-creator-system.md ⬜

工作流文档 (aiox-workflows/)：

文档 原文路径 译文路径 状态
工作流 README aiox-workflows/README.md zh/aiox-workflows/README.md ⬜
绿地全栈工作流 aiox-workflows/greenfield-fullstack-workflow.md zh/aiox-workflows/greenfield-fullstack-workflow.md ⬜
绿地服务工作流 aiox-workflows/greenfield-service-workflow.md zh/aiox-workflows/greenfield-service-workflow.md ⬜
绿地 UI 工作流 aiox-workflows/greenfield-ui-workflow.md zh/aiox-workflows/greenfield-ui-workflow.md ⬜
棕地全栈工作流 aiox-workflows/brownfield-fullstack-workflow.md zh/aiox-workflows/brownfield-fullstack-workflow.md ⬜
棕地服务工作流 aiox-workflows/brownfield-service-workflow.md zh/aiox-workflows/brownfield-service-workflow.md ⬜
棕地 UI 工作流 aiox-workflows/brownfield-ui-workflow.md zh/aiox-workflows/brownfield-ui-workflow.md ⬜
棕地发现工作流 aiox-workflows/brownfield-discovery-workflow.md zh/aiox-workflows/brownfield-discovery-workflow.md ⬜
规格流水线工作流 aiox-workflows/spec-pipeline-workflow.md zh/aiox-workflows/spec-pipeline-workflow.md ⬜
QA 循环工作流 aiox-workflows/qa-loop-workflow.md zh/aiox-workflows/qa-loop-workflow.md ⬜
Story 开发周期 aiox-workflows/story-development-cycle-workflow.md zh/aiox-workflows/story-development-cycle-workflow.md ⬜

代理定义：

文档 原文路径 译文路径 状态
角色定义 agents/persona-definitions.md zh/agents/persona-definitions.md ⬜
原型原理 agents/archetype-rationale.md zh/agents/archetype-rationale.md ⬜

第三阶段：架构文档 (Tier 2 - Important)

目标： 深入理解系统架构

预计文件数： 20 个文件 优先级： 高

文档 原文路径 译文路径 状态
架构索引 architecture/ARCHITECTURE-INDEX.md zh/architecture/ARCHITECTURE-INDEX.md ⬜
架构简介 architecture/introduction.md zh/architecture/introduction.md ⬜
高级架构 architecture/high-level-architecture.md zh/architecture/high-level-architecture.md ⬜
AIOX 视觉概览 architecture/AIOX-VISUAL-OVERVIEW.md zh/architecture/AIOX-VISUAL-OVERVIEW.md ⬜
模块系统 architecture/module-system.md zh/architecture/module-system.md ⬜
源码树 architecture/source-tree.md zh/architecture/source-tree.md ⬜
命令权限矩阵 architecture/command-authority-matrix.md zh/architecture/command-authority-matrix.md ⬜
代理责任矩阵 architecture/agent-responsibility-matrix.md zh/architecture/agent-responsibility-matrix.md ⬜
代理工具集成指南 architecture/agent-tool-integration-guide.md zh/architecture/agent-tool-integration-guide.md ⬜
编码标准 architecture/coding-standards.md zh/architecture/coding-standards.md ⬜
技术栈 architecture/tech-stack.md zh/architecture/tech-stack.md ⬜
CI/CD architecture/ci-cd.md zh/architecture/ci-cd.md ⬜
MCP 系统图 architecture/mcp-system-diagrams.md zh/architecture/mcp-system-diagrams.md ⬜
MCP API 密钥管理 architecture/mcp-api-keys-management.md zh/architecture/mcp-api-keys-management.md ⬜

第四阶段：高级指南 (Tier 3 - Standard)

目标： 完善文档覆盖

预计文件数： 50+ 个文件 优先级： 中

安全相关：

文档 原文路径 译文路径 状态
安全最佳实践 security-best-practices.md zh/security-best-practices.md ⬜
安全强化 guides/security-hardening.md zh/guides/security-hardening.md ⬜
安全文档 security.md zh/security.md ⬜

MCP 相关：

文档 原文路径 译文路径 状态
MCP 全局设置 guides/mcp-global-setup.md zh/guides/mcp-global-setup.md ⬜
Docker Gateway 教程 guides/mcp/docker-gateway-tutorial.md zh/guides/mcp/docker-gateway-tutorial.md ⬜
Desktop Commander guides/mcp/desktop-commander.md zh/guides/mcp/desktop-commander.md ⬜

Squad 相关：

文档 原文路径 译文路径 状态
Squad API api/squads-api.md zh/api/squads-api.md ⬜
Squad 示例 guides/squad-examples/README.md zh/guides/squad-examples/README.md ⬜
Squad 迁移 guides/squad-migration.md zh/guides/squad-migration.md ⬜
Squad 贡献 guides/contributing-squads.md zh/guides/contributing-squads.md ⬜

其他指南：

文档 原文路径 译文路径 状态
性能调优 performance-tuning-guide.md zh/performance-tuning-guide.md ⬜
Git 工作流 git-workflow-guide.md zh/git-workflow-guide.md ⬜
版本发布 versioning-and-releases.md zh/versioning-and-releases.md ⬜
权限模式 guides/permission-modes.md zh/guides/permission-modes.md ⬜
代理选择指南 guides/agent-selection-guide.md zh/guides/agent-selection-guide.md ⬜
模板引擎 v2 guides/template-engine-v2.md zh/guides/template-engine-v2.md ⬜
质量仪表板 guides/quality-dashboard.md zh/guides/quality-dashboard.md ⬜

第五阶段：示例和社区 (Tier 4 - Extended)

目标： 完整示例和社区文档

预计文件数： 30+ 个文件 优先级： 低

示例：

文档 原文路径 译文路径 状态
基础 Squad examples/squads/basic-squad/ zh/examples/squads/basic-squad/ ⬜
多代理 Squad examples/squads/multi-agent-squad/ zh/examples/squads/multi-agent-squad/ ⬜
带工具 Squad examples/squads/squad-with-tools/ zh/examples/squads/squad-with-tools/ ⬜

社区：

文档 原文路径 译文路径 状态
社区文档 community.md zh/community.md ⬜
贡献指南 contributing.md zh/contributing.md ⬜
行为准则 code-of-conduct.md zh/code-of-conduct.md ⬜
PR 指南 how-to-contribute-with-pull-requests.md zh/how-to-contribute-with-pull-requests.md ⬜

翻译标准

术语表

英文 简体中文 繁体中文 备注
Agent 代理 代理 核心概念
Workflow 工作流 工作流程
Story 故事 / Story 故事 / Story 保留英文亦可
Task 任务 任務
Epic 史诗 / Epic Epic 保留英文更常见
Squad 小队 / Squad 小隊 / Squad
Greenfield 绿地项目 全新專案 新项目
Brownfield 棕地项目 既有專案 现有项目
Meta-Agent 元代理 元代理
Memory Layer 记忆层 記憶層
Self-Modifying 自修改 自修改
Orchestration 编排 編排
Pipeline 流水线 管線
Gate 门控 門控 质量门控
Persona 角色 / 人格 角色 / 人格
Constitution 宪法 / 准则 憲法 / 準則 AIOX Constitution
CLI CLI / 命令行 CLI / 命令列
Hook 钩子 鉤子
MCP MCP MCP 不翻译
SYNAPSE SYNAPSE SYNAPSE 不翻译

翻译原则

  1. 保持技术准确性 - 技术术语优先使用行业标准翻译
  2. 代码不翻译 - 代码块、变量名、命令保持英文
  3. 保留品牌名 - Synkra、AIOX、Claude 等品牌名不翻译
  4. 链接更新 - 更新文档内部链接指向中文版本
  5. 同步标记 - 每个文件标注原文版本和同步日期

文件头模板

<!--
  翻译：zh-CN（简体中文）
  原文：/docs/en/{path}
  最后同步：YYYY-MM-DD
  翻译者：{name}
  审核者：{name}
-->

# 文档标题

> 🌐 [EN](../{path}) | [PT](../pt/{path}) | [ES](../es/{path}) | **ZH**

---

目录结构

docs/zh/
├── README.md                           # 中文文档首页
├── TRANSLATION-PLAN.md                 # 本计划文件
├── GLOSSARY.md                         # 术语表
├── getting-started.md                  # 快速入门
├── core-architecture.md                # 核心架构
├── meta-agent-commands.md              # 元代理命令
├── agent-reference-guide.md            # 代理参考指南
├── ENVIRONMENT.md                      # 环境配置
├── GUIDING-PRINCIPLES.md               # 指导原则
├── security-best-practices.md          # 安全最佳实践
├── performance-tuning-guide.md         # 性能调优指南
├── git-workflow-guide.md               # Git 工作流指南
├── versioning-and-releases.md          # 版本发布
│
├── installation/                       # 安装文档
│   ├── README.md
│   ├── macos.md
│   ├── linux.md
│   ├── windows.md
│   ├── faq.md
│   └── troubleshooting.md
│
├── framework/                          # 框架文档
│   ├── README.md
│   ├── coding-standards.md
│   ├── tech-stack.md
│   └── source-tree.md
│
├── guides/                             # 指南
│   ├── README.md
│   ├── api-reference.md
│   ├── development-setup.md
│   ├── quality-gates.md
│   ├── workflows-guide.md
│   ├── permission-modes.md
│   ├── agent-selection-guide.md
│   ├── security-hardening.md
│   ├── mcp/
│   │   ├── docker-gateway-tutorial.md
│   │   └── desktop-commander.md
│   └── squad-examples/
│       └── README.md
│
├── aiox-agent-flows/                   # 代理流程
│   ├── README.md
│   ├── aiox-master-system.md
│   ├── dev-system.md
│   ├── architect-system.md
│   ├── qa-system.md
│   ├── ux-design-expert-system.md
│   ├── data-engineer-system.md
│   ├── analyst-system.md
│   ├── pm-system.md
│   ├── sm-system.md
│   ├── devops-system.md
│   └── squad-creator-system.md
│
├── aiox-workflows/                     # 工作流
│   ├── README.md
│   ├── greenfield-fullstack-workflow.md
│   ├── greenfield-service-workflow.md
│   ├── greenfield-ui-workflow.md
│   ├── brownfield-fullstack-workflow.md
│   ├── brownfield-service-workflow.md
│   ├── brownfield-ui-workflow.md
│   ├── brownfield-discovery-workflow.md
│   ├── spec-pipeline-workflow.md
│   ├── qa-loop-workflow.md
│   └── story-development-cycle-workflow.md
│
├── architecture/                       # 架构文档
│   ├── ARCHITECTURE-INDEX.md
│   ├── introduction.md
│   ├── high-level-architecture.md
│   ├── AIOX-VISUAL-OVERVIEW.md
│   ├── module-system.md
│   ├── source-tree.md
│   ├── command-authority-matrix.md
│   ├── agent-responsibility-matrix.md
│   ├── agent-tool-integration-guide.md
│   ├── coding-standards.md
│   ├── tech-stack.md
│   ├── ci-cd.md
│   ├── mcp-system-diagrams.md
│   └── mcp-api-keys-management.md
│
├── agents/                             # 代理定义
│   ├── persona-definitions.md
│   └── archetype-rationale.md
│
├── api/                                # API 文档
│   └── squads-api.md
│
├── examples/                           # 示例
│   └── squads/
│       ├── basic-squad/
│       ├── multi-agent-squad/
│       └── squad-with-tools/
│
├── community/                          # 社区
│   └── README.md
│
├── security/                           # 安全
│   └── README.md
│
└── troubleshooting.md                  # 故障排除

执行计划

阶段 1：基础设施 (第1周)

  • 创建 docs/zh/ 目录结构
  • 创建 GLOSSARY.md 术语表
  • 创建 README.md 中文首页
  • 设置翻译工作流脚本

阶段 2：核心文档 (第2-3周)

  • 翻译安装文档 (6个文件)
  • 翻译快速入门
  • 翻译核心架构
  • 翻译框架文档 (4个文件)
  • 翻译基础指南 (5个文件)

阶段 3：代理系统 (第4-5周)

  • 翻译代理流程 (12个文件)
  • 翻译工作流 (11个文件)
  • 翻译代理定义 (2个文件)

阶段 4：架构文档 (第6周)

  • 翻译架构索引
  • 翻译核心架构文档 (14个文件)

阶段 5：高级指南 (第7-8周)

  • 翻译安全文档 (3个文件)
  • 翻译 MCP 文档 (3个文件)
  • 翻译 Squad 文档 (4个文件)
  • 翻译其他指南 (10+个文件)

阶段 6：示例和社区 (第9-10周)

  • 翻译示例文档 (3个目录)
  • 翻译社区文档 (4个文件)
  • 最终审核和校对

质量保证

翻译审核流程

初译 → 技术审核 → 语言审核 → 合并
  1. 初译 - 完成初步翻译
  2. 技术审核 - 确保技术准确性
  3. 语言审核 - 确保语言流畅性
  4. 合并 - PR 审核后合并

自动化检查

  • 链接检查 - 确保内部链接有效
  • 格式检查 - 确保 Markdown 格式正确
  • 术语一致性检查 - 确保术语使用一致
  • 代码块检查 - 确保代码块未被翻译

维护计划

同步策略

  1. 版本标记 - 每个文件记录原文版本
  2. 变更监控 - 监控英文文档变更
  3. 定期同步 - 每月检查并同步更新
  4. 自动提醒 - 当原文更新时创建 Issue

文档版本对照

文档 英文版本 中文版本 同步状态
getting-started.md v4.2.13 - ⬜ 待翻译
... ... ... ...

贡献指南

如何参与翻译

  1. Fork 仓库
  2. 选择一个待翻译文档
  3. 创建分支 zh/translate-{filename}
  4. 按照翻译标准完成翻译
  5. 提交 PR

PR 模板

## 翻译内容

- 文件：`docs/zh/{path}`
- 原文：`docs/{path}`
- 类型：[ ] 新翻译 / [ ] 更新同步

## 检查清单

- [ ] 遵循术语表
- [ ] 添加文件头标记
- [ ] 更新内部链接
- [ ] 代码块保持英文
- [ ] 通过格式检查

联系方式

如有翻译相关问题，请：

  1. 在 GitHub 创建 Issue，标签 translation/zh
  2. 参与 Discord 的 #translation-zh 频道
  3. 邮件联系翻译协调员

Synkra AIOX 中文文档翻译计划 v1.0 创建日期：2026-02-22