You are viewing a plain text version of this content. The canonical link for it is here.
Posted to issues@flink.apache.org by GitBox <gi...@apache.org> on 2022/06/11 08:01:15 UTC
[GitHub] [flink-web] Myasuka commented on a diff in pull request #548: [FLINK-27879][flink-web] Translate the Documentation Style Guide page into Chinese
Myasuka commented on code in PR #548:
URL: https://github.com/apache/flink-web/pull/548#discussion_r894990979
##########
contributing/docs-style.zh.md:
##########
@@ -1,131 +1,82 @@
---
-title: "Documentation Style Guide"
+title: "文档样式指南"
---
-This guide provides an overview of the essential style guidelines for writing
-and contributing to the Flink documentation. It's meant to support your
-contribution journey in the greater community effort to improve and extend
-existing documentation — and help make it more **accessible**, **consistent**
-and **inclusive**.
+本指南概述了在编辑以及贡献 Flink 文档中必要的样式原则。目的是在你的贡献之旅中可以投入更好的社区精力去改进和扩展既有文档，并使其更 **易读**、 **一致** 和 **全面**。
{% toc %}
-## Language
+## 语言
-The Flink documentation is maintained in **US English** and **Chinese** — when
-extending or updating the documentation, both versions should be addressed in
-one pull request. If you are not familiar with the Chinese language, make sure
-that your contribution is complemented by these additional steps:
+Flink 同时维护了 **英语** 和 **中文** 两种文档，当你拓展或者更新文档时，需要在 pull request 中包含两种语言版本。如果你不熟悉中文，确保本次贡献补充了如下额外操作：
Review Comment:
```suggestion
Flink 同时维护了 **英文** 和 **中文** 两种文档，当你拓展或者更新文档时，需要在 pull request 中包含两种语言版本。如果你不熟悉中文，确保本次贡献补充了如下额外操作：
```
##########
contributing/docs-style.zh.md:
##########
@@ -151,257 +102,220 @@ under the License.
-->
```
-Below are the front matter variables most commonly used along the Flink
-documentation.
+下面是 Flink 文档前言中常用的变量。
<font size="3">
<table width="100%" class="table table-bordered">
<thead>
<tr>
<th></th>
- <th style="vertical-align : middle;"><center><b>Variable</b></center></th>
- <th style="vertical-align : middle;"><center><b>Possible Values</b></center></th>
- <th style="vertical-align : middle;"><center><b>Description</b></center></th>
+ <th style="vertical-align : middle;"><center><b>变量名</b></center></th>
+ <th style="vertical-align : middle;"><center><b>可能值</b></center></th>
+ <th style="vertical-align : middle;"><center><b>描述</b></center></th>
</tr>
<tr>
- <td><b>Layout</b></td>
+ <td><b>布局</b></td>
<td>layout</td>
<td>{base,plain,redirect}</td>
- <td>The layout file to use. Layout files are located under the <i>_layouts</i> directory.</td>
+ <td>要使用的布局文件。布局文件位于 <i>_layouts</i> 目录下。</td>
</tr>
<tr>
- <td><b>Content</b></td>
+ <td><b>内容</b></td>
<td>title</td>
<td>%s</td>
- <td>The title to be used as the top-level (Level-1) heading for the page.</td>
+ <td>此标题是页面最顶部 （1级） 的标题。</td>
</tr>
<tr>
- <td rowspan="4" style="vertical-align : middle;"><b>Navigation</b></td>
+ <td rowspan="4" style="vertical-align : middle;"><b>导航</b></td>
<td>nav-id</td>
<td>%s</td>
- <td>The ID of the page. Other pages can use this ID as their nav-parent_id.</td>
+ <td>页面 ID。其他页面可以使用此 ID 作为他们的 nav-parent_id。</td>
</tr>
<tr>
<td>nav-parent_id</td>
<td>{root,%s}</td>
- <td>The ID of the parent page. The lowest navigation level is root.</td>
+ <td>页面父级 ID。最低导航级别为 root。</td>
</tr>
<tr>
<td>nav-pos</td>
<td>%d</td>
- <td>The relative position of pages per navigation level.</td>
+ <td>在每个导航级别下页面的相对位置。</td>
</tr>
<tr>
<td>nav-title</td>
<td>%s</td>
- <td>The title to use as an override of the default link text (title).</td>
+ <td>此标题用于重载默认的文本链接（标题）</td>
</tr>
</thead>
</table>
</font>
-Documentation-wide information and configuration settings that sit under
-`_config.yml` are also available to the front matter through the site variable.
-These settings can be accessed using the following syntax:
+文档范围的信息和配置位于 `_config.yml` 下，在前言中也是可用的，通过 site 变量使用。可以使用以下语法访问这些设置：
```liquid
{{ "{{ site.CONFIG_KEY " }}}}
```
-The placeholder will be replaced with the value of the variable named `CONFIG_KEY` when generating the documentation.
+当生成文档时，占位符会被替换成变量 `CONFIG_KEY` 的值。
-[Back to top](#top)
+[回到顶部](#top)
-## Formatting
+## 格式化
-Listed in the following sections are the basic formatting guidelines to get you
-started with writing documentation that is consistent and simple to navigate.
+以下各节列出了基本的格式准则，可以帮助你开始编写一致且易于浏览的文档。
-### Headings
+### 标题
-In Markdown, headings are any line prefixed with a hash (#), with the number of
-hashes indicating the level of the heading. Headings should be nested and
-consecutive — never skip a header level for styling reasons!
+在 Markdown 中，标题是任意以井号（#）开头的行，井号的数量表示标题级别。标题永远是嵌套和连续的--永远不能因为样式原因跳过标题级别！
<font size="3">
<table width="100%" class="table table-bordered">
<thead>
<tr>
- <th style="vertical-align : middle;"><center><b>Syntax</b></center></th>
- <th style="vertical-align : middle;"><center><b>Level</b></center></th>
- <th style="vertical-align : middle;"><center><b>Description</b></center></th>
+ <th style="vertical-align : middle;"><center><b>语法</b></center></th>
+ <th style="vertical-align : middle;"><center><b>级别</b></center></th>
+ <th style="vertical-align : middle;"><center><b>描述</b></center></th>
</tr>
<tr>
- <td># Heading</td>
- <td><center>Level-1</center></td>
- <td>The page title is defined in the Front Matter, so this level should <b>not be used</b>.</td>
+ <td># 标题</td>
+ <td><center>1级</center></td>
+ <td>页面标题在前言中定义，此级别标题 <b>不应该使用</b>。</td>
</tr>
<tr>
- <td>## Heading</td>
- <td><center>Level-2</center></td>
- <td>Starting level for Sections. Used to organize content by higher-level topics or goals.</td>
+ <td>## 标题</td>
+ <td><center>2级</center></td>
+ <td>章节的起始级别。用于按照高级别的主题或者目标来组织内容。</td>
</tr>
<tr>
- <td>### Heading</td>
- <td><center>Level-3</center></td>
- <td rowspan="2" style="vertical-align : middle;">Sub-sections. Used in each Section to separate supporting information or tasks.</td>
+ <td>### 标题</td>
+ <td><center>3级</center></td>
+ <td rowspan="2" style="vertical-align : middle;">子章节。在每个章节中用于分隔次要信息或者任务。</td>
</tr>
<tr>
- <td>#### Heading</td>
- <td><center>Level-4</center></td>
+ <td>#### 标题</td>
+ <td><center>4级</center></td>
</tr>
</thead>
</table>
</font>
<div class="alert alert-warning">
- <h3>Best Practice</h3>
+ <h3>最佳实践</h3>
- Use descriptive language in the phrasing of headings. For example, for a
- documentation page on dynamic tables, "Dynamic Tables and Continuous Queries"
- is more descriptive than "Background" or "Technical Information".
+ 标题使用叙述语言的措辞。例如，一个动态表格的文档页面，“动态表格和连续查询”就比“背景”或者“技术信息”更有描述性。
</div>
-### Table of Contents
+### 目录
-In the documentation build, the **Table Of Contents** (TOC) is automatically
-generated from the headings of the page using the following line of markup:
+在文档构建过程中，**标题**（TOC) 从页面标题自动生成，通过如下行标记使用：
```liquid
{{ "{:toc" }}}
```
-All headings up to **Level-3** are considered. To exclude a particular heading
-from the TOC:
+仔细考虑下大于 **3级** 的标题。在 TOC 中去除指定标题：
```liquid
-{{ "# Excluded Heading
+{{ "# 排除在外的标题
{:.no_toc" }}}
```
<div class="alert alert-warning">
- <h3>Best Practice</h3>
+ <h3>最佳实践</h3>
- Write a short and concise introduction to the topic that is being covered and
- place it before the TOC. A little context, such an outline of key messages,
- goes a long way in ensuring that the documentation is consistent and
- accessible to all levels of knowledge.
+ 为所涵盖的主题写一个简短的介绍，并放在 TOC 之前。一些上下文，例如关键信息的概述，对于确保文档的连贯、降低阅读门槛都大有帮助。
</div>
-### Navigation
+### 导航
-In the documentation build, navigation is defined using properties configured
-in the [front-matter variables](#front-matter) of each page.
+在文档构建中，导航的属性通过每个页面中的 [前言变量](#front-matter)配置。
-It's possible to use _Back to Top_ links in extensive documentation pages, so
-that users can navigate to the top of the page without having to scroll back up
-manually. In markup, this is implemented as a placeholder that is replaced with
-a default link when generating the documentation:
+在比较长的文档页面中使用 _回到首页_ 是很有必要的，这样用户就可以直接跳转到顶部而不用手动向上滑动。在使用标记中，通过在构建文档时替换占位符为一个默认的链接来实现：
```liquid
{{ "{% top " }}%}
```
<div class="alert alert-warning">
- <h3>Best Practice</h3>
-
- It's recommended to use Back to Top links at least at the end of each Level-2
- section.
+ <h3>最佳实践</h3>
+
+ 建议至少要在 2 级章节的结尾处添加回到首页链接。
</div>
-### Annotations
+### 标注
-In case you want to include edge cases, tightly related information or
-nice-to-knows in the documentation, it’s a (very) good practice to highlight
-them using special annotations.
+如果你需要在文档中添加边缘案例、紧密相关或者最好了解的信息，使用特殊的标注来高亮是一个（很）好的实践。
-* To highlight a tip or piece of information that may be helpful to know:
+* 突出显示提示以及有助于理解的信息：
```html
<div class="alert alert-info"> // Info Message </div>
```
-* To signal danger of pitfalls or call attention to an important piece of
- information that is crucial to follow:
+* 发出陷阱危险信号，或提醒关注必须要遵循的重要信息：
```html
<div class="alert alert-danger"> // Danger Message </div>
```
-### Links
+### 链接
-Adding links to documentation is an effective way to guide the user into a
-better understanding of the topic being discussed without the risk of
-overwriting.
+添加文档链接是一种有效的方法--可以引导用户更好的理解正在讨论的主题，而不会有重写的风险。
-* **Links to sections in the page.** Each heading generates an implicit
- identifier to directly link it within a page. This identifier is generated by
- making the heading lowercase and replacing internal spaces with hyphens.
+* **指向页面中各节的链接。** 每个标题都会生成一个隐式标识符，以便在页面中直接跳转。此标识符是通过将标题设置为小写并将内部空格替换为连字符来生成的。
- * **Heading:** ## Heading Title
- * **ID:** #heading-title
+ * **标题：** ## Heading Title
+ * **ID：** #heading-title
<p></p>
```liquid
[Link Text](#heading-title)
```
-* **Links to other pages of the Flink documentation.**
+* **链接到 Flink 文档的其他页面。**
{% raw %}
```liquid
[Link Text]({% link path/to/link-page.md %})
```
{% endraw %}
-* **Links to external pages**
+* **指向外部页面的链接**
```liquid
[Link Text](external_url)
```
<div class="alert alert-warning">
- <h3>Best Practice</h3>
+ <h3>最佳实践</h3>
- Use descriptive links that provide information on the action or destination.
- For example, avoid using "Learn More" or "Click Here" links.
+ 链使用可以提供操作或者目标信息的描述性链接名称。例如，避免使用“了解更多”或“单击此处”链接。
</div>
-### Visual Elements
+### 可视化内容
-Figures and other visual elements are placed under the root _fig_ folder and
-can be referenced in documentation pages using a syntax similar to that of
-links:
+图形和其他可视化内容放置在根目录的 _fig_ 目录下，可以使用类似于链接的语法在文档页面中引用：
```liquid
![Picture Text]({{ "{{ site.baseurl " }}}}/fig/image_name.png){:height="200px" width="200px"}
```
-Or using plain HTML:
+或者使用纯 HTML：
{% highlight html %}
<img src="{{ site.baseurl }}/fig/image_name.png" class="center" height="200px" width="200px"/>
{% endhighlight %}
<div class="alert alert-warning">
- <h3>Best Practice</h3>
+ <h3>最佳实践</h3>
- Use flowcharts, tables and figures where appropriate or necessary for
- additional clarification, but never as a standalone source of information.
- Make sure that any text included in those elements is large enough to read
- and that the overall resolution is adequate.
+ 在适当或必要的情况下使用流程图、表格和图形进行额外说明，但切勿作为独立的信息来源。确保内容中的字体大小不影响阅读，并且整体分辨率足够。
</div>
-### Code
+### 代码
-* **Inline code.** Small code snippets or references to language constructs in
- normal text flow should be highlighted using surrounding backticks ( **\`**
- ).
+* **行内代码、** 使用包围的反引号（ **\`**）来高亮正常文本流中的小代码段或者语言结构类型的引用。
-* **Code blocks.** Code that represents self-contained examples, feature
- walkthroughs, demonstration of best practices or other useful scenarios
- should be wrapped using a fenced code block with appropriate [syntax
- highlighting](https://github.com/rouge-ruby/rouge/wiki/List-of-supported-languages-and-lexers).
- One way of achieving this with markup is:
+* **代码块。** 表示自包含示例、功能演练、最佳实践演示或其他有用场景的代码，应使用带有适当 [语法突出]((https://github.com/rouge-ruby/rouge/wiki/List-of-supported-languages-and-lexers))显示的围栏代码块（fenced code block）进行包装。实现此目的的一种方式是标记：
Review Comment:
```suggestion
* **代码块。** 表示自包含示例、功能演练、最佳实践演示或其他有用场景的代码，应使用带有适当 [语法高亮]((https://github.com/rouge-ruby/rouge/wiki/List-of-supported-languages-and-lexers))显示的围栏代码块（fenced code block）进行包装。其中一种代码块实现方式如下：
```
##########
contributing/docs-style.zh.md:
##########
@@ -1,131 +1,82 @@
---
-title: "Documentation Style Guide"
+title: "文档样式指南"
---
-This guide provides an overview of the essential style guidelines for writing
-and contributing to the Flink documentation. It's meant to support your
-contribution journey in the greater community effort to improve and extend
-existing documentation — and help make it more **accessible**, **consistent**
-and **inclusive**.
+本指南概述了在编辑以及贡献 Flink 文档中必要的样式原则。目的是在你的贡献之旅中可以投入更好的社区精力去改进和扩展既有文档，并使其更 **易读**、 **一致** 和 **全面**。
{% toc %}
-## Language
+## 语言
-The Flink documentation is maintained in **US English** and **Chinese** — when
-extending or updating the documentation, both versions should be addressed in
-one pull request. If you are not familiar with the Chinese language, make sure
-that your contribution is complemented by these additional steps:
+Flink 同时维护了 **英语** 和 **中文** 两种文档，当你拓展或者更新文档时，需要在 pull request 中包含两种语言版本。如果你不熟悉中文，确保本次贡献补充了如下额外操作：
-* Open a
- [JIRA](https://issues.apache.org/jira/projects/FLINK/issues/FLINK-12070?filter=allopenissues)
- ticket for the translation, tagged with the chinese-translation component;
-* Link the ticket to the original contribution JIRA ticket.
+* 开一个翻译的 [JIRA](https://issues.apache.org/jira/projects/FLINK/issues/FLINK-12070?filter=allopenissues) 票据，并打上 chinese-translation 的标签；
+* 在此票据上添加到原始 JIRA 票据的链接。
-Looking for style guides to contribute with translating existing documentation
-to Chinese? Go ahead and consult [this translation
-specification](https://cwiki.apache.org/confluence/display/FLINK/Flink+Translation+Specifications).
+正在寻求有助于将现有文档翻译成中文的风格指南？请继续查阅 [这个翻译规范](https://cwiki.apache.org/confluence/display/FLINK/Flink+Translation+Specifications)。
-[Back to top](#top)
+[回到顶部](#top)
-## Language Style
+## 语言风格
-Below, you find some basic guidelines that can help ensure readability and
-accessibility in your writing. For a deeper and more complete dive into
-language style, also refer to the [General Guiding
-Principles](#general-guiding-principles).
+如下，你可以看到一些初步的原则，这些原则可以确保书写中的可读性和通俗易懂。如果想更深入、更细致的了解语言风格，也可以参考 [通用准则](#general-guiding-principles)。
-### Voice and Tone
+### 语态和语气
-* **Use active voice.** [Active
- voice](https://medium.com/@DaphneWatson/technical-writing-active-vs-passive-voice-485dfaa4e498)
- supports brevity and makes content more engaging. If you add _by zombies_
- after the verb in a sentence and it still makes sense, you are using the
- passive voice.
+* **使用主动语态。**[主动语态](https://medium.com/@DaphneWatson/technical-writing-active-vs-passive-voice-485dfaa4e498)简洁，并让内容更具有吸引力。如果你在句子的动词后添加 _by zombies_ 后仍然读的通，那么你用的就是被动语态。
Review Comment:
`If you add _by zombies_
after the verb in a sentence and it still makes sense, you are using the
passive voice.` 这句是阐释了英文中的被动语态，无法直接套用在中文中，建议换成中文的例子。
##########
contributing/docs-style.zh.md:
##########
@@ -1,131 +1,82 @@
---
-title: "Documentation Style Guide"
+title: "文档样式指南"
---
-This guide provides an overview of the essential style guidelines for writing
-and contributing to the Flink documentation. It's meant to support your
-contribution journey in the greater community effort to improve and extend
-existing documentation — and help make it more **accessible**, **consistent**
-and **inclusive**.
+本指南概述了在编辑以及贡献 Flink 文档中必要的样式原则。目的是在你的贡献之旅中可以投入更好的社区精力去改进和扩展既有文档，并使其更 **易读**、 **一致** 和 **全面**。
{% toc %}
-## Language
+## 语言
-The Flink documentation is maintained in **US English** and **Chinese** — when
-extending or updating the documentation, both versions should be addressed in
-one pull request. If you are not familiar with the Chinese language, make sure
-that your contribution is complemented by these additional steps:
+Flink 同时维护了 **英语** 和 **中文** 两种文档，当你拓展或者更新文档时，需要在 pull request 中包含两种语言版本。如果你不熟悉中文，确保本次贡献补充了如下额外操作：
-* Open a
- [JIRA](https://issues.apache.org/jira/projects/FLINK/issues/FLINK-12070?filter=allopenissues)
- ticket for the translation, tagged with the chinese-translation component;
-* Link the ticket to the original contribution JIRA ticket.
+* 开一个翻译的 [JIRA](https://issues.apache.org/jira/projects/FLINK/issues/FLINK-12070?filter=allopenissues) 票据，并打上 chinese-translation 的标签；
Review Comment:
`ticket` 在一些翻译中被翻译成`请求单`，如果比较难翻译的话，可以保持原始的`ticket`描述
##########
contributing/docs-style.zh.md:
##########
@@ -151,257 +102,220 @@ under the License.
-->
```
-Below are the front matter variables most commonly used along the Flink
-documentation.
+下面是 Flink 文档前言中常用的变量。
<font size="3">
<table width="100%" class="table table-bordered">
<thead>
<tr>
<th></th>
- <th style="vertical-align : middle;"><center><b>Variable</b></center></th>
- <th style="vertical-align : middle;"><center><b>Possible Values</b></center></th>
- <th style="vertical-align : middle;"><center><b>Description</b></center></th>
+ <th style="vertical-align : middle;"><center><b>变量名</b></center></th>
+ <th style="vertical-align : middle;"><center><b>可能值</b></center></th>
+ <th style="vertical-align : middle;"><center><b>描述</b></center></th>
</tr>
<tr>
- <td><b>Layout</b></td>
+ <td><b>布局</b></td>
<td>layout</td>
<td>{base,plain,redirect}</td>
- <td>The layout file to use. Layout files are located under the <i>_layouts</i> directory.</td>
+ <td>要使用的布局文件。布局文件位于 <i>_layouts</i> 目录下。</td>
</tr>
<tr>
- <td><b>Content</b></td>
+ <td><b>内容</b></td>
<td>title</td>
<td>%s</td>
- <td>The title to be used as the top-level (Level-1) heading for the page.</td>
+ <td>此标题是页面最顶部 （1级） 的标题。</td>
</tr>
<tr>
- <td rowspan="4" style="vertical-align : middle;"><b>Navigation</b></td>
+ <td rowspan="4" style="vertical-align : middle;"><b>导航</b></td>
<td>nav-id</td>
<td>%s</td>
- <td>The ID of the page. Other pages can use this ID as their nav-parent_id.</td>
+ <td>页面 ID。其他页面可以使用此 ID 作为他们的 nav-parent_id。</td>
</tr>
<tr>
<td>nav-parent_id</td>
<td>{root,%s}</td>
- <td>The ID of the parent page. The lowest navigation level is root.</td>
+ <td>页面父级 ID。最低导航级别为 root。</td>
</tr>
<tr>
<td>nav-pos</td>
<td>%d</td>
- <td>The relative position of pages per navigation level.</td>
+ <td>在每个导航级别下页面的相对位置。</td>
</tr>
<tr>
<td>nav-title</td>
<td>%s</td>
- <td>The title to use as an override of the default link text (title).</td>
+ <td>此标题用于重载默认的文本链接（标题）</td>
</tr>
</thead>
</table>
</font>
-Documentation-wide information and configuration settings that sit under
-`_config.yml` are also available to the front matter through the site variable.
-These settings can be accessed using the following syntax:
+文档范围的信息和配置位于 `_config.yml` 下，在前言中也是可用的，通过 site 变量使用。可以使用以下语法访问这些设置：
```liquid
{{ "{{ site.CONFIG_KEY " }}}}
```
-The placeholder will be replaced with the value of the variable named `CONFIG_KEY` when generating the documentation.
+当生成文档时，占位符会被替换成变量 `CONFIG_KEY` 的值。
-[Back to top](#top)
+[回到顶部](#top)
-## Formatting
+## 格式化
-Listed in the following sections are the basic formatting guidelines to get you
-started with writing documentation that is consistent and simple to navigate.
+以下各节列出了基本的格式准则，可以帮助你开始编写一致且易于浏览的文档。
-### Headings
+### 标题
-In Markdown, headings are any line prefixed with a hash (#), with the number of
-hashes indicating the level of the heading. Headings should be nested and
-consecutive — never skip a header level for styling reasons!
+在 Markdown 中，标题是任意以井号（#）开头的行，井号的数量表示标题级别。标题永远是嵌套和连续的--永远不能因为样式原因跳过标题级别！
Review Comment:
```suggestion
在 Markdown 中，标题是任意以井号（#）开头的行，井号的数量表示标题级别。标题永远是嵌套和连续的，不能因为样式原因跳过标题级别！
```
##########
contributing/docs-style.zh.md:
##########
@@ -1,131 +1,82 @@
---
-title: "Documentation Style Guide"
+title: "文档样式指南"
---
-This guide provides an overview of the essential style guidelines for writing
-and contributing to the Flink documentation. It's meant to support your
-contribution journey in the greater community effort to improve and extend
-existing documentation — and help make it more **accessible**, **consistent**
-and **inclusive**.
+本指南概述了在编辑以及贡献 Flink 文档中必要的样式原则。目的是在你的贡献之旅中可以投入更好的社区精力去改进和扩展既有文档，并使其更 **易读**、 **一致** 和 **全面**。
{% toc %}
-## Language
+## 语言
-The Flink documentation is maintained in **US English** and **Chinese** — when
-extending or updating the documentation, both versions should be addressed in
-one pull request. If you are not familiar with the Chinese language, make sure
-that your contribution is complemented by these additional steps:
+Flink 同时维护了 **英语** 和 **中文** 两种文档，当你拓展或者更新文档时，需要在 pull request 中包含两种语言版本。如果你不熟悉中文，确保本次贡献补充了如下额外操作：
-* Open a
- [JIRA](https://issues.apache.org/jira/projects/FLINK/issues/FLINK-12070?filter=allopenissues)
- ticket for the translation, tagged with the chinese-translation component;
-* Link the ticket to the original contribution JIRA ticket.
+* 开一个翻译的 [JIRA](https://issues.apache.org/jira/projects/FLINK/issues/FLINK-12070?filter=allopenissues) 票据，并打上 chinese-translation 的标签；
+* 在此票据上添加到原始 JIRA 票据的链接。
-Looking for style guides to contribute with translating existing documentation
-to Chinese? Go ahead and consult [this translation
-specification](https://cwiki.apache.org/confluence/display/FLINK/Flink+Translation+Specifications).
+正在寻求有助于将现有文档翻译成中文的风格指南？请继续查阅 [这个翻译规范](https://cwiki.apache.org/confluence/display/FLINK/Flink+Translation+Specifications)。
-[Back to top](#top)
+[回到顶部](#top)
-## Language Style
+## 语言风格
-Below, you find some basic guidelines that can help ensure readability and
-accessibility in your writing. For a deeper and more complete dive into
-language style, also refer to the [General Guiding
-Principles](#general-guiding-principles).
+如下，你可以看到一些初步的原则，这些原则可以确保书写中的可读性和通俗易懂。如果想更深入、更细致的了解语言风格，也可以参考 [通用准则](#general-guiding-principles)。
-### Voice and Tone
+### 语态和语气
-* **Use active voice.** [Active
- voice](https://medium.com/@DaphneWatson/technical-writing-active-vs-passive-voice-485dfaa4e498)
- supports brevity and makes content more engaging. If you add _by zombies_
- after the verb in a sentence and it still makes sense, you are using the
- passive voice.
+* **使用主动语态。**[主动语态](https://medium.com/@DaphneWatson/technical-writing-active-vs-passive-voice-485dfaa4e498)简洁，并让内容更具有吸引力。如果你在句子的动词后添加 _by zombies_ 后仍然读的通，那么你用的就是被动语态。
<div class="alert alert-info">
- <b>Active Voice</b>
+ <b>主动语态</b>
<p>"You can run this example in your IDE or on the command line."</p>
<p></p>
- <b>Passive Voice</b>
+ <b>被动语态</b>
<p>"This example can be run in your IDE or on the command line (by zombies)."</p>
</div>
-* **Use you, never we.** Using _we_ can be confusing and patronizing to some
- users, giving the impression that “we are all members of a secret club and
- _you_ didn’t get a membership invite”. Address the user as _you_.
-
-* **Avoid gender- and culture-specific language.** There is no need to identify
- gender in documentation: technical writing should be
- [gender-neutral](https://techwhirl.com/gender-neutral-technical-writing/).
- Also, jargon and conventions that you take for granted in your own language
- or culture are often different elsewhere. Humor is a staple example: a great
- joke in one culture can be widely misinterpreted in another.
-
-* **Avoid qualifying and prejudging actions.** For a user that is frustrated or
- struggling to complete an action, using words like _quick_ or _easy_ can lead
- to a poor documentation experience.
-
-* **Avoid using uppercase words** to highlight or emphasize statements.
- Highlighting key words with e.g. **bold** or _italic_ font usually appears more polite.
- If you want to draw attention to important but not obvious statements,
- try to group them into separate paragraphs starting with a label,
- highlighted with a corresponding HTML tag:
+* **使用你，而不是我们。** 用 _我们_ 会让用户感到困惑以及傲慢，给人“我们是一个秘密组织的成员，而 _你_ 并没有获得会员邀请”的感觉。所以用 _你_ 来建议用户。
+
+* **避免使用针对性别和文化的语言。**文档无需指定性别：技术写作应当 [性别中立](https://techwhirl.com/gender-neutral-technical-writing/)。还有，在你的文化和日常交流中被认为是理所应当的行话和惯例，在其他地方可能很不一样。幽默就是很典型的例子：在某个文化中很棒的笑话，但在其他文化中可能被广泛误解。
+
+* **避免对操作做能力限定以及对难度提前下结论。**对于很艰难才能完成操作或者操作中很容易沮丧的用户，使用诸如 _快速_ 或者 _容易_ 是糟糕的文档体验。
+
+* **避免使用大写单词**来突出或者强调陈述。使用例如 **加粗** 或者 _斜体_ 来突出关键词通常会更礼貌。如果一个不明显的声明需要突出以引起更多的注意，可以按照段落分组，段落以标签开头，配合对应的 HTML 标记来突出显示：
* `<span class="label label-info">Note</span>`
* `<span class="label label-warning">Warning</span>`
* `<span class="label label-danger">Danger</span>`
-### Using Flink-specific Terms
+### 使用 Flink 特定术语
-Use clear definitions of terms or provide additional instructions on what
-something means by adding a link to a helpful resource, such as other
-documentation pages or the [Flink
-Glossary]({{site.DOCS_BASE_URL}}flink-docs-stable/docs/concepts/glossary).
-The Glossary is a work in progress, so you can also propose new terms by
-opening a pull-request.
+使用清晰的术语定义，也可以对要表达的内容提供有帮助的资源链接来辅助说明，例如其他的文档页面或者 [Flink 术语表]({{site.DOCS_BASE_URL}}flink-docs-stable/docs/concepts/glossary)。目前，术语表仍在编辑中，新术语可以开 pull-request 来提交。
-[Back to top](#top)
+[回到顶部](#top)
-## Repository
+## 仓库
Review Comment:
```suggestion
## 代码仓库
```
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@flink.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org