# 编写要翻译的内容

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

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

遵循以下准则，可确保你创建的内容能被成功翻译。 有关详细信息，请参阅[风格指南](/zh/enterprise-server@3.22/contributing/style-guide-and-content-model/style-guide)。

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

## 示例

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

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

例如，避免使用 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 文件）”。

### 避免采用名词化结构

例如，使用“总结”而不是“得出结论”。

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

避免使用诸如“可能”和“也许”等词。 请编写较为清晰的内容，以避免歧义。

### 避免使用介词短语

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

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

模糊的名词和代词可能会混淆你所指代的对象，特别是在要翻译此内容时。 例如，“维护者和贡献者可以访问文件和评论。” 在拉取请求中，他们对其进行了更改。 在此句子中，我们不清楚他们更改的是文件还是注释。 如果某个代词可能指代多个先行词，请改写句子以明确其指代的先行词，或用名词替换代词以消除歧义。

### 尽可能减少内联链接。

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

```markdown
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.
```

你可以改写为：

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