Apache SkyWalking中文文档贡献指南：从术语规范到本地化实践
项目地址: https://gitcode.com/gh_mirrors/sky/skywalking 你是否在翻译开源文档时遇到过术语不统一、菜单层级混乱的问题？本文将系统讲解Apache SkyWalking中文文档的翻译规范，通过术语表管理、菜单本地化流程和实战案例，帮助你快速上手文档贡献，让全球20万+开发者用上地道的中文文档。读完本文你将掌握：术语翻译的"三原则"、i18n配置文件的修改技巧、以及如何通过菜单结构优化提升用户体验。
术语表管理：翻译的基石
核心术语规范
Apache SkyWalking作为分布式追踪系统（Distributed Tracing System），拥有大量专业术语。所有术语翻译需遵循"准确性、一致性、可读性"三大原则，首现术语必须中英文对照标注。例如：
- Agent（探针）：用于收集应用性能数据的组件，对应代码实现可见oap-server/server-core/
- OAL（Observability Analysis Language，可观测性分析语言）：SkyWalking自定义的指标分析语言，语法定义在oap-server/oal-grammar/
术语冲突处理
当遇到多义词时，需结合上下文选择合适译法。典型案例：
| 英文术语 | 常见译法 | 推荐译法（SkyWalking语境） | 应用场景 |
|---|---|---|---|
| Service | 服务/业务 | 服务 | 指代微服务架构中的独立部署单元 |
| Endpoint | 端点/终点 | 端点 | 表示服务中的具体API接口 |
| Probe | 探针/探测器 | 探针 | 特指数据采集组件，见concepts-and-designs/probe-introduction.md |
翻译流程与文件结构
文档组织架构
SkyWalking文档采用国际化标准目录结构，中文翻译文件应遵循以下路径规则：
docs/
├── en/ # 英文原版文档
├── zh/ # 中文翻译文档（需新建）
└── menu.yml # 文档导航配置
核心翻译对象包括：
- 概念文档：docs/en/concepts-and-designs/
- 安装指南：docs/en/setup/
- API文档：docs/en/api/
菜单本地化实践
文档导航菜单通过docs/menu.yml定义，中文本地化需注意保持层级结构一致。以"Concepts and Designs"为例：
# 英文原版
- name: "Concepts and Designs"
catalog:
- name: "Overview and Core concepts"
path: "/en/concepts-and-designs/overview"
# 中文翻译版（建议）
- name: "概念与设计"
catalog:
- name: "概述与核心概念"
path: "/zh/concepts-and-designs/overview"
i18n配置与前端展示
翻译文件格式
UI界面的国际化文本存储在JSON格式的语言文件中，典型结构如下：
{
"general_service": "通用服务",
"general_service_desc": "通过SkyWalking Agent采集的遥测数据观察服务及其直接依赖"
}
上述键值对对应docs/en/guides/i18n.md中定义的翻译规则，其中general_service为i18nKey，_desc后缀表示描述文本。
本地化效果预览
完成翻译后，可通过Docker快速启动本地化环境验证效果：
docker-compose -f docker/docker-compose.yml up -d
访问UI后在设置中切换至中文，检查以下关键区域：
- 主导航菜单：对应docs/menu.yml的name字段
- 仪表盘标题：对应locales文件中的指标名称翻译
- 帮助文本：对应各文档页面的description字段
图1：文档中引用本地图片的正确方式，文件路径docs/en/FAQ/MQ-involved-architecture.png
贡献规范与质量保障
提交指南
- Fork仓库：
git clone https://gitcode.com/gh_mirrors/sky/skywalking - 创建分支：
git checkout -b i18n-zh-translation - 提交格式：
[I18N] Translate concepts-and-designs/overview.md to Chinese
评审标准
中文文档PR需通过以下检查：
社区协作
遇到翻译难题时，可通过以下渠道寻求帮助：
- 开发指南：CONTRIBUTING.md
- 社区论坛：Apache SkyWalking官方邮件列表
- 即时沟通：加入Slack工作区 #skywalking-dev 频道
常见问题与解决方案
图片资源处理
文档中的图片应优先使用项目内文件，避免外部链接。建议在中文文档目录下维护独立图片文件夹：
docs/zh/
├── concepts-and-designs/
│ ├── overview.md
│ └── images/
│ └── architecture-zh.png # 中文标注版图片
版本同步策略
保持中文文档与英文原版同步的高效方法：
- 定期关注变更日志
- 使用
git diff对比英文文档更新 - 在翻译文件头部添加版本信息：
<!-- 翻译基于英文版 9.7.0 -->
通过本文档介绍的方法，你可以系统地参与Apache SkyWalking中文文档建设。无论是术语翻译、菜单配置还是i18n适配，每一处改进都将直接提升全球中文用户的使用体验。立即 fork 项目，开始你的第一次文档贡献吧！
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
