Skip to main content

编写要翻译的内容

我们的文档已翻译成多种语言。 我们编写英语文档的方式可以大大提高这些翻译的质量。

“参与 GitHub Docs”部分中的文章指的是文档本身,是 GitHub 员工和开放源代码参与者的资源。

关于如何编写易于翻译的内容

遵循以下准则,可确保你创建的内容能被成功翻译。 有关详细信息,请参阅“风格指南”。

  • 使用比较宽泛且能被大多数理解的示例。
  • 避免使用具有争议性或在文化上特定于某类人群的示例。
  • 采用主动语态编写内容。
  • 编写简单、简短且易于理解的句子。
  • 避免使用过多的代词,这些代词会混淆文本内容。
  • 避免使用俚语和笑话。
  • 避免使用否定句。
  • 尽可能使用行业标准的首字母缩略词,并对自定义的首字母缩略词进行解释。
  • 使用指示性的语气。
  • 避免赘述。
  • 避免堆砌辞藻(一串名词)。 翻译工具可能会分不清被修饰的是哪个名词。
  • 避免使用不明确的复数形式,这样会在第一个名词是单数还是复数上存在混淆。
  • 避免采用名词化结构。
  • 避免使用模糊的情态助动词。
  • 避免使用特定于性别的字词。
  • 避免使用介词短语。
  • 避免模糊的名词和代词(模糊的句子主语)。
  • 尽可能减少内联链接。 如果是必要的链接,请在它们前面加上一个短语,例如“有关详细信息,请参阅‘链接标题’”。 或者将相关链接添加到主题末尾的“延伸阅读”部分。

示例

本部分提供一些示例,帮助你了解如何遵循这些准则,以编写易于翻译的文档。

避免使用特定于国家/地区的信息

例如,避免使用 800 号码和国家/地区特定的地址。 如果无法避免,请说明信息适用的国家/地区。

避免堆砌辞藻(一串名词)

大量堆砌辞藻可能会导致翻译错误,因为很难判断字词间的修饰关系。 例如,请采用“Default source settings for the public repository(公共存储库的默认源设置)”而不是“public repository default source settings(公共存储库默认源设置)”。

避免使用不明确的复数形式

例如,在采用“file retrieval(文件检索)”一词时,很难判断检索的是一个文件还是所有文件。 提供更多上下文以消除歧义。 在上面给出的示例中,可以使用“retrieving all the files(检索所有文件)”或“retrieving the source.md file(检索 source.md 文件)”。

避免采用名词化结构

例如,请采用“conclude(总结)”,而不是“to reach a conclusion(得出结论)”。

避免使用模糊的情态助动词。

避免使用“may”和“may”等词。 请编写较为清晰的内容,以避免歧义。

避免使用介词短语

与其写“after trying many times(多次尝试后)”或“according to the repository log(根据存储库日志)”,不如采用更直接的方式编写内容。 例如“after trying three times(尝试三次后)”。

避免使用模糊的名词和代词

模糊的名词和代词可能会混淆你所指代的对象,特别是在要翻译此内容时。 例如“Maintainers and contributors have access to files and comments. In the pull request they make changes to it.(维护人员和参与者有权访问文件和注释。他们在拉取请求中对其进行了更改。)” 在此句子中,我们不清楚他们更改的是文件还是注释。 如果某一代词可能指代的前述词不止一个,请改写句子以明确它所指代的前述词,或者用名词替换代词来消除歧义。

请尽可能地按照我们的风格指南清晰地介绍链接。 下面的句子是一个反面教材:

Read [more about OAuth2.](/apps/building-integrations/setting-up-and-registering-oauth-apps/) Note that OAuth2 tokens can be [acquired programmatically](/rest/reference/oauth-authorizations/#create-a-new-authorization), for applications that are not websites.

你可以改写为:

OAuth2 tokens can be acquired programmatically for applications that are not websites. For more information, see "[Setting up and registering OAuth Apps](apps/building-integrations/setting-up-and-registering-oauth-apps/)" and "[Create a new authorization](/rest/reference/oauth-authorizations/#create-a-new-authorization)."