文档翻译

一般情况下,DevStream 文档使用英文来写,然后翻译成其他语言,目前主要是中文。本文将介绍文档翻译工作的一些规则以及注意事项。

规则

我们以英文文档为主,所以新增文档的时候尽可能先写英文,然后再通过翻译的方式补充中文版本,避免出现部分文档有英文没中文,部分文档有中文没英文的混乱局面。

文档翻译以意译为主,句子表达要求符合中国人的说话习惯,看起来通顺自然。翻译过程中如果发现相应英文文档不够详细,也必须保留不详细的内容,不要在翻译的过程中创作。 换言之,所有的不详细、错误等如果希望更正,都应该先保证先改英文版,再更新中文版,避免出现英文版落后的情况。

如果你希望补充一个中文文档,并且不想写对应的英文版本,请先开一个 issue 来记录你的想法,如果合理,社区会寻找一位擅长英文的贡献者来帮助你在中文文档完成的同时补充相应的英文版本文档,确保英文版本文档永远是最新最全面的; 如果你想翻译某一篇英文文档,也请先开一个 issue,等得管理员确认并回复后再开始翻译工作;

注意事项

  1. 所有英文标点需要转换成对应的中文标点,比如“,、.、;、:”等对应需要改成“,、。、;、:”;
  2. 专有名词如果翻译之后更难理解,则不翻译,比如 Pod 不要翻译成“豆荚”或者“容器组”;DevOps 不要翻译成“开发运维”;k8s 里的 Service、Deployment 等都不需要翻译;
  3. 中文文档以第二人称为主,部分场景也可以使用“我们”,不需要敬语。比如“you”翻译成“你”而不是“您”;
  4. 中文句子中带英文单词时,单词左右的空格可有可无,但是要全文统一,不能有的地方加空格,有的地方不加空格。比如本文出现的英文单词左右一律都加了空格;
  5. 不要引入多余的空格或空行,也不要丢失必要的空行,比如标题和正文之间需要有且只有1个空行。

上述注意事项只是初版,如果你有更多的建议,欢迎提交一个 Pull Request 来一起进一步完善。