Mrzyxing commented on code in PR #548:
URL: https://github.com/apache/flink-web/pull/548#discussion_r895002853
##########
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:
已明确，待前面问题确认完一起提交。
##########
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:
再读一遍后，结合前面已经明确主语是标题的情况下，直接改为 `，不能因为样式原因跳级` ，是不是更通顺点？
--
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: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
