Myasuka commented on code in PR #548:
URL: https://github.com/apache/flink-web/pull/548#discussion_r895302020
##########
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:
嗯，如果这样子的话，还是需要翻译一下，我看目前还是保持着 `票据`的翻译。
##########
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:
`跳级`在一般语义下，有“升学跳级”的含义，感觉还是要避免歧义，多一些描述。
##########
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:
我想了想，这个文档的目的还是以写出好的英文文档。中文文档不是Flink社区的第一语言，所以面向的对象确实是如何写出优秀的英文文档。关于 `by the
zombines`的说法，应该是英文俚语，我看很多翻译书籍中也有类似的表达：[清晰簡明的英文寫作指南](https://books.google.com.hk/books?id=WkEyEAAAQBAJ&pg=PA8&lpg=PA8&dq=by+zombies+%E8%A2%AB%E5%8A%A8%E8%AF%AD%E6%80%81&source=bl&ots=sJb76uNdna&sig=ACfU3U2T6wB2A1lDS7yR_qwMylItfvw-Hw&hl=zh-CN&sa=X&redir_esc=y&sourceid=cndr#v=onepage&q=by%20zombies%20%E8%A2%AB%E5%8A%A8%E8%AF%AD%E6%80%81&f=false)
--
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]
