Merge pull request #1274 from Jinjiang/zh-cn

[docs] Chinese translation

Author: Justineo

docs/.vuepress/config.js

@@ -1,42 +1,96 @@
 module.exports = {
-  title: 'Vue Loader',
-  description: 'Webpack loader for single-file Vue components',
+  locales: {
+    '/': {
+      lang: 'en-US',
+      title: 'Vue Loader',
+      description: 'Webpack loader for single-file Vue components'
+    },
+    '/zh/': {
+      lang: 'zh-CN',
+      title: 'Vue Loader',
+      description: '处理 Vue 单文件组件的 Webpack loader'
+    }
+  },
   serviceWorker: true,
   theme: 'vue',
   themeConfig: {
     repo: 'vuejs/vue-loader',
     docsDir: 'docs',
-    nav: [
-      {
-        text: 'Guide',
-        link: '/guide/'
+    locales: {
+      '/': {
+        label: 'English',
+        selectText: 'Languages',
+        editLinkText: 'Edit this page on GitHub',
+        nav: [
+          {
+            text: 'Guide',
+            link: '/guide/'
+          },
+          {
+            text: 'SFC Spec',
+            link: '/spec.html'
+          },
+          {
+            text: 'Options Reference',
+            link: '/options.html'
+          },
+          {
+            text: 'Migrating from v14',
+            link: '/migrating.md'
+          }
+        ],
+        sidebar: [
+          '/',
+          '/guide/',
+          '/guide/asset-url',
+          '/guide/pre-processors',
+          '/guide/scoped-css',
+          '/guide/css-modules',
+          '/guide/hot-reload',
+          '/guide/functional',
+          '/guide/custom-blocks',
+          '/guide/extract-css',
+          '/guide/linting',
+          '/guide/testing'
+        ]
       },
-      {
-        text: 'SFC Spec',
-        link: '/spec.html'
-      },
-      {
-        text: 'Options Reference',
-        link: '/options.html'
-      },
-      {
-        text: 'Migrating from v14',
-        link: '/migrating.md'
+      '/zh/': {
+        label: '简体中文',
+        selectText: '选择语言',
+        editLinkText: '在 GitHub 上编辑此页',
+        nav: [
+          {
+            text: '指南',
+            link: '/zh/guide/'
+          },
+          {
+            text: '单文件组件规范',
+            link: '/zh/spec.html'
+          },
+          {
+            text: '选项参考',
+            link: '/zh/options.html'
+          },
+          {
+            text: '如何从 v14 迁移',
+            link: '/zh/migrating.md'
+          }
+        ],
+        sidebar: [
+          '/zh/',
+          '/zh/guide/',
+          '/zh/guide/asset-url',
+          '/zh/guide/pre-processors',
+          '/zh/guide/scoped-css',
+          '/zh/guide/css-modules',
+          '/zh/guide/hot-reload',
+          '/zh/guide/functional',
+          '/zh/guide/custom-blocks',
+          '/zh/guide/extract-css',
+          '/zh/guide/linting',
+          '/zh/guide/testing'
+        ]
       }
-    ],
-    sidebar: [
-      '/',
-      '/guide/',
-      '/guide/asset-url',
-      '/guide/pre-processors',
-      '/guide/scoped-css',
-      '/guide/css-modules',
-      '/guide/hot-reload',
-      '/guide/functional',
-      '/guide/custom-blocks',
-      '/guide/extract-css',
-      '/guide/linting',
-      '/guide/testing'
-    ]
+    }
   }
 }

docs/guide/asset-url.md

@@ -2,7 +2,7 @@
 
 When Vue Loader compiles the `<template>` blocks in SFCs, it also converts any encountered asset URLs into **webpack module requests**.
 
-For example, the following template snippet
+For example, the following template snippet:
 
 ``` vue
 <img src="../image.png">

docs/zh/README.md

@@ -0,0 +1,41 @@
+# 介绍
+
+:::tip 版本说明
+这份文档是为 Vue Loader v15 及以上版本撰写的。如果你正在从 v14 或更早的版本往这里迁移，请查阅[迁移指南](../migrating.md)。如果你正在使用老版本，其对应的文档[在此](https://vue-loader-v14.vuejs.org)。
+:::
+
+## Vue Loader 是什么？
+
+Vue Loader 是一个 [webpack](https://webpack.js.org/) 的 loader，它允许你以一种名为[单文件组件 (SFCs)](./spec.md)的格式撰写 Vue 组件：
+
+``` vue
+<template>
+  <div class="example">{{ msg }}</div>
+</template>
+
+<script>
+export default {
+  data () {
+    return {
+      msg: 'Hello world!'
+    }
+  }
+}
+</script>
+
+<style>
+.example {
+  color: red;
+}
+</style>
+```
+
+Vue Loader 还提供了很多酷炫的特性：
+
+- 允许为 Vue 组件的每个部分使用其它的 webpack loader，例如在 `<style>` 的部分使用 Sass 和在 `<template>` 的部分使用 Pug；
+- 允许在一个 `.vue` 文件中使用自定义块，并对其运用自定义的 loader 链；
+- 使用 webpack loader 将 `<style>` 和 `<template>` 中引用的资源当作模块依赖来处理；
+- 为每个组件模拟出 scoped CSS；
+- 在开发过程中使用热重载来保持状态。
+
+简而言之，webpack 和 Vue Loader 的结合为你提供了一个现代、灵活且极其强大的前端工作流，来帮助撰写 Vue.js 应用。

docs/zh/guide/README.md

@@ -0,0 +1,75 @@
+# 起步
+
+## Vue CLI
+
+如果你不想手动设置 webpack，我们推荐使用 [Vue CLI](https://github.com/vuejs/vue-cli) 直接创建一个项目的脚手架。通过 Vue CLI 创建的项目会针对多数常见的开发需求进行预先配置，做到开箱即用。
+
+如果 Vue CLI 提供的内建没有满足你的需求，或者你乐于从零开始创建你自己的 webpack 配置，那么请继续阅读这篇指南。
+
+## 手动配置
+
+Vue Loader 的配置和其它的 loader 不太一样。除了通过一条规则将 `vue-loader` 应用到所有扩展名为 `.vue` 的文件上之外，请确保在你的 webpack 配置中添加 Vue Loader 的插件：
+
+``` js
+// webpack.config.js
+const { VueLoaderPlugin } = require('vue-loader')
+
+module.exports = {
+  module: {
+    rules: [
+      // ... 其它规则
+      {
+        test: /\.vue$/,
+        loader: 'vue-loader'
+      }
+    ]
+  },
+  plugins: [
+    // 请确保引入这个插件！
+    new VueLoaderPlugin()
+  ]
+}
+```
+
+**这个插件是必须的！**它的职责是将你定义过的其它规则复制并应用到 `.vue` 文件里相应语言的块。例如，如果你有一条匹配 `/\.js$/` 的规则，那么它会应用到 `.vue` 文件里的 `<script>` 块。
+
+一个更完整的 webpack 配置示例看起来像这样：
+
+``` js
+// webpack.config.js
+const path = require('path')
+const { VueLoaderPlugin } = require('vue-loader')
+
+module.exports = {
+  mode: 'development',
+  module: {
+    rules: [
+      {
+        test: /\.vue$/,
+        loader: 'vue-loader'
+      },
+      // 它会应用到普通的 `.js` 文件
+      // 以及 `.vue` 文件中的 `<script>` 块
+      {
+        test: /\.js$/,
+        loader: 'babel-loader'
+      },
+      // 它会应用到普通的 `.css` 文件
+      // 以及 `.vue` 文件中的 `<style>` 块
+      {
+        test: /\.css$/,
+        use: [
+          'vue-style-loader',
+          'css-loader'
+        ]
+      }
+    ]
+  },
+  plugins: [
+    // 请确保引入这个插件来施展魔法
+    new VueLoaderPlugin()
+  ]
+}
+```
+
+你也可以在[选项参考](../options.md)查阅所有可用的 loader 选项。

docs/zh/guide/asset-url.md

@@ -0,0 +1,60 @@
+# 处理资源路径
+
+当 Vue Loader 编译单文件组件中的 `<template>` 块时，它也会将所有遇到的资源 URL 转换为 **webpack 模块请求**。
+
+例如，下面的模板代码片段：
+
+``` vue
+<img src="../image.png">
+```
+
+将会被编译成为：
+
+``` js
+createElement('img', {
+  attrs: {
+    src: require('../image.png') // 现在这是一个模块的请求了
+  }
+})
+```
+
+默认下列标签/特性的组合会被转换，且这些组合时可以使用 [transformAssetUrls](../options.md#transformasseturls) 选项进行配置的。
+
+``` js
+{
+  video: ['src', 'poster'],
+  source: 'src',
+  img: 'src',
+  image: 'xlink:href'
+}
+```
+
+此外，如果你配置了为 `<style>` 块使用 [css-loader](https://github.com/webpack-contrib/css-loader)，则你的 CSS 中的资源 URL 也会被同等处理。
+
+## 转换规则
+
+资源 URL 转换会遵循如下规则：
+
+- 如果路径是绝对路径 (例如 `/images/foo.png`)，会原样保留。
+
+- 如果路径以 `.` 开头，将会被看作相对的模块依赖，并按照你的本地文件系统上的目录结构进行解析。
+
+- 如果路径以 `~` 开头，其后的部分将会被看作模块依赖。这意味着你可以用该特性来引用一个 Node 依赖中的资源：
+
+  ``` html
+  <img src="~some-npm-package/foo.png">
+  ```
+
+- 如果路径以 `@` 开头，也会被看作模块依赖。如果你的 webpack 配置中给 `@` 配置了 alias，这就很有用了。所有 `vue-cli` 创建的项目都默认配置了将 `@` 指向 `/src`。
+
+## 相关的 Loader
+
+因为像 `.png` 这样的文件不是一个 JavaScript 模块，你需要配置 webpack 使用 [file-loader](https://github.com/webpack/file-loader) 或者 [url-loader](https://github.com/webpack/url-loader) 去合理地处理它们。通过 Vue CLI 创建的项目已经把这些预配置好了。
+
+## 为什么
+
+转换资源 URL 的好处是：
+
+1. `file-loader` 可以指定要复制和放置资源文件的位置，以及如何使用版本哈希命名以获得更好的缓存。此外，这意味着 **你可以就近管理图片文件，可以使用相对路径而不用担心部署时 URL 的问题**。使用正确的配置，webpack 将会在打包输出中自动重写文件路径为正确的 URL。
+
+2. `url-loader` 允许你有条件地将文件转换为内联的 base-64 URL (当文件小于给定的阈值)，这会减少小文件的 HTTP 请求数。如果文件大于该阈值，会自动的交给 `file-loader` 处理。