docs: document usage for generator & prompts in remote/local presets [ci skip]

yyx990803 · yyx990803 · commit c4843ef12ef7 · 2018-08-08T16:54:19.000-04:00
diff --git a/docs/guide/plugins-and-presets.md b/docs/guide/plugins-and-presets.md
@@ -180,7 +180,13 @@ For such scenarios you can specify `"prompts": true` in a plugin's options to al
 
 ### Remote Presets
 
-You can share a preset with other developers by publishing it in a git repo. The repo should contain a `preset.json` file containing the preset data. You can then use the `--preset` option to use the remote preset when creating a project:
+You can share a preset with other developers by publishing it in a git repo. The repo can contain the following files:
+
+- `preset.json`: the main file containing the preset data (required).
+- `generator.js`: a [Generator](../dev-guide/plugin-dev.md#generator) that can inject or modify files in the project.
+- `prompts.js`: a [prompts file](../dev-guide/plugin-dev.md#prompts-for-3rd-party-plugins) that can collect options for the generator.
+
+Once the repo is published, you can then use the `--preset` option to use the remote preset when creating a project:
 
 ``` bash
 # use preset from GitHub repo
@@ -196,8 +202,12 @@ vue create --preset bitbucket:username/repo --clone my-project
 
 ### Local Filesystem Preset
 
-When developing a remote preset, it can be tedious to have to repeatedly push the preset to a remote repo to test it. To simplify the workflow, the `--preset` flag also accepts local `.json` files:
+When developing a remote preset, it can be tedious to have to repeatedly push the preset to a remote repo to test it. To simplify the workflow, you can directly work with local presets. Vue CLI will load local presets if the value for the `--preset` option is a relative or absolute file path, or ends with `.json`:
 
 ``` bash
-vue create --preset local.json my-project
+# ./my-preset should be a directory containing preset.json
+vue create --preset ./my-preset my-project
+
+# or directly use a json file in cwd:
+vue create --preset my-preset.json
 ```
diff --git a/docs/zh/dev-guide/plugin-dev.md b/docs/zh/dev-guide/plugin-dev.md
@@ -15,15 +15,15 @@ sidebarDepth: 3
 
 ### Creator
 
-[Creator][creator-class] 是调用 `vue create <app>` 时创建的类。负责偏好提示符、调用 generator 和安装依赖。
+[Creator][creator-class] 是调用 `vue create <app>` 时创建的类。负责偏好对话、调用 generator 和安装依赖。
 
 ### Service
 
 [Service][service-class] 是调用 `vue-cli-service <command> [...args]` 时创建的类。负责管理内部的 webpack 配置、暴露服务和构建项目的命令等。
 
 ### CLI 插件
 
-CLI 插件是一个可以为 `@vue/cli` 项目添加额外特性的 npm 包。它应该始终包含一个 [Service 插件](#service-插件)作为其主要导出，且可选的包含一个 [Generator](#generator) 和一个 [Prompt 文件](#第三方插件的提示符)。
+CLI 插件是一个可以为 `@vue/cli` 项目添加额外特性的 npm 包。它应该始终包含一个 [Service 插件](#service-插件)作为其主要导出，且可选的包含一个 [Generator](#generator) 和一个 [Prompt 文件](#第三方插件的对话)。
 
 一个典型的 CLI 插件的目录结构看起来是这样的：
 
@@ -152,7 +152,7 @@ module.exports = {
 
 1. 一个 `GeneratorAPI` 实例：
 
-2. 这个插件的 generator 选项。这些选项会在项目创建提示符过程中被解析，或从一个保存在 `~/.vuerc` 中的 preset 中加载。例如，如果保存好的 `~/.vuerc` 像如下的这样：
+2. 这个插件的 generator 选项。这些选项会在项目创建对话过程中被解析，或从一个保存在 `~/.vuerc` 中的 preset 中加载。例如，如果保存好的 `~/.vuerc` 像如下的这样：
 
     ``` json
     {
@@ -168,7 +168,7 @@ module.exports = {
 
     如果用户使用 preset `foo` 创建了一个项目，那么 `@vue/cli-plugin-foo` 的 generator 就会收到 `{ option: 'bar' }` 作为第二个参数。
 
-    对于一个第三方插件来说，该选项将会解析自提示符或用户执行 `vue invoke` 时的命令行参数中 (详见[第三方插件的提示符](#第三方插件的提示符))。
+    对于一个第三方插件来说，该选项将会解析自对话或用户执行 `vue invoke` 时的命令行参数中 (详见[第三方插件的对话](#第三方插件的对话))。
 
 3. 整个 preset (`presets.foo`) 将会作为第三个参数传入。
 
@@ -261,13 +261,13 @@ _variables.scss
 ```
 
 
-### 提示符
+### Prompts
 
-#### 内建插件的提示符
+#### 内建插件的对话
 
-只有内建插件可以定制创建新项目时的初始化提示符，且这些提示符模块放置在 [`@vue/cli` 包的内部][prompt-modules]。
+只有内建插件可以定制创建新项目时的初始化对话，且这些对话模块放置在 [`@vue/cli` 包的内部][prompt-modules]。
 
-一个提示符模块应该导出一个函数，这个函数接收一个 [PromptModuleAPI][prompt-api] 实例。这些提示符的底层使用 [inquirer](https://github.com/SBoudrias/Inquirer.js) 进行展示：
+一个对话模块应该导出一个函数，这个函数接收一个 [PromptModuleAPI][prompt-api] 实例。这些对话的底层使用 [inquirer](https://github.com/SBoudrias/Inquirer.js) 进行展示：
 
 ``` js
 module.exports = api => {
@@ -277,16 +277,16 @@ module.exports = api => {
     value: 'my-feature'
   })
 
-  // injectPrompt 期望接收一个有效的 inquirer 提示符对象
+  // injectPrompt 期望接收一个有效的 inquirer 对话对象
   api.injectPrompt({
     name: 'someFlag',
-    // 确认提示符只在用户已经选取了特性的时候展示
+    // 确认对话只在用户已经选取了特性的时候展示
     when: answers => answers.features.include('my-feature'),
     message: 'Do you want to turn on flag foo?',
     type: 'confirm'
   })
 
-  // 当所有的提示符都完成之后，将你的插件注入到
+  // 当所有的对话都完成之后，将你的插件注入到
   // 即将传递给 Generator 的 options 中
   api.onPromptComplete((answers, options) => {
     if (answers.features.includes('my-feature')) {
@@ -298,11 +298,11 @@ module.exports = api => {
 }
 ```
 
-#### 第三方插件的提示符
+#### 第三方插件的对话
 
 第三方插件通常会在一个项目创建完毕后被手动安装，且用户将会通过调用 `vue invoke` 来初始化这个插件。如果这个插件在其根目录包含一个 `prompt.js`，那么它将会用在该插件被初始化调用的时候。这个文件应该导出一个用于 Inquirer.js 的[问题](https://github.com/SBoudrias/Inquirer.js#question)的数组。这些被解析的答案对象会作为选项被传递给插件的 generator。
 
-或者，用户可以通过在命令行传递选项来跳过提示符直接初始化插件，比如：
+或者，用户可以通过在命令行传递选项来跳过对话直接初始化插件，比如：
 
 ``` bash
 vue invoke my-plugin --mode awesome
diff --git a/docs/zh/guide/plugins-and-presets.md b/docs/zh/guide/plugins-and-presets.md
@@ -180,7 +180,13 @@ Preset 的数据会被插件生成器用来生成相应的项目文件。除了
 
 ### 远程 Preset
 
-你可以通过发布 git repo 将一个 preset 分享给其他开发者。这个 repo 应该包含一个包含了 preset 数据的 `preset.json` 文件。然后你就可以在创建项目的时候通过 `--preset` 选项使用这个远程的 preset 了：
+你可以通过发布 git repo 将一个 preset 分享给其他开发者。这个 repo 应该包含以下文件：
+
+- `preset.json`: 包含 preset 数据的主要文件（必需）。
+- `generator.js`: 一个可以注入或是修改项目中文件的 [Generator](../dev-guide/plugin-dev.md#generator)。
+- `prompts.js` 一个可以通过命令行对话为 generator 收集选项的 [prompts 文件](../dev-guide/plugin-dev.md#第三方插件的对话)。
+
+发布 repo 后，你就可以在创建项目的时候通过 `--preset` 选项使用这个远程的 preset 了：
 
 ``` bash
 # 从 GitHub repo 使用 preset
@@ -196,8 +202,12 @@ vue create --preset bitbucket:username/repo --clone my-project
 
 ### 加载文件系统中的 Preset
 
-当开发一个远程 preset 的时候，你必须不厌其烦的向远程 repo 发出 push 进行反复测试。为了简化这个流程，`--preset` 标记也支持本地的 `.json` 文件：
+当开发一个远程 preset 的时候，你必须不厌其烦的向远程 repo 发出 push 进行反复测试。为了简化这个流程，你也可以直接在本地测试 preset。如果 `--preset` 选项的值是一个相对或绝对文件路径，或是以 `.json` 结尾，则 Vue CLI 会加载本地的 preset：
 
 ``` bash
-vue create --preset local.json my-project
+# ./my-preset 应当是一个包含 preset.json 的文件夹
+vue create --preset ./my-preset my-project
+
+# 或者，直接使用当前工作目录下的 json 文件：
+vue create --preset my-preset.json
 ```
