Merge remote-tracking branch 'origin/cn' into cn

Author: dear-lizhihua

content/guides/hmr-react.md

@@ -38,19 +38,19 @@ npm install --save [email protected] [email protected]
 {
   "presets": [
     ["es2015", {"modules": false}],
-    // webpack understands the native import syntax, and uses it for tree shaking
+    // webpack现在已经支持原生的import语句了, 并且将其运用在tree-shaking特性上
 
     "stage-2",
-    // Specifies what level of language features to activate.
-    // Stage 2 is "draft", 4 is finished, 0 is strawman.
-    // See https://tc39.github.io/process-document/
+    // 规定JS运用的语言规范层级
+    // Stage 2 是 "草案", 4 是 "已完成", 0 is "稻草人(strawman)"。
+    // 详情查看 https://tc39.github.io/process-document/
 
     "react"
-    // Transpile React components to JavaScript
+    // 转译React组件为JS代码
   ],
   "plugins": [
     "react-hot-loader/babel"
-    // Enables React code to work with HMR.
+    // 开启react代码的模块热替换（HMR）
   ]
 }
 ```
@@ -66,27 +66,28 @@ const webpack = require('webpack');
 module.exports = {
   entry: [
     'react-hot-loader/patch',
-    // activate HMR for React
+    // 开启react代码的模块热替换（HMR）
 
     'webpack-dev-server/client?http://localhost:8080',
-    // bundle the client for webpack-dev-server
-    // and connect to the provided endpoint
+    // 为webpack-dev-server的环境打包好运行代码
+    // 然后连接到指定服务器域名与端口
 
     'webpack/hot/only-dev-server',
-    // bundle the client for hot reloading
-    // only- means to only hot reload for successful updates
+    // 为热替换（HMR）打包好运行代码
+    // only- 意味着只有成功更新运行代码才会执行热替换（HMR）
 
 
     './index.js'
-    // the entry point of our app
+    // 我们app的入口文件
   ],
   output: {
     filename: 'bundle.js',
-    // the output bundle
+    // 输出的打包文件
 
     path: resolve(__dirname, 'dist'),
 
     publicPath: '/'
+    // 对于热替换（HMR）是必须的，让webpack知道在哪里载入热更新的模块（chunk）
     // necessary for HMR to know where to load the hot update chunks
   },
 
@@ -96,13 +97,13 @@ module.exports = {
 
   devServer: {
     hot: true,
-    // enable HMR on the server
+    // 开启服务器的模块热替换（HMR）
 
     contentBase: resolve(__dirname, 'dist'),
-    // match the output path
+    // 输出文件的路径
 
     publicPath: '/'
-    // match the output `publicPath`
+    // 和上文output的"publicPath"值保持一致
   },
 
   module: {
@@ -127,15 +128,16 @@ module.exports = {
 
   plugins: [
     new webpack.HotModuleReplacementPlugin(),
-    // enable HMR globally
+    // 开启全局的模块热替换（HMR）
 
     new webpack.NamedModulesPlugin(),
+    // 当模块热替换（HMR）时在浏览器控制台输出对用户更友好的模块名字信息
     // prints more readable module names in the browser console on HMR updates
   ],
 };
 ```
 
-上面的内容涵盖了 webpack 配置的方方面面，并不是全部都和 HMR 相关。这个 webpack 开发服务器的[完整的文档](https://webpack.github.io/docs/webpack-dev-server.html)能够让你对它了解更多，这些在 webpack.js.org 上的[文章](https://webpack.js.org/concepts/)也应该一读。
+上面的内容涵盖了 webpack 配置的方方面面，并不是全部都和 HMR 相关。这个 webpack 开发服务器的[完整的文档](https://webpack.github.io/docs/webpack-dev-server.html)能够让你对它了解更多，这些在 webpack.js.org 上的[文章](https://doc.webpack-china.org/concepts/)也应该一读。
 
 这里有一个基本假设，便是你的 JavaScript 入口在 `./src/index.js`，还有，你在使用 CSS 模块。
 
@@ -173,7 +175,7 @@ const render = (Component) => {
 
 render(App);
 
-// Hot Module Replacement API
+// 模块热替换的 API
 if (module.hot) {
   module.hot.accept('./components/App', () => {
     render(App)
@@ -211,23 +213,25 @@ export default App;
 
 2. 因此，我们可以使用 `module.hot` 钩子函数为特定资源启用 HMR（这里是`App.js`）。这里最重要的 API 是 `module.hot.accept`，它指定如何处理对特定依赖的更改。
 
-3. 注意，因为 webpack 2 对 ES2015 模块有内置的支持，你不需要在 `module.hot.accept` 中重新引入你的根组件。要完成这项工作，你需要更改 Babel ES2015 在 `.babelrc` 的预设：
+3. 注意，因为 webpack 2 对 ES2015 模块有内置的支持，你不需要在 `module.hot.accept` 中重新引入你的根组件。要完成这项工作，你需要更改 Babel ES2015 在 `.babelrc` 的预设值：
 
   ```
   ["es2015", {"modules": false}]
   ```
 
-  like what we did in [Babel Config](#babel-config). Note that disabling Babel's module plugin is not only necessary for HMR. If you don't disable it you'll run into many other issues (see [Migrating from v1 to v2](/guides/migrating/#mixing-es2015-with-amd-and-commonjs) and [webpack-tree-shaking](http://www.2ality.com/2015/12/webpack-tree-shaking.html)).
+  与我们在 [Babel 配置文件](#babel-config) 中所配置的是一样的。注意，不仅仅只有模块热替换的场景需要禁用Babel模块插件。如果你不将此插件禁用，你可能会遇到许多其他的问题(查看 [从webpack v1 迁移到 v2](/guides/migrating/#mixing-es2015-with-amd-and-commonjs) 和 [webpack-tree-shaking](http://www.2ality.com/2015/12/webpack-tree-shaking.html))。
 
-4. Note that if you're using ES6 modules in your webpack 2 configuration file, and you change your `.babelrc` file in #3 above, you either need to use `require` or create two `.babelrc` files (issue [here](https://github.com/webpack/webpack.js.org/issues/154)):
-  * One in the project root directory with `"presets": ["es2015"]
-  * One in the home directory for webpack to build. For this example, in `src/`.
+4. 注意，如果你在webpack 2 配置文件中启用了ES6模块，并且按照上文#3 的配置，修改了你的`.babelrc` 文件，你需要使用`require`命令，或者，创建两个`.babelrc`文件(查看问题 [这里](https://github.com/webpack/webpack.js.org/issues/154)):
+  * 一个文件放置在项目的根目录，并且加上配置: `"presets": ["es2015"]`
+  * 另一个文件放置在webpack要构建代码的主目录。在这个例子里，放置的目录路径是`src/`
+
+所以，在这种情景下，当 `src/components/App.js` 或者它的依赖文件被更改了， `module.hot.accept` 将会触发 `render` 方法，这意味着，因为 `App.js` 里面包含了对 `App.css` 的引用, 所以 `render` 方法同样会在 `App.css` 被修改的时候触发，
 
-So in this case, `module.hot.accept` will fire the `render` method whenever `src/components/App.js` or its dependencies are changed - which means the `render` method will also fire when the `App.css` is changed, since `App.css` is included in `App.js`.
 
 ### index.html
 
-This needs to be placed inside of `dist` in your project root. webpack-dev-server will not run without it.
+这个文件需要放置在你的项目根路径下的 `dist`目录，不然 webpack-dev-server 将因为缺少这个文件而无法运行。
+
 
 ```html
 <!DOCTYPE html>

content/plugins/extract-text-webpack-plugin.md

@@ -4,11 +4,11 @@ title: extract-text-webpack-plugin
 
 # extract text plugin for webpack 2
 
-API 从版本1起已经改变。用于 webpack 1 的版本，请看[the README in the webpack-1 branch](https://github.com/webpack/extract-text-webpack-plugin/blob/webpack-1/README.md)。
+和 webpack 1 版本相比 API 已经发生改变。对于 webpack 1 版本，请查看 [webpack-1 分支的 README 文档](https://github.com/webpack/extract-text-webpack-plugin/blob/webpack-1/README.md)。
 
 ## 安装
 
-> 你可以用 [npm](https://nodejs.org/en/) 或者 [yarn](https://yarnpkg.com/)安装它。
+> 可以使用 [npm](https://nodejs.org/en/) 或者 [yarn](https://yarnpkg.com/) 来安装。
 
 ```sh
 npm install --save-dev extract-text-webpack-plugin
@@ -18,7 +18,7 @@ or
 yarn add --dev extract-text-webpack-plugin
 ```
 
-## css的使用例子
+## CSS 的用法示例
 
 ``` javascript
 var ExtractTextPlugin = require("extract-text-webpack-plugin");
@@ -37,56 +37,56 @@ module.exports = {
 }
 ```
 
-它会将所有的 入口chunk (entry chunks) 中的 `require("style.css")` 移动到分开的 css 文件。因此，你的样式不再内联到 javascript 里面，但会放到一个单独的 css 包文件 (`styles.css`)当中。 如果你的样式文件大小较大，这会更快，因为样式文件会跟 javascript 包并行加载。
+它会将每个「入口 chunk(entry chunks)」中的 `require("style.css")` 移动到分离的 css 输出文件中。所以，你的样式不再内联到 javascript 里面，而是分离到 css bundle(`styles.css`) 文件中。如果样式总量很大，加载就会变得很快，因为样式 bundle 会并行加载到 javascript bundle 中。
 
-优点:
+优势：
 
-* 更少 style 标签 (旧版本的 IE 浏览器有限制)
-*  CSS SourceMap (使用 `devtool: "source-map"` 和 `css-loader?sourceMap` 配置)
+* 更少的 style 标签（旧版本的 IE 浏览器对 style 标签数量有限制）
+* CSS SourceMap（使用 `devtool: "source-map"` 和 `css-loader?sourceMap` 配置）
 * CSS 请求并行
 * CSS 单独缓存
-* 更快的浏览器运行时 (更少代码和 DOM 的运行)
+* 更快的浏览器运行时(runtime)（减少代码和减少 DOM 操作）
 
-警告:
+警告：
 
 * 额外的 HTTP 请求
 * 更长的编译时间
 * 更复杂的配置
-* 没有运行时的公共路径修改
-* 没有热替换
+* 没有运行时(runtime)的公共路径修改
+* 没有模块热替换
 
 ## API
 
 ``` javascript
 new ExtractTextPlugin(options: filename | object)
 ```
 
-* `options.filename: string` _(必填)_ 生成文件的文件名。会包含 `[name]`, `[id]` 和 `[contenthash]`
+* `options.filename: string` _（必选）_ 生成文件的文件名。可能包含 `[name]`, `[id]` 和 `[contenthash]`
   * `[name]` chunk 的名称
   * `[id]` chunk 的数量 
-  * `[contenthash]` 根据提取文件内容的哈希值
-* `options.allChunks: boolean` 向所有额外的 chunk 提取（默认只提取初始加载模块）
+  * `[contenthash]` 提取文件内容的哈希值
+* `options.allChunks: boolean` 向所有额外的 chunk 中提取（默认情况下，只从初始chunk 提取）
 * `options.disable: boolean` 禁用插件
-* `options.id: string` 此插件实例的唯一id。 （仅限高级用途，默认情况下自动生成）
+* `options.id: string` 此插件实例的唯一 id。（仅限于高级用法，默认情况下自动生成）
 
-The `ExtractTextPlugin` 每个 入口chunk 都会生成一个文件，所以当你使用多个 入口chunk 的时候，你必须使用 `[name]`, `[id]` 或者 `[contenthash]`.
+`ExtractTextPlugin` 为每个入口 chunk 生成一个输出文件，所以在使用多个入口时，你必须使用 `[name]`, `[id]` 或者 `[contenthash]`。
 
 ``` javascript
 ExtractTextPlugin.extract(options: loader | object)
 ```
 
-从已经有的加载器里创建一个提取的加载器，支持加载器类似，如 `{ loader: string; query: object }`。
+从已有的 loader 中创建一个用于提取的 loader，支持的 loader 如 `{ loader: string; query: object }` 这种类型。
 
-* `options.loader: string | object | loader[]` _(必填)_ 加载器应用于将资源转换成 css 输出模块。
-* `options.fallbackLoader: string | object | loader[]` 加载器应用于当 css 没有被提取(也就是一个额外的 chunk，当 `allChunks: false`)
-* `options.publicPath: string` 对加载器的 `publicPath` 配置重写
+* `options.loader: string | object | loader[]` _(必选)_loader 用于将资源转换为 css 导出模块
+* `options.fallbackLoader: string | object | loader[]` loader 用于在 css 没有被提取时(例如，在 `allChunks: false` 时的额外的 chunk)
+* `options.publicPath: string` 重写 loader 的 `publicPath` 设置
 
-这也是一个 提取函数的实例。如果你有多于一个 `ExtractTextPlugin` 插件 你应使用这种办法。
+在 extract 实例还有一个 extract 函数。如果有多个 `ExtractTextPlugin` 实例，你应该使用此方法。
 
 ```javascript
 let ExtractTextPlugin = require('extract-text-webpack-plugin');
 
-// 多个提取实例
+// 多个 extract 实例
 let extractCSS = new ExtractTextPlugin('stylesheets/[name].css');
 let extractLESS = new ExtractTextPlugin('stylesheets/[name].less');
 

content/plugins/index.md

@@ -4,16 +4,17 @@ contributors:
   - simon04
 ---
 
-webpack has a rich plugin interface. Most of the features within webpack itself use this plugin interface. This makes webpack **flexible**.
+webpack 有着大量的插件接口(plugin interface)。多数功能由 webpack 自己的插件接口提供。这些插件使 webpack 变得**极其灵活**。
 
-|Name|Description|
+
+|名称|描述|
 |:--:|:----------|
-|[commons-chunk-plugin](/plugins/commons-chunk-plugin)|Generates chunks of common modules shared between entry points and splits them into separate  bundles, e.g., `1vendor.bundle.js` && `app.bundle.js`|
-|[extract-text-webpack-plugin](/plugins/extract-text-webpack-plugin)|Extracts Text (CSS) from your bundles into a separate file (app.bundle.css)|
-|[component-webpack-plugin](/plugins/component-webpack-plugin)|Use components with webpack|
-|[compression-webpack-plugin](/plugins/compression-webpack-plugin)|Prepare compressed versions of assets to serve them with Content-Encoding|
-|[i18n-webpack-plugin](/plugins/i18n-webpack-plugin)|Adds i18n support to your bundles|
-|[html-webpack-plugin](/plugins/html-webpack-plugin)| Simplifies creation of HTML files (`index.html`) to serve your bundles|
+|[commons-chunk-plugin](/plugins/commons-chunk-plugin)|将多个入口起点之间共享的公共模块，生成为一些 chunk，并且分离到单独的 bundle 中，例如，`1vendor.bundle.js` 和 `app.bundle.js`|
+|[extract-text-webpack-plugin](/plugins/extract-text-webpack-plugin)|从 bundle 中提取文本（CSS）到分离的文件（app.bundle.css）|
+|[component-webpack-plugin](/plugins/component-webpack-plugin)|通过 webpack 中使用组件|
+|[compression-webpack-plugin](/plugins/compression-webpack-plugin)|预先准备的资源压缩版本，使用 Content-Encoding 提供访问服务|
+|[i18n-webpack-plugin](/plugins/i18n-webpack-plugin)|为 bundle 增加国际化支持|
+|[html-webpack-plugin](/plugins/html-webpack-plugin)| 用于简化 HTML 文件（`index.html`）的创建，提供访问 bundle 的服务。|
 
 ***
 

content/plugins/source-map-dev-tool-plugin.md

@@ -6,19 +6,19 @@ contributors:
 
 ?> Review this content
 
-Adds SourceMaps for assets.
+给资源添加 SourceMap。
 
 ```javascript
 new webpack.SourceMapDevToolPlugin(options)
 ```
 
-* `options.test` / `options.include` / `options.exclude` (`string|RegExp|Array`): Used to determine which assets should be processed. Each one can be a `RegExp` (asset filename is matched), a `string` (asset filename need to start with this string) or an `Array` of those (any of them need to be matched). `test` defaults to `.js` files if omitted.
-* `options.filename` (`string`): defines the output filename of the SourceMap. If no value is provided the SourceMap is inlined.
-* `options.append` (`string`): is appended to the original asset. Usually the `#sourceMappingURL` comment. `[url]` is replaced with a URL to the SourceMap file. `false` disables the appending.
-* `options.moduleFilenameTemplate` / `options.fallbackModuleFilenameTemplate` (`string`): see `output.devtoolModuleFilenameTemplate`.
-* `options.module` (`boolean`):  (defaults to `true`) When `false` loaders do not generate SourceMaps and the transformed code is used as source instead.
-* `options.columns` (`boolean`):  (defaults to `true`) When `false` column mappings in SourceMaps are ignored and a faster SourceMap implementation is used.
-* `options.lineToLine` (`{test: string|RegExp|Array, include: string|RegExp|Array, exclude: string|RegExp|Array}` matched modules uses simple (faster) line to line source mappings.
+* `options.test` / `options.include` / `options.exclude` (`string|RegExp|Array`): 用来规定哪些资源应该被处理。可以是 `RegExp`（匹配资源文件名），也可以是 `string`（资源文件名的开头）或者包含以上两种的 `Array`（需要匹配其中一个），`test` 如果没有设置，默认为 `.js` 文件。
+* `options.filename` (`string`): 定义 SourceMap 输出的文件名。如果不设置，SourceMap 会放在代码文件里。
+* `options.append` (`string`): 添加到原始资源之后。通常是 `#sourceMappingURL` 注释。`[url]`会被替换成 SourceMap 文件的路径。`false` 禁用添加。
+* `options.moduleFilenameTemplate` / `options.fallbackModuleFilenameTemplate` (`string`): 查看 `output.devtoolModuleFilenameTemplate`。
+* `options.module` (`boolean`):  (默认为 `true`) 当 `false` loaders 不产生 SourceMaps 时，将转换后的代码作为源.
+* `options.columns` (`boolean`):  (默认为 `true`) 当 SourceMaps 里的 `false` column 映射 (mappings) 被忽略时，会使用一个更快的 SourceMap 实现。
+* `options.lineToLine` (`{test: string|RegExp|Array, include: string|RegExp|Array, exclude: string|RegExp|Array}` 使用简单（快速）的「行到行资源映射(line to line source mappings)」来匹配模块。
 
 ## Examples