diff --git a/docs/zh-cn/README.md b/docs/zh-cn/README.md
new file mode 100644
index 000000000..6af9d30bb
--- /dev/null
+++ b/docs/zh-cn/README.md
@@ -0,0 +1,38 @@
+# 介绍
+
+### `vue-loader` 是什么？
+
+`vue-loader` 是一个 Webpack 的 loader，可以将用下面这个格式编写的 Vue 组件转换为 JavaScript 模块：
+
+![screenshot](http://blog.evanyou.me/images/vue-component.png)
+
+这里有一些 `vue-loader` 提供的很酷的特性：
+
+- ES2015 默认支持;
+- 允许对 Vue 组件的组成部分使用其它 Webpack loaders，比如对 `<style>` 使用 SASS 和对 `<template>` 使用 Jade；
+- `.vue` 文件中允许自定义节点，然后使用自定义的 loader 处理他们；
+- 把 `<style>` 和 `<template>` 中的静态资源当作模块来对待，并使用 Webpack loaders 进行处理；
+- 对每个组件模拟出 CSS 作用域；
+- 支持开发期组件的热重载。
+
+简而言之，编写 Vue.js 应用程序时，组合使用 Webpack 和 `vue-loader` 能带来一个现代，灵活并且非常强大的前端工作流程。
+
+### Webpack 是什么?
+
+如果你已经熟悉了 Webpack，随时可以跳过下面的说明。如果你没有使用过 Webpack,下面是一个快速介绍：
+
+[Webpack](http://webpack.github.io/) 是一个模块打包工具。它将一堆文件中的每个文件都作为一个模块，找出他们的依赖关系，将它们打包为可部署的静态资源。
+
+![webpack](http://webpack.github.io/assets/what-is-webpack.png)
+
+一个基本的例子，想像我们有一些 CommonJS 模块，它不能直接在浏览器中运行，所以我们需要打包成一个文件，这样就可以通过`<script>` 标签加载。Webpack 可以遵循 `require()` 调用的依赖关系，为我们完成这些工作。
+
+但是 Webpack 可以做的不止这些。使用 "loaders"，我们可以配置 Webpack 以任何方式去转换所有类型的文件。一些例子包括：
+
+- 转换 ES2015,CoffeeScript 或者 TypeScript 模块为普通的 ES5 CommonJS 模块；
+- 可以选择在编译之前检验你的源代码；
+- 将 Jade 模版转换为纯 HTML 并且嵌入 Javascript 字符串中；
+- 将 SASS 文件转换为纯 CSS，then convert it into a JavaScript snippet that insert the resulting CSS as a `<style>` tag;
+- 处理 HTML 或者 CSS 中引用的图片，移动到配置的路径中，并且使用 md5 hash 重命名。
+
+当你理解 Webpack 原理后会感觉它是如此强大，它可以大大优化你的前端工作流程。它主要的缺点是配置复杂麻烦，但是使用本指南， Vue.js 和 `vue-loader`使用时的常见问题，应该可以帮助你找到解决方案。
diff --git a/docs/zh-cn/SUMMARY.md b/docs/zh-cn/SUMMARY.md
new file mode 100644
index 000000000..5689d977a
--- /dev/null
+++ b/docs/zh-cn/SUMMARY.md
@@ -0,0 +1,21 @@
+- 开始
+  - [Vue 组件细则](start/spec.md)
+  - [创建项目](start/setup.md)
+- 特性
+  - [ES2015](features/es2015.md)
+  - [CSS 作用域](features/scoped-css.md)
+  - [CSS 模块](features/css-modules.md)
+  - [PostCSS](features/postcss.md)
+  - [热重载](features/hot-reload.md)
+- 配置
+  - [预处理器](configurations/pre-processors.md)
+  - [处理资源路径](configurations/asset-url.md)
+  - [进阶配置](configurations/advanced.md)
+  - [提取 CSS 文件](configurations/extract-css.md)
+  - [自定义块](configurations/custom-blocks.md)
+- 工作流程
+  - [生产环境构建](workflow/production.md)
+  - [代码检验](workflow/linting.md)
+  - [测试](workflow/testing.md)
+  - [使用 Mocks 测试](workflow/testing-with-mocks.md)
+- [选项参考](options.md)
diff --git a/docs/zh-cn/configurations/advanced.md b/docs/zh-cn/configurations/advanced.md
new file mode 100644
index 000000000..3484c20e7
--- /dev/null
+++ b/docs/zh-cn/configurations/advanced.md
@@ -0,0 +1,78 @@
+# Loader 进阶配置
+
+有些时候你想要这样：
+
+1. 对语言应用自定义 loader string，而不是让 `vue-loader` 去推断；
+
+2. 覆盖默认语言的内置配置。
+
+3. 默认语言预处理或者后处理配置。
+
+为了实现这些，详细说明 `vue-loader` 的 `loaders` 选项：
+
+> 注意 `preLoaders` 和 `postLoaders` 只在版本 >=10.3.0 支持
+
+### Webpack 2.x
+
+``` js
+module.exports = {
+  // other options...
+  module: {
+    // module.rules is the same as module.loaders in 1.x
+    rules: [
+      {
+        test: /\.vue$/,
+        loader: 'vue-loader',
+        options: {
+          // `loaders` 覆盖默认 loaders.
+          // 以下配置会导致所有的 <script> 标签 "lang" 属性失效。
+          // attribute to be loaded with coffee-loader
+          loaders: {
+            js: 'coffee-loader'
+          },
+
+          // `preLoaders` 会在默认 loaders 之前加载.
+          // 你可以用来预处理语言块 - 一个例子是用来处理构建时的 i18n
+          preLoaders: {
+            js: '/path/to/custom/loader'
+          },
+
+          // `postLoaders` 会在默认 loaders 之后加载.
+          //
+          // - 对于 `html`, 默认 loader 返回会编译为 JavaScript 渲染函数
+          //
+          // - 对于 `css`, 由`vue-style-loader` 返回的结果通常不太有用。使用 postcss 插件将会是更好的选择。
+          postLoaders: {
+            html: 'babel-loader'
+          }
+        }
+      }
+    ]
+  }
+}
+```
+
+### Webpack 1.x
+
+``` js
+// webpack.config.js
+module.exports = {
+  // other options...
+  module: {
+    loaders: [
+      {
+        test: /\.vue$/,
+        loader: 'vue'
+      }
+    ]
+  },
+  // vue-loader configurations
+  vue: {
+    loaders: {
+      // same configuration rules as above
+    }
+  }
+}
+```
+
+进阶配置更实际的用法是 [提取组件中的 CSS 到单个文件](./extract-css.md)。
diff --git a/docs/zh-cn/configurations/asset-url.md b/docs/zh-cn/configurations/asset-url.md
new file mode 100644
index 000000000..3cc760abd
--- /dev/null
+++ b/docs/zh-cn/configurations/asset-url.md
@@ -0,0 +1,23 @@
+# 处理资源路径
+
+默认情况下，`vue-loader` 使用 [css-loader](https://github.com/webpack/css-loader) 和 Vue 模版编译器自动处理你的样式和模版文件。在处理过程中，所有的资源路径例如 `<img src="...">`, `background: url(...)` 和 `@import` **会作为模块依赖**。
+
+例如，`url(./image.png)` 会被转换为 `require('./image.png')`,
+
+``` html
+<img src="../image.png">
+```
+
+将会编译为：
+
+``` js
+createElement('img', { attrs: { src: require('../image.png') }})
+```
+
+因为 `.png` 不是一个 JavaScript 文件，你需要配置 Webpack 使用 [file-loader](https://github.com/webpack/file-loader) 或者 [url-loader](https://github.com/webpack/url-loader) 去处理它们。脚手器工具 `vue-cli` 已经为你配置好了。
+
+使用它们的好处：
+
+1. `file-loader` 允许你指定资源文件的位置，允许使用 hashes 命名以获得长时间的缓存。此外，这意味着 **你可以就近管理你的图片文件，可以使用相对路径而不用担心布署**。使用正确的配置，Webpack 将会在输出中自动重写为正常的文件路径。
+
+2. `url-loader` 允许你设置转换为内联 base64 的文件最小值，这会减少小文件的 HTTP 请求。如果文件大于设置值，会自动的交给 `file-loader` 处理。
diff --git a/docs/zh-cn/configurations/custom-blocks.md b/docs/zh-cn/configurations/custom-blocks.md
new file mode 100644
index 000000000..ae5edf39d
--- /dev/null
+++ b/docs/zh-cn/configurations/custom-blocks.md
@@ -0,0 +1,67 @@
+# 自定义块
+
+> 在大于 10.2.0 中支持
+
+在 `.vue` 文件中，你可以自定义语言块。自定义块将会被 `vue-loader` 选项 `loaders` 中指定的 loaders 处理，然后被组件模块依赖。配置类似 [Loader 进阶配置](../configurations/advanced.md)，除了匹配使用的是标签名称，而不是 `lang` 属性。
+
+如果 loader 匹配到自定义块，它会被处理；其它情况会被忽略。
+
+## 例子
+
+这个例子是提取自定义块 `<docs>` 的内容到单个 docs 文件中：
+
+#### component.vue
+
+``` html
+<docs>
+## This is an Example component.
+</docs>
+
+<template>
+  <h2 class="red">{{msg}}</h2>
+</template>
+
+<script>
+export default {
+  data () {
+    return {
+      msg: 'Hello from Component A!'
+    }
+  }
+}
+</script>
+
+<style>
+comp-a h2 {
+  color: #f00;
+}
+</style>
+```
+
+#### webpack.config.js
+
+``` js
+// Webpack 2.x
+var ExtractTextPlugin = require("extract-text-webpack-plugin")
+
+module.exports = {
+  module: {
+    rules: [
+      {
+        test: /\.vue$/,
+        loader: 'vue',
+        options: {
+          loaders: {
+            // 提取 <docs> 中的内容为原始文本
+            'docs': ExtractTextPlugin.extract('raw-loader'),
+          }
+        }
+      }
+    ]
+  },
+  plugins: [
+    // 输出 docs 到当个文件中
+    new ExtractTextPlugin('docs.md')
+  ]
+}
+```
diff --git a/docs/zh-cn/configurations/extract-css.md b/docs/zh-cn/configurations/extract-css.md
new file mode 100644
index 000000000..796dfcfba
--- /dev/null
+++ b/docs/zh-cn/configurations/extract-css.md
@@ -0,0 +1,70 @@
+# 提取 CSS 到单个文件
+
+提取所有 Vue 组件中的 CSS 到单个文件的例子：
+
+### Webpack 2.x
+
+``` bash
+npm install extract-text-webpack-plugin@2.x --save-dev
+```
+
+``` js
+// webpack.config.js
+var ExtractTextPlugin = require("extract-text-webpack-plugin")
+
+module.exports = {
+  // other options...
+  module: {
+    rules: [
+      {
+        test: /\.vue$/,
+        loader: 'vue-loader',
+        options: {
+          loaders: {
+            css: ExtractTextPlugin.extract({
+              use: 'css-loader',
+              fallback: 'vue-style-loader' // <- this is a dep of vue-loader, so no need to explicitly install if using npm3
+            })
+          }
+        }
+      }
+    ]
+  },
+  plugins: [
+    new ExtractTextPlugin("style.css")
+  ]
+}
+```
+
+### Webpack 1.x
+
+``` bash
+npm install extract-text-webpack-plugin --save-dev
+```
+
+``` js
+// webpack.config.js
+var ExtractTextPlugin = require("extract-text-webpack-plugin")
+
+module.exports = {
+  // other options...
+  module: {
+    loaders: [
+      {
+        test: /\.vue$/,
+        loader: 'vue'
+      },
+    ]
+  },
+  vue: {
+    loaders: {
+      css: ExtractTextPlugin.extract("css"),
+      // you can also include <style lang="less"> or other langauges
+      less: ExtractTextPlugin.extract("css!less")
+    }
+  },
+  plugins: [
+    new ExtractTextPlugin("style.css")
+  ]
+}
+```
diff --git a/docs/zh-cn/configurations/pre-processors.md b/docs/zh-cn/configurations/pre-processors.md
new file mode 100644
index 000000000..d3779403c
--- /dev/null
+++ b/docs/zh-cn/configurations/pre-processors.md
@@ -0,0 +1,81 @@
+# 使用预处理器
+
+在 Webpack 中，所有的预处理器需要匹配对应的 loader。 `vue-loader` 允许你使用其它 Webpack loaders 处理 Vue 组件的某一部分。它会根据 `lang` 属性自动推断出要使用的 loaders。
+
+### CSS
+
+例如，使用 SASS 编译我们的 `<style>` 语言块：
+
+``` bash
+npm install sass-loader node-sass --save-dev
+```
+
+``` html
+<style lang="sass">
+  /* write sass here */
+</style>
+```
+
+在内部，`<style>` 标签中的内容将会先由 `sass-loader` 进行处理，然后再传递进行下一步处理。
+
+#### sass-loader 警告
+
+与名称相反，[*sass*-loader](https://github.com/jtangelder/sass-loader) 默认解析 *SCSS* 语法。如果你想要使用 *SASS* 语法，你需要配置 `vue-loader` 的选项：
+
+```javascript
+{
+  test: /\.vue$/,
+  loader: 'vue-loader',
+  options: {
+    loaders: {
+      scss: 'vue-style-loader!css-loader!sass-loader', // <style lang="scss">
+      sass: 'vue-style-loader!css-loader!sass-loader?indentedSyntax' // <style lang="sass">
+    }
+  }
+}
+```
+
+如要获得更多关于 `vue-loader` 的配置信息，请查看 [Loader 进阶配置](./advanced.md) 章节。
+
+### JavaScript
+
+Vue 组件中的所有 JavaScript 默认使用 `babel-loader` 处理。你也可以改变处理方式：
+
+``` bash
+npm install coffee-loader --save-dev
+```
+
+``` html
+<script lang="coffee">
+  # Write coffeescript!
+</script>
+```
+
+### 模版
+
+模版的处理方式略有不同，因为大多数 Webpack 模版处理器（比如 `pug-loader`）会返回模版处理函数，而不是编译的 HTML 字符串，我们使用原始的 `pug` 替代 `pug-loader`:
+
+``` bash
+npm install pug --save-dev
+```
+
+``` html
+<template lang="pug">
+div
+  h1 Hello world!
+</template>
+```
+
+> **重要:** 如果你使用 `vue-loader@<8.2.0`， 你还需要安装 `template-html-loader`。
+
+### 行内 Loader Requests
+
+你可以在 `lang` 属性中使用 [Webpack loader requests](https://webpack.github.io/docs/loaders.html#introduction) ：
+
+``` html
+<style lang="sass?outputStyle=expanded">
+  /* use sass here with expanded output */
+</style>
+```
+
+但是，这使你的 Vue 组件只适用于 Webpack，不能与 Browserify and [vueify](https://github.com/vuejs/vueify) 一同使用。**如果你打算将你的 Vue 组件作为可重复使用的第三方组件，请避免使用这个语法。**
diff --git a/docs/zh-cn/features/css-modules.md b/docs/zh-cn/features/css-modules.md
new file mode 100644
index 000000000..043213e44
--- /dev/null
+++ b/docs/zh-cn/features/css-modules.md
@@ -0,0 +1,117 @@
+# CSS 模块
+
+> 需要 ^9.8.0
+
+[CSS 模块](https://github.com/css-modules/css-modules) 是一个用于模块化和组合 CSS的流行系统。`vue-loader` 提供了与 CSS 模块的一流集成，可以作为模拟 CSS 作用域的替代方案。
+
+### 使用
+
+在你的 `<style>` 上添加 `module` 属性：
+
+``` html
+<style module>
+.red {
+  color: red;
+}
+.bold {
+  font-weight: bold;
+}
+</style>
+```
+
+这将为 `css-loader` 打开 CSS 模块模式，生成的 CSS 对象将为组件注入一个名叫 `$style` 的计算属性，你可以在你的模块中使用动态绑定：
+
+``` html
+<template>
+  <p :class="$style.red">
+    This should be red
+  </p>
+</template>
+```
+
+由于它是一个计算属性，它也与 `：class` 的 object/array 语法一起使用：
+
+``` html
+<template>
+  <div>
+    <p :class="{ [$style.red]: isRed }">
+      Am I red?
+    </p>
+    <p :class="[$style.red, $style.bold]">
+      Red and bold
+    </p>
+  </div>
+</template>
+```
+
+你也可以在 JavaScript 访问它：
+
+``` html
+<script>
+export default {
+  created () {
+    console.log(this.$style.red)
+    // -> "_1VyoJ-uZOjlOxP7jWUy19_0"
+    // an identifier generated based on filename and className.
+  }
+}
+</script>
+```
+
+请参考 [CSS Modules spec](https://github.com/css-modules/css-modules) 了解更多详细信息 [global exceptions](https://github.com/css-modules/css-modules#exceptions) 和 [composition](https://github.com/css-modules/css-modules#composition).
+
+### 自定义注入名称
+
+在 `.vue` 中你可以定义不止一个 `<style>`，为了避免被覆盖，你可以通过设置 `module` 属性来为它们定义注入后计算属性的名称。
+
+``` html
+<style module="a">
+  /* identifiers injected as a */
+</style>
+
+<style module="b">
+  /* identifiers injected as b */
+</style>
+```
+
+### 配置 `css-loader` Query
+
+CSS 模块处理是通过 [css-loader](https://github.com/webpack/css-loader)。默认 query 如下：
+
+``` js
+{
+  modules: true,
+  importLoaders: true,
+  localIdentName: '[hash:base64]'
+}
+```
+
+你可以使用 `vue-loader` 的 `cssModules` 选项去为 `css-loader` 添加 query 配置：
+
+``` js
+// webpack 1
+vue: {
+  cssModules: {
+    // overwrite local ident name
+    localIdentName: '[path][name]---[local]---[hash:base64:5]',
+    // enable camelCase
+    camelCase: true
+  }
+}
+
+// webpack 2
+module: {
+  rules: [
+    {
+      test: '\.vue$',
+      loader: 'vue-loader',
+      options: {
+        cssModules: {
+          localIdentName: '[path][name]---[local]---[hash:base64:5]',
+          camelCase: true
+        }
+      }
+    }
+  ]
+}
+```
diff --git a/docs/zh-cn/features/es2015.md b/docs/zh-cn/features/es2015.md
new file mode 100644
index 000000000..16f54345a
--- /dev/null
+++ b/docs/zh-cn/features/es2015.md
@@ -0,0 +1,65 @@
+# ES2015
+
+当项目中配置了 `babel-loader` 或者 `buble-loader`，`vue-loader` 会使用他们处理所有 `.vue` 文件中的 `<script>` 部分，允许我们在 Vue 组件中使用 ES2015，如果你还没有使用 ES2015，你应该使用它，下面是一些好的学习资源：
+
+- [Babel - Learn ES2015](https://babeljs.io/docs/learn-es2015/)
+- [ES6 Features](https://github.com/lukehoban/es6features)
+- [Exploring ES6 (book)](https://leanpub.com/exploring-es6)
+
+下面是导入其它 Vue 组件的典型写法：
+
+``` html
+<script>
+import ComponentA from './ComponentA.vue'
+import ComponentB from './ComponentB.vue'
+
+export default {
+  components: {
+    ComponentA,
+    ComponentB
+  }
+}
+</script>
+```
+
+我们使用 ES2015 的属性的简洁表示法去定义子组件，`{ ComponentA }` 是 `{ ComponentA: ComponentA }` 的简写，Vue 会自动的将 key 转换为`component-a`，所以你可以在 template 中使用 `<component-a>`.
+
+### 在 Templates 中使用 ES2015
+
+`.vue` 中的 `<template>` 会编译为 JavaScript 渲染函数，然后通过自定义构建的 [Buble](https://buble.surge.sh/guide/) 去支持 ES2015，这允许你使用[属性的简洁表示法](https://buble.surge.sh/guide/#object-shorthand-methods-and-properties-transforms-concisemethodproperty-) 和 [属性名表达式](https://buble.surge.sh/guide/#computed-properties-transforms-computedproperty-)：
+
+``` html
+<div :class="[{ active: active }, isButton ? prefix + '-button' : null]">
+```
+
+可以简写为：
+
+``` html
+<div :class="{ active, [`${prefix}-button`]: isButton }">
+```
+
+**vue@^2.1.0 only:** 你可以在 `v-for` 或者 scoped slots 中使用解构赋值：
+
+``` html
+<li v-for="{ id, text } in items">
+  {{ id }} {{ text }}
+</li>
+```
+
+``` html
+<my-component>
+  <template scope="{ id, text }">
+    <span>{{ id }} {{ text }}</span>
+  </template>
+</my-component>
+```
+
+你还可以使用[`buble` 选项]（../ options.md＃buble）自定义模板中支持的功能。
+
+### 转换普通 `.js` 文件
+
+由于 `vue-loader` 只处理 `.vue` 文件，你需要告诉 Webpack 如何使用 `babel-loader` 或者 `buble-loader` 处理普通 `.js` 文件，在 Webpakc 中配置 `babel-loader`或者 `buble-loader`。脚手架工具 `vue-cli` 已经为你做了这些。
+
+### 使用 `.babelrc` 配置 Babel
+
+`babel-loader` 遵守 [`.babelrc`](https://babeljs.io/docs/usage/babelrc/)，因此这是推荐配置 Babel presets 和插件的方法。
diff --git a/docs/zh-cn/features/hot-reload.md b/docs/zh-cn/features/hot-reload.md
new file mode 100644
index 000000000..7d8df900a
--- /dev/null
+++ b/docs/zh-cn/features/hot-reload.md
@@ -0,0 +1,7 @@
+# 热重载
+
+"热重载"不是当你修改文件的时候简单重新加载页面。启用热重载后，当你修改 `.vue` 文件时，所有该组件的实例会被替换，**并且不需要刷新页面**。它甚至保持应用程序和修改组件的当前状态！当你调整模版或者修改样式时，这极大的提高了开发体验。
+
+![hot-reload](http://blog.evanyou.me/images/vue-hot.gif)
+
+当使用脚手架工具 `vue-cli` 时，热重载是开箱即用的。
\ No newline at end of file
diff --git a/docs/zh-cn/features/postcss.md b/docs/zh-cn/features/postcss.md
new file mode 100644
index 000000000..77273d9c5
--- /dev/null
+++ b/docs/zh-cn/features/postcss.md
@@ -0,0 +1,68 @@
+# PostCSS
+
+由`vue-loader` 处理的 CSS 输出，都是通过 [PostCSS](https://github.com/postcss/postcss) 进行作用域重写，你还可以为 PostCSS 添加自定义插件，例如 [autoprefixer](https://github.com/postcss/autoprefixer) 或者 [CSSNext](http://cssnext.io/)。
+
+## 使用配置文件
+
+`vue-loader` 从 11.0 版本开始支持通过 [`postcss-loader`](https://github.com/postcss/postcss-loader#usage) 自动加载同一个配置文件：
+
+- `postcss.config.js`
+- `.postcssrc`
+- `package.json` 中的 `postcss`
+
+使用配置文件允许一份配置用于处理普通 CSS 文件(通过`postcss-loader`)，和 `.vue` 文件内的 CSS，这是推荐做法。
+
+## 内联选项
+
+或者，你可以使用 `vue-loader` 的 `postcss` 选项来为 `.vue` 文件指定配置。
+
+Webpack 1.x 例子：
+
+``` js
+// webpack.config.js
+module.exports = {
+  // other configs...
+  vue: {
+    // use custom postcss plugins
+    postcss: [require('postcss-cssnext')()]
+  }
+}
+```
+
+Webpack 2.x 例子:
+
+``` js
+// webpack.config.js
+module.exports = {
+  // other options...
+  module: {
+    // module.rules is the same as module.loaders in 1.x
+    rules: [
+      {
+        test: /\.vue$/,
+        loader: 'vue-loader',
+        // vue-loader options goes here
+        options: {
+          // ...
+          postcss: [require('postcss-cssnext')()]
+        }
+      }
+    ]
+  }
+}
+```
+
+除了插件数组之外，`postcss` 配置选项也接受：
+
+- 一个返回插件数组的函数；
+
+- 一个对象包含配置选项，传递给 PostCSS 处理器。这在使用自定义 parser/stringifiers 时非常有用:
+
+  ``` js
+  postcss: {
+    plugins: [...], // list of plugins
+    options: {
+      parser: sugarss // use sugarss parser
+    }
+  }
+  ```
diff --git a/docs/zh-cn/features/scoped-css.md b/docs/zh-cn/features/scoped-css.md
new file mode 100644
index 000000000..f2fe4fc29
--- /dev/null
+++ b/docs/zh-cn/features/scoped-css.md
@@ -0,0 +1,52 @@
+# CSS 作用域
+
+当 `<style>` 标签有 `scoped` 属性时，它的 CSS 只作用于当前组件中的元素。 这类似于 Shadow DOM 中的样式封装。它有一些注意事项，但不需要任何 polyfills。 它通过使用 PostCSS 来实现以下转换：
+
+``` html
+<style scoped>
+.example {
+  color: red;
+}
+</style>
+
+<template>
+  <div class="example">hi</div>
+</template>
+```
+
+转换结果：
+
+``` html
+<style>
+.example[_v-f3f3eg9] {
+  color: red;
+}
+</style>
+
+<template>
+  <div class="example" _v-f3f3eg9>hi</div>
+</template>
+```
+
+#### 注意
+
+1. 你可以在一个组件中同时使用 scoped 和 non-scoped styles
+
+  ``` html
+  <style>
+  /* global styles */
+  </style>
+
+  <style scoped>
+  /* local styles */
+  </style>
+  ```
+
+2. 子组件的根节点将同时受父组件作用域和子组件作用域的影响。
+
+3. 部分元素不受作用域影响部分。
+
+4. **CSS 作用域不能代C替 classes**。考虑到浏览器渲染各种 CSS 选择器的方式，`p { color: red }` 在作用域中会慢很多(即转换为属性选择器)。如果你使用 classes 或者 ids 代替，比如 `.example { color: red }`，这样几乎没有性能影响。[Here's a playground](http://stevesouders.com/efws/css-selectors/csscreate.php) 你可以测试它们的不同。
+
+5. **在递归组件中小心使用后代选择器!** 对于带有选择器 `.a .b` 的CSS 规则，如果元素 `.a` 包含递归子组件，所有的子组件中的 `.b` 会被匹配。
+
diff --git a/docs/zh-cn/options.md b/docs/zh-cn/options.md
new file mode 100644
index 000000000..d9c5e6081
--- /dev/null
+++ b/docs/zh-cn/options.md
@@ -0,0 +1,190 @@
+# 配置文档
+
+## Webpack 1 和 2 配置差异
+
+Webpack 2：配置直接放到 loader rule 中。
+
+``` js
+module.exports = {
+  // ...
+  module: {
+    rules: [
+      {
+        test: /\.vue$/,
+        loader: 'vue-loader',
+        options: {
+          // vue-loader options
+        }
+      }
+    ]
+  }
+}
+```
+
+Webpack 1.x：在 Webpack 配置中添加根节点 `vue` 块。
+
+``` js
+module.exports = {
+  // ...
+  vue: {
+    // vue-loader options
+  }
+}
+```
+
+### loaders
+
+- 类型： `{ [lang: string]: string }`
+
+  如果指定 Webpack loaders 会覆盖 ` .vue` 文件中的语言块的默认 `lang` 属性。 每种类型的默认 `lang` 是：
+  An object specifying Webpack loaders to overwrite the default loaders used for language blocks inside `*.vue` files. The key corresponds to the `lang` attribute for language blocks, if specified. The default `lang` for each type is:
+
+  - `<template>`: `html`
+  - `<script>`: `js`
+  - `<style>`: `css`
+
+  例如，使用 `babel-loader` 和 `eslint-loader` 处理所有的 `<script>` 块：
+
+  ``` js
+  // Webpack 2.x config
+  module: {
+    rules: [
+      {
+        test: /\.vue$/,
+        loader: 'vue-loader',
+        options: {
+          loaders: {
+            js: 'babel-loader!eslint-loader'
+          }
+        }
+      }
+    ]
+  }
+  ```
+
+### preLoaders
+
+- 类型： `{ [lang: string]: string }`
+- 在大于 >=10.3.0 版本中支持
+
+  配置格式和 `loaders` 相同，但是 `preLoaders` 会在默认 loaders 之前处理。你可以用来预处理语言块 - 一个例子是用来处理构建时的 i18n。
+  
+### postLoaders
+
+- 类型： `{ [lang: string]: string }`
+- 在大于 >=10.3.0 版本中支持
+
+  配置格式和 `loaders` 相同，但是 `postLoaders` 会在默认 loaders 之后处理。你可以用来后处理语言块。注意这会有些复杂：
+
+  - 对于 `html`,默认 loader 返回结果会被编译为 JavaScript 渲染函数。
+
+  - 对于 `css`，由`vue-style-loader` 返回的结果通常不太有用。使用 postcss 插件将会是更好的选择。
+
+### postcss
+
+> 注意： 在 >=11.0.0 版本中，推荐使用 PostCSS 配置文件代替. [The usage is the same as `postcss-loader`](https://github.com/postcss/postcss-loader#usage).
+
+- 类型： `Array` or `Function` or `Object`
+
+
+  指定要应用于 `.vue` 文件中 CSS 的自定义 PostCSS 插件。如果使用函数，函数将使用相同的 loader 上下文调用，并返回一个插件数组。
+
+  ``` js
+  // ...
+  {
+    loader: 'vue-loader',
+    options: {
+      // note: do not nest the `postcss` option under `loaders`
+      postcss: [require('postcss-cssnext')()],
+      loaders: {
+        // ...
+      }
+    }
+  }
+  ```
+
+  这个配置选项也可以是一个对象，这在使用依赖于自定义 parser/stringifiers 的项目会非常有用：
+
+  ``` js
+  postcss: {
+    plugins: [...], // list of plugins
+    options: {
+      parser: sugarss // use sugarss parser
+    }
+  }
+  ```
+
+### cssSourceMap
+
+- 类型: `Boolean`
+- 默认值: `true`
+
+  是否开启 CSS 的 source maps，关闭可以避免 `css-loader` 的 some relative path related bugs 同时可以加快构建速度。
+
+  注意，这个值会在 Webpack 配置中没有 `devtool` 的情况下自动设置为 `false`。
+
+### esModule
+
+- 类型: `Boolean`
+- 默认值: `undefined`
+
+  是否导出 esModule 兼容代码，默认情况下 vue-loader 会导出 commonjs 格式，像 `module.exports = ....`。当 `esModule` 设置为 true 的情况下，导出会变为 `exports.__esModule = true; exports = ...`。Useful for interoperating with transpiler other than Babel，比如 TypeScript。
+
+### preserveWhitespace
+
+- 类型: `Boolean`
+- 默认值: `true`
+
+  如果设置为 `false`，模版中 HTML 标签之前的空格将会被忽略。
+
+### transformToRequire
+
+- 类型: `{ [tag: string]: string | Array<string> }`
+- 默认值: `{ img: 'src', image: 'xlink:href' }`
+
+  在模版编译过程中，编译器可以将某些属性，如 `src` 路径，转换为 `require` 调用，以便目标资源可以由 Webpack 处理。 默认配置会转换 `<img>` 标签上的 `src` 属性和 SVG 的 `<image>` 标签上的 `xlink：href` 属性。
+
+### buble
+
+- 类型: `Object`
+- 默认值: `{}`
+
+  在使用 `buble-loader` 时配置它的选项，AND the buble compilation pass for template render functions。
+
+  > 版本警告：在 9.x 版本中，模板表达式通过现在已经删除的 `templateBuble` 选项单独配置。
+
+
+  模板渲染函数编译支持一个特殊的变换 `stripWith`（默认启用），它删除生成的渲染函数中的 `with` 用法，使它们兼容严格模式。
+
+  配置例子：
+
+  ``` js
+  // webpack 1
+  vue: {
+    buble: {
+      // enable object spread operator
+      // NOTE: you need to provide Object.assign polyfill yourself!
+      objectAssign: 'Object.assign',
+
+      // turn off the `with` removal
+      transforms: {
+        stripWith: false
+      }
+    }
+  }
+
+  // webpack 2
+  module: {
+    rules: [
+      {
+        test: /\.vue$/,
+        loader: 'vue-loader',
+        options: {
+          buble: {
+            // same options
+          }
+        }
+      }
+    ]
+  }
+  ```
diff --git a/docs/zh-cn/start/setup.md b/docs/zh-cn/start/setup.md
new file mode 100644
index 000000000..97474524f
--- /dev/null
+++ b/docs/zh-cn/start/setup.md
@@ -0,0 +1,13 @@
+# 创建项目
+
+### 使用 `vue-cli`
+
+推荐用脚手架工具 `vue-cli` 来创建一个使用 `vue-loader` 的项目：
+
+``` bash
+npm install -g vue-cli
+vue init webpack-simple hello-vue
+cd hello-vue
+npm install
+npm run dev # ready to go!
+```
diff --git a/docs/zh-cn/start/spec.md b/docs/zh-cn/start/spec.md
new file mode 100644
index 000000000..4de8776d2
--- /dev/null
+++ b/docs/zh-cn/start/spec.md
@@ -0,0 +1,112 @@
+# Vue 组件细则
+
+`.vue` 文件是一个自定义的文件类型,用类 HTML 语法描述一个 Vue 组件。每个 `.vue` 文件包含三种类型的顶级语言块 `<template>`, `<script>` 和 `<style>`，还允许添加可选的自定义块：
+
+``` html
+<template>
+  <div class="example">{{ msg }}</div>
+</template>
+
+<script>
+export default {
+  data () {
+    return {
+      msg: 'Hello world!'
+    }
+  }
+}
+</script>
+
+<style>
+.example {
+  color: red;
+}
+</style>
+
+<custom1>
+  This could be e.g. documentation for the component.
+</custom1>
+```
+
+`vue-loader` 会解析文件，提取每个语言块，如有必要会通过其它 loaders 处理，最后将他们组装成一个 CommonJS 模块，`module.exports` 出一个 Vue.js 组件对象。
+
+`vue-loader` 支持使用非默认放言，比如 CSS 预处理器，预编译的 HTML 模版语言，通过设置语言块的 `lang` 属性。例如，你可以像下面这样使用 SASS 语法编写 style： 
+
+``` html
+<style lang="sass">
+  /* write SASS! */
+</style>
+```
+
+更多细节可以在 [预处理器](../configurations/pre-processors.md) 中找到。
+
+### 语言块
+
+#### `<template>`
+
+- 默认语言：`html`。
+
+- 每个 `.vue` 文件最多包含一个 `<template>` 块
+
+- 内容将被提取为字符串，将编译并用作 Vue 组件的 `template` 选项。
+
+#### `<script>`
+
+- 默认语言：`js` (ES2015 在检测到配置 `babel-loader` 或 `buble-loader` 时自动支持).
+
+- 每个 `.vue` 文件最多包含一个 `<script>` 块
+
+- script 在 CommonJS 环境中执行（就像通过 Webpack 打包的正常 js 模块），这意味这你可以 `require()` 其它依赖。在 ES2015 在支持下,你也可以使用 `import` 和 `export` 语法。
+
+- script 必须导出 Vue.js 组件对象。也可以导出由 `Vue.extend()` 创建的扩展对象，但是普通对象是最好的选择。
+
+#### `<style>`
+
+- 默认语言： `css`。
+
+- 一个 `.vue` 文件可以包含多个 `<style>` 标签。
+
+- `<style>` 标签可以有 `scoped` 或者 `module` 属性 (查看 [CSS 作用域](../features/scoped-css.md) 和 [CSS 模块](../features/css-modules.md)) 以帮助你将样式封装到当前组件。多个不同封装的 `<style>` 标签将会混合在一个组件中。
+
+- 默认情况下内容将会使用 `style-loader` 提取并通过 `<style>` 标签动态加入文档的 `<head>` 中，也可以[配置 Webpack 将所有 styles 提取到单个 CSS 文件中](../configurations/extract-css.md).
+
+### 自定义块
+
+> 只在 vue-loader 10.2.0+ 中支持
+
+可以在 `.vue` 文件中填加额外的自定义块来实现项目的特定需求，例如 `<docs>` 块。`vue-loader` 将会使用标签名来查找对应的 webpack loaders 来应用在对应的块上。webpack loaders 需要在 `vue-loader` 的选项 `loaders` 中指定。
+
+更多细节，查看 [自定义块](../configurations/custom-blocks.md)。
+
+### Src 导入
+
+如果你喜欢分隔你的 `.vue` 文件到多个文件中，你可以通过 `src` 属性导入外部文件：
+
+``` html
+<template src="./template.html"></template>
+<style src="./style.css"></style>
+<script src="./script.js"></script>
+```
+
+需要注意的是 `src` 导入遵循和 `require()` 一样的规则，这意味着你相对路径需要以 `./` 开始，你还可以从 NPM 包中直接导入资源，例如：
+
+``` html
+<!-- import a file from the installed "todomvc-app-css" npm package -->
+<style src="todomvc-app-css/index.css">
+```
+
+在自定义块上同样支持 `src` 导入，例如：
+
+``` html
+<unit-test src="./unit-test.js">
+</unit-test>
+```
+
+### 语法高亮
+
+
+目前语法高亮支持 [Sublime Text](https://github.com/vuejs/vue-syntax-highlight), [Atom](https://atom.io/packages/language-vue), [Vim](https://github.com/posva/vim-vue), [Visual Studio Code](https://marketplace.visualstudio.com/items/liuji-jim.vue), [Brackets](https://github.com/pandao/brackets-vue), and [JetBrains products](https://plugins.jetbrains.com/plugin/8057) (WebStorm, PhpStorm, 等)。 对其他编辑器/IDEs 的贡献将会非常感谢！如果在 Vue 组件中没有使用任何预处理器，你可以把 `.vue` 文件当作HTML对待。
+
+### 注释
+
+在语言块中使用该语言块对应的注释语法（HTML, CSS, JavaScript, Jade, 等）。顶层注释使用 HTML 注释语法：`<!-- comment contents here -->`
diff --git a/docs/zh-cn/workflow/linting.md b/docs/zh-cn/workflow/linting.md
new file mode 100644
index 000000000..339fd11a7
--- /dev/null
+++ b/docs/zh-cn/workflow/linting.md
@@ -0,0 +1,92 @@
+# 代码检验
+
+你可能有疑问，在 `.vue` 文件中你怎么检验你的代码，因为它不是 Javascript。我们假设你使用 [ESLint](http://eslint.org/) (如果你没有使用话，你应该去使用！)。
+
+你还需要 [eslint-plugin-html](https://github.com/BenoitZugmeyer/eslint-plugin-html) 来支持提取并检验你的 `.vue` 文件中的 JavaScript。
+
+确保把下面的配置加入到你的 ESLint 配置中：
+``` json
+"plugins": [
+  "html"
+]
+```
+
+在命令行这样使用：
+
+``` bash
+eslint --ext js,vue MyComponent.vue
+```
+
+别一种方法是使用 [eslint-loader](https://github.com/MoOx/eslint-loader),这样你的 `.vue` 文件会在开发期间每次保存时自动检验。
+
+``` bash
+npm install eslint eslint-loader --save-dev
+```
+
+``` js
+// webpack.config.js
+module.exports = {
+  // ... other options
+  module: {
+    loaders: [
+      {
+        test: /.vue$/,
+        loader: 'vue!eslint'
+      }
+    ]
+  }
+}
+```
+
+注意 Webpack loader 处理顺序是 **从右到左**。确保在 `vue` 之前应用 `eslint`，这样才能检验编译前的代码。
+
+我们需要考虑使用的 NPM 包中的第三方 `.vue` 组件，实际使用中我们希望使用 `vue-loader` 去处理第三方组件，但是不想检验它们。我们需要把 linting 配置到 Webpack's [preLoaders](https://webpack.github.io/docs/loaders.html#loader-order)中：
+
+``` js
+// webpack.config.js
+module.exports = {
+  // ... other options
+  module: {
+    // only lint local *.vue files
+    preLoaders: [
+      {
+        test: /.vue$/,
+        loader: 'eslint',
+        exclude: /node_modules/
+      }
+    ],
+    // but use vue-loader for all *.vue files
+    loaders: [
+      {
+        test: /.vue$/,
+        loader: 'vue'
+      }
+    ]
+  }
+}
+```
+
+For Webpack 2.x:
+
+``` js
+// webpack.config.js
+module.exports = {
+  // ... other options
+  module: {
+    rules: [
+      // only lint local *.vue files
+      {
+        enforce: 'pre',
+        test: /.vue$/,
+        loader: 'eslint-loader',
+        exclude: /node_modules/
+      },
+      // but use vue-loader for all *.vue files
+      {
+        test: /.vue$/,
+        loader: 'vue-loader'
+      }
+    ]
+  }
+}
+```
diff --git a/docs/zh-cn/workflow/production.md b/docs/zh-cn/workflow/production.md
new file mode 100644
index 000000000..665c2f9bc
--- /dev/null
+++ b/docs/zh-cn/workflow/production.md
@@ -0,0 +1,39 @@
+# 生产环境构建
+
+生产环境打包要做两件事：
+
+1. 缩小软件代码；
+2. 使用 [Vue.js 指南 - 删除警告](https://cn.vuejs.org/v2/guide/deployment.html#删除警告) 去除 Vue.js 中的警告。
+
+下面是例子：
+
+``` js
+// webpack.config.js
+module.exports = {
+  // ... other options
+  plugins: [
+    // short-circuits all Vue.js warning code
+    new webpack.DefinePlugin({
+      'process.env': {
+        NODE_ENV: '"production"'
+      }
+    }),
+    // minify with dead-code elimination
+    new webpack.optimize.UglifyJsPlugin({
+      compress: {
+        warnings: false
+      }
+    }),
+    // optimize module ids by occurrence count
+    new webpack.optimize.OccurrenceOrderPlugin()
+  ]
+}
+```
+
+显然我们不会想在开发时使用这些配置，有几种方式来实现：
+
+1. 使用环境变量动态构建；
+
+2. 或者，使用两个分开的 Webpack 配置文件，一个用于开发环境，一个用于生产环境。把可能共用的配置放到第三个文件中，如 [vue-hackernews-2.0](https://github.com/vuejs/vue-hackernews-2.0) 所示。
+
+只要达到目标，怎么做取决于你。
diff --git a/docs/zh-cn/workflow/testing-with-mocks.md b/docs/zh-cn/workflow/testing-with-mocks.md
new file mode 100644
index 000000000..b1a17838f
--- /dev/null
+++ b/docs/zh-cn/workflow/testing-with-mocks.md
@@ -0,0 +1,70 @@
+# Testing with Mocks
+
+In a real world application, our components most likely have external dependencies. When writing unit tests for components, it would be ideal if we can mock these external dependencies so that our tests only rely the behavior of the component being tested.
+
+`vue-loader` provides a feature that allows you to inject arbitrary dependencies to a `*.vue` component, using [inject-loader](https://github.com/plasticine/inject-loader). The general idea is that instead of directly importing the component module, we use `inject-loader` to create a "module factory" function for that module. When this function gets called with an object of mocks, it returns an instance of the module with the mocks injected.
+
+Suppose we have a component like this:
+
+``` html
+<!-- example.vue -->
+<template>
+  <div class="msg">{{ msg }}</div>
+</template>
+
+<script>
+// this dependency needs to be mocked
+import SomeService from '../service'
+
+export default {
+  data () {
+    return {
+      msg: SomeService.msg
+    }
+  }
+}
+</script>
+```
+
+Here's how to import it with mocks:
+
+> Note: inject-loader@3.x is currently unstable.
+
+``` bash
+npm install inject-loader@^2.0.0 --save-dev
+```
+
+``` js
+// example.spec.js
+const ExampleInjector = require('!!vue?inject!./example.vue')
+```
+
+Notice that crazy require string - we are using some inline [webpack loader requests](https://webpack.github.io/docs/loaders.html) here. A quick explanation:
+
+- `!!` at the start means "disable all loaders from the global config";
+- `vue?inject!` means "use the `vue` loader, and pass in the `?inject` query". This tells `vue-loader` to compile the component in dependency-injection mode.
+
+The returned `ExampleInjector` is a factory function that can be called to create instances of the `example.vue` module:
+
+``` js
+const ExampleWithMocks = ExampleInjector({
+  // mock it
+  '../service': {
+    msg: 'Hello from a mocked service!'
+  }
+})
+```
+
+Finally, we can test the component like usual:
+
+``` js
+it('should render', () => {
+  const vm = new Vue({
+    template: '<div><test></test></div>',
+    components: {
+      'test': ExampleWithMocks
+    }
+  }).$mount()
+  expect(vm.$el.querySelector('.msg').textContent).toBe('Hello from a mocked service!')
+})
+```
diff --git a/docs/zh-cn/workflow/testing.md b/docs/zh-cn/workflow/testing.md
new file mode 100644
index 000000000..03c0a64c5
--- /dev/null
+++ b/docs/zh-cn/workflow/testing.md
@@ -0,0 +1,101 @@
+# Testing
+
+> The [webpack vue-cli template](https://github.com/vuejs-templates/webpack) offers pre-configured unit testing and e2e testing setups for you.
+
+When testing `*.vue` files, we cannot use a plain CommonJS-based test runner because it won't know how to handle `*.vue` files. Instead, we still use Webpack + vue-loader to bundle our test files. The recommended setup is using [Karma](http://karma-runner.github.io/0.13/index.html) and [karma-webpack](https://github.com/webpack/karma-webpack).
+
+Karma is a test runner that launches browsers and runs your tests for you. You can choose what browsers you want to test in and what test framework (e.g. Mocha or Jasmine) you want to use. Here is an example Karma configuration that runs the tests inside [PhantomJS](http://phantomjs.org/) with the [Jasmine](http://jasmine.github.io/edge/introduction.html) test framework:
+
+``` bash
+npm install\
+  karma karma-webpack\
+  karma-jasmine jasmine-core\
+  karma-phantomjs-launcher phantomjs\
+  --save-dev
+```
+
+``` js
+// we can just use the exact same webpack config by requiring it
+// however, remember to delete the original entry since we don't
+// need it during tests
+var webpackConfig = require('./webpack.config.js')
+delete webpackConfig.entry
+
+// karma.conf.js
+module.exports = function (config) {
+  config.set({
+    browsers: ['PhantomJS'],
+    frameworks: ['jasmine'],
+    // this is the entry file for all our tests.
+    files: ['test/index.js'],
+    // we will pass the entry file to webpack for bundling.
+    preprocessors: {
+      'test/index.js': ['webpack']
+    },
+    // use the webpack config
+    webpack: webpackConfig,
+    // avoid walls of useless text
+    webpackMiddleware: {
+      noInfo: true
+    },
+    singleRun: true
+  })
+}
+```
+
+And for the entry `test/index.js` file:
+
+``` js
+// test/index.js
+// require all test files using special Webpack feature
+// https://webpack.github.io/docs/context.html#require-context
+var testsContext = require.context('.', true, /\.spec$/)
+testsContext.keys().forEach(testsContext)
+```
+
+This entry file simply requires all other files that ends in `.spec.js` in the same folder. Now we can actually write some tests:
+
+``` js
+// test/component-a.spec.js
+var Vue = require('vue')
+var ComponentA = require('../../src/components/a.vue')
+
+describe('a.vue', function () {
+
+  // asserting JavaScript options
+  it('should have correct message', function () {
+    expect(ComponentA.data().msg).toBe('Hello from Component A!')
+  })
+
+  // asserting rendered result by actually rendering the component
+  it('should render correct message', function () {
+    var vm = new Vue({
+      template: '<div><test></test></div>',
+      components: {
+        'test': ComponentA
+      }
+    }).$mount()
+    expect(vm.$el.querySelector('h2.red').textContent).toBe('Hello from Component A!')
+  })
+})
+```
+
+To run the tests, add the following NPM script:
+
+``` js
+// package.json
+...
+"scripts": {
+  ...
+  "test": "karma start karma.conf.js"
+}
+...
+```
+
+Finally, run:
+
+``` bash
+npm test
+```
+
+Again, [webpack vue-cli template](https://github.com/vuejs-templates/webpack) contains a fully working example with tests.