Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

docs(cn): translate src/content/contribute/writers-guide.mdx #1342

Merged
merged 3 commits into from
Sep 13, 2023
Merged

docs(cn): translate src/content/contribute/writers-guide.mdx #1342

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
28e75c7
1. 补上 webpack 4 翻译漏的 Assumptions and simplicity 和 Configuration defau…
jsbugwang Oct 12, 2021
781f831
docs(cn): review and update
Yucohny Sep 13, 2023
08ff896
Merge branch 'cn' into writers-guide-cn-upstream
Yucohny Sep 13, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
193 changes: 99 additions & 94 deletions src/content/contribute/writers-guide.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,66 +1,71 @@
---
title: Writer's Guide
title: 作者指引
sort: 1
contributors:
- pranshuchittora
- EugeneHlushko
translators:
- jsbugwang
- Yucohny
---

The following sections contain all you need to know about editing and formatting the content within this site. Make sure to do some research before starting your edits or additions. Sometimes the toughest part is finding where the content should live and determining whether or not it already exists.
以下部分包含编辑和格式化本网站内容的所有必需知识。请确保在开始编辑或添加之前，你已经进行过一些研究。有时候最困难的地方在于，确定内容应该在哪和确定它是否存在。

## Process $#process$
## 步骤 $#process$

1. Check related issue if an article links to one.
2. Hit `edit` and expand on the structure.
3. PR changes.
1. 如果文章包含 issue 链接，先查看 issue。
2. 点击编辑并阐述结构。
3. 提交 PR 修改。

## YAML Frontmatter $#yaml-frontmatter$
## YAML 文件顶部信息 $#yaml-frontmatter$

Each article contains a small section at the top written in [YAML Frontmatter](https://jekyllrb.com/docs/frontmatter/):
每篇文章的顶部都包含一小部分 [YAML Frontmatter](https://jekyllrb.com/docs/frontmatter/) 格式的内容：

```yaml
---
title: My Article
group: My Sub-Section
title: 我的文章
group: 我的小节
sort: 3
contributors:
- [github username]
- [github 用户名]
related:
- title: Title of Related Article
url: [url of related article]
- title: 相关文章的标题
url: [相关文章的 url]
---
```

Let's break these down:
让我们来逐个分析：

- `title`: The name of the article.
- `group`: The name of the sub-section
- `sort`: The order of the article within its section (or) sub-section if it is present.
- `contributors`: A list of GitHub usernames who have contributed to this article.
- `related`: Any related reading or useful examples.
- `title`：文章的名称。
- `group`：小节的名称。
- `sort`：这篇文章在此类（或子类）中的顺序（如果存在同类）。
- `contributors`：文章贡献者的 GitHub 用户名列表。
- `related`：任何相关阅读或有用示例。

Note that `related` will generate a **Further Reading** section at the bottom of the page and `contributors` will yield a **Contributors** section below it. If you edit an article and would like recognition, don't hesitate to add your GitHub username to the `contributors` list.
请注意，`related` 将在页面底部生成 **Further Reading** 部分，`contributors` 将在其下生成 **Contributors** 部分。如果你编辑了一篇文章，并希望获得认可，请不要犹豫，将你的 GitHub 用户名添加到 `contributors` 列表中。

## Article Structure $#article-structure$
## 文章结构 $#article-structure$

1. Brief Introduction - a paragraph or two so you get the basic idea about the what and why.
2. Outline Remaining Content – how the content will be presented.
3. Main Content - tell what you promised to tell.
4. Conclusion - tell what you told and recap the main points.
1. 简介 —— 一两个段落，以便你了解关于什么和为什么的基本想法。
2. 概述剩余内容 —— 将如何呈现内容。
3. 主要内容 —— 讲述你承诺要讲的内容。
4. 结论 —— 讲述你讲了什么并复述要点。

## Typesetting $#typesetting$
## 排版 $#typesetting$

- Webpack can be written with a capital W at the beginning of a sentence. ([source](https://github.com/webpack/media#name))
- loaders are enclosed in backticks and [kebab-cased](https://en.wikipedia.org/w/index.php?title=Kebab_case): `css-loader`, `ts-loader`, …
- plugins are enclosed in backticks and [camel-cased](https://en.wikipedia.org/wiki/Camel_case): `BannerPlugin`, `NpmInstallWebpackPlugin`, …
- Use "webpack 2" to refer to a specific webpack version (~~"webpack v2"~~)
- Use ES5; ES2015, ES2016, … to refer to the ECMAScript standards (~~ES6~~, ~~ES7~~)
- Webpack 作为句子的第一个单词时，W 可以大写。参考 [source](https://github.com/webpack/media#name) 以了解更多。
- loader 应当用反引号包裹，并且使用 [kebab-cased](https://en.wikipedia.org/w/index.php?title=Kebab_case)：`css-loader`，`ts-loader`，……
- plugin 应当用反引号包裹，并且使用 [camel-cased](https://en.wikipedia.org/wiki/Camel_case): `BannerPlugin`， `NpmInstallWebpackPlugin`，……
- 使用 "webpack 2" 指代特定的 webpack 版本 (~~"webpack v2"~~)
- 使用 ES5; ES2015, ES2016, …… 指代 ECMAScript 标准 (~~ES6~~, ~~ES7~~)

## Formatting $#formatting$
> 译者注：中文文档排版规范不必依照于此。

### Code $#code$
## 格式化 $#formatting$

**Syntax: \`\`\`javascript … \`\`\`**
### 代码 $#code$

**语法：\`\`\`javascript … \`\`\`**

```javascript
function foo() {
Expand All @@ -70,156 +75,156 @@ function foo() {
foo();
```

#### Quotation $#quotation$
#### 引号 $#quotation$

Use single quotes in code snippets and project files (`.jsx`, `.scss` etc):
在代码片段和项目文件中使用单引号 (`.jsx`， `.scss` 等)：

```diff
- import webpack from "webpack";
+ import webpack from 'webpack';
```

And in inline backticks:
行内反引号也是一样：

**correct**
**正确**

Set value to `'index.md'`...
把值设置为 `'index.md'`……

**incorrect**
**错误**

Set value to `"index.md"`...
把值设置为 `"index.md"`……

### Lists $#lists$
### 列表 $#lists$

- Boo
- Foo
- Zoo

Lists should be ordered alphabetically.
列表应该按字母顺序排序。

### Tables $#tables$
### 表格 $#tables$

| Parameter | Explanation | Input Type | Default Value |
| ---------- | ------------------------------------------------ | ---------- | ------------- |
| --debug | Switch loaders to debug mode | boolean | false |
| --devtool | Define source map type for the bundled resources | string | - |
| --progress | Print compilation progress in percentage | boolean | false |
| 参数 | 解释说明 | 输入类型 | 默认值 |
| ---------- | -------------------------------- | -------- | ------ |
| --debug | 把 loader 切换为 debug 模式 | boolean | false |
| --devtool | 为打包的资源定义 source map 类型 | string | - |
| --progress | 打印 compilation 的百分比进度 | boolean | false |

Tables should also be ordered alphabetically.
表格也应该按字母顺序排序。

### Configuration Properties $#configuration-properties$
### 配置属性 $#configuration-properties$

The [configuration](/configuration) properties should be ordered alphabetically as well:
[配置](/configuration) 属性，应该按字母顺序排序：

- `devServer.compress`
- `devServer.hot`
- `devServer.static`

### Quotes $#quotes$
### 引用 $#quotes$

#### Blockquote $#blockquote$
#### 引用块 $#blockquote$

**Syntax: \>**
**语法：\>**

> This is a blockquote.
> 这是一个引用块。

#### Tip $#tip$
#### 提示 $#tip$

**Syntax: T\>**
**语法：T\>**

T> This is a tip.
T> 这是一个提示。

**Syntax: W\>**
**语法：W\>**

W> This is a warning.
W> 这是一个警告。

**Syntax: ?\>**
**语法：?\>**

?> This is a todo.
?> 这是一个 todo 待办项。

### Assumptions and simplicity $#assumptions-and-simplicity$
### 假设与详略 $#assumptions-and-simplicity$

Do not make assumptions when writing the documentation.
写文档时，不要做假设：

```diff
- You might already know how to optimize bundle for production...
+ As we've learned in [production guide](/guides/production/)...
- 你可能已经知道如何为生产环境优化 bundle ……
+ 我们在 [production guide](/guides/production/) 学习过……
```

Please do not assume things are simple. Avoid words like 'just', 'simply'.
请不要假设事情简单。避免使用词汇“只是”，“简单地”。

```diff
- Simply run command...
+ Run the `command-name` command...
- 简单地运行命令……
+ 运行 `command-name` 命令……
```

### Configuration defaults and types $#configuration-defaults-and-types$
### 配置的默认值和类型 $#configuration-defaults-and-types$

Always provide types and defaults to all of the documentation options in order to keep the documentation accessible and well-written. We are adding types and defaults after entitling the documented option:
总是为所有文档选项提供类型和默认值，以保持文档的可读性和良好书写。我们在选项后面加上类型和默认值：

**configuration.example.option**

`string = 'none'`

Where `= 'none'` means that the default value is `'none'` for the given option.
这里 `= 'none'` 表示指定选项的默认值是 `'none'` 。

`string = 'none': 'none' | 'development' | 'production'`

Where `: 'none' | 'development' | 'production'` enumerates the possible type values, in this case, three strings are acceptable: `'none'`, `'development'`, and `'production'`.
这里 `: 'none' | 'development' | 'production'` 枚举所有可能的类型值，本例接受 3 个字符串：`'none'`, `'development'` 和 `'production'`。

Use space between types to list all available types for the given option:
在类型之间使用空格，为指定选项列举所有可用的类型：

`string = 'none': 'none' | 'development' | 'production'` `boolean`

To mark an array, use square brackets:
使用方括号表示数组：

`string` `[string]`

If multiple types are allowed in `array`, use comma:
如果 `数组` 允许多种类型，使用英文逗号：

`string` `[string, RegExp, function(arg) => string]`

To mark a function, also list arguments when they are available:
标记为函数时，如果有参数，应同时把参数列出来：

`function (compilation, module, path) => boolean`

Where `(compilation, module, path)` lists the arguments that the provided function will receive and `=> boolean` means that the return value of the function must be a `boolean`.
这里 `(compilation, module, path)` 列举指定函数接受的参数，`=> boolean` 表示函数返回值的类型必须是 `boolean`。

To mark a Plugin as an available option value type, use the camel case title of the `Plugin`:
标记 Plugin 为可用的选项值类型时，使用 `Plugin` 的 camel case 标题：

`TerserPlugin` `[TerserPlugin]`

Which means that the option expects one or few `TerserPlugin` instances.
这表示选项接受一个或多个 `TerserPlugin` 实例。

To mark a number, use `number`:
使用 `number` 标记为 number ：

`number = 15: 5, 15, 30`

To mark an object, use `object`:
使用 `object` 标记为对象：

`object = { prop1 string = 'none': 'none' | 'development' | 'production', prop2 boolean = false, prop3 function (module) => string }`

When object's key can have multiple types, use `|` to list them. Here is an example, where `prop1` can be both a string and an array of strings:
当对象的 key 可以有多个类型时，用 `|` 列来出。如下例子，`prop1` 可以是字符串或字符串数组：

`object = { prop1 string = 'none': 'none' | 'development' | 'production' | [string]}`

This allows us to display the defaults, enumeration and other information.
这样我们可以展示默认值，枚举和其他信息。

If the object's key is dynamic, user-defined, use `<key>` to describe it:
如果对象的 key 是动态的，用户自定义的，用 `<key>` 来描述：

`object = { <key> string }`

### Options shortlists and their typing $#options-shortlists-and-their-typing$
### 选项 shortlist 及其类型 $#options-shortlists-and-their-typing$

Sometimes, we want to describe certain properties of objects and functions in lists. When applicable add typing directly to the list where properties are enlisted:
有时，我们希望描述对象的某些属性，以及列表中的函数。在属性列表直接添加即可：

- `madeUp` (`boolean = true`): short description
- `shortText` (`string = 'i am text'`): another short description
- `madeUp` (`boolean = true`): 简短描述
- `shortText` (`string = 'i am text'`): 另一个简短描述

W> `:` is not a necessity here, note the property, type and default.
W> `:` 不是必须的。注意属性名，类型和默认值。

An example can be found on the [`options` section of the EvalSourceMapDevToolPlugin's page](/plugins/eval-source-map-dev-tool-plugin/#options).
[EvalSourceMapDevToolPlugin 页面的 `选项` 部分](/plugins/eval-source-map-dev-tool-plugin/#options) 有一个例子。

### Adding links $#adding-links$
### 添加链接 $#adding-links$

Please use relative URLs (such as `/concepts/mode/`) to link our own content instead of absolute URLs (such as `https://webpack.js.org/concepts/mode/`).
请使用相对 URL (如 `/concepts/mode/`) 来链接到自有内容，不要用绝对 URL (如 `https://webpack.js.org/concepts/mode/`)。
Loading