docs(@angular/cli): add i18n commands and story

fix(@angular/cli): make flag values case insensitive (angular#5355) Fixes angular#5344 docs(@angular/cli): fixing broken ng doc link in wiki ng docs --> ng doc style: blueprint consistency (angular#5392) docs(@angular/cli): services are provided, not declared docs(@angular/cli): services are provided, not declared Merge branch 'master' into docs-i18n-story docs(@angular/cli): add i18n commands and story
ocombe · Mar 13, 2017 · 7c0ed5b · 7c0ed5b
1 parent 1c2f361
commit 7c0ed5b
Show file tree

Hide file tree

Showing 43 changed files with 323 additions and 64 deletions.
diff --git a/README.md b/README.md
@@ -57,10 +57,10 @@ ng serve
 ```
 Navigate to `http://localhost:4200/`. The app will automatically reload if you change any of the source files.
 
-You can configure the default HTTP port and the one used by the LiveReload server with two command-line options :
+You can configure the default HTTP host and port used by the development server with two command-line options :
 
 ```bash
-ng serve --host 0.0.0.0 --port 4201 --live-reload-port 49153
+ng serve --host 0.0.0.0 --port 4201
 ```
 
 ### Generating Components, Directives, Pipes and Services
@@ -88,6 +88,7 @@ Directive | `ng g directive my-new-directive`
 Pipe      | `ng g pipe my-new-pipe`
 Service   | `ng g service my-new-service`
 Class     | `ng g class my-new-class`
+Guard     | `ng g guard my-new-guard`
 Interface | `ng g interface my-new-interface`
 Enum      | `ng g enum my-new-enum`
 Module    | `ng g module my-module`
@@ -111,7 +112,7 @@ npm install -g @angular/cli@latest
 
 Local project package:
 ```bash
-rm -rf node_modules dist # use rmdir on Windows
+rm -rf node_modules dist # use rmdir /S/Q node_modules dist in Windows Command Prompt; use rm -r -fo node_modules,dist in Windows PowerShell
 npm install --save-dev @angular/cli@latest
 npm install
 ```

diff --git a/docs/documentation/build.md b/docs/documentation/build.md
@@ -103,8 +103,8 @@ or `ng serve --prod` will also make use of uglifying and tree-shaking functional
 
 `--target` (`-t`) Defines the build target.
 
-`--vendor-chunk` (`-vb`) Use a separate bundle containing only vendor libraries.
+`--vendor-chunk` (`-vc`) Use a separate bundle containing only vendor libraries.
 
 `--verbose` (`-v`) Adds more details to output logging.
 
-`--watch` (`-w`) Run build when files change.
+`--watch` (`-w`) Run build when files change.
diff --git a/docs/documentation/generate/interface.md b/docs/documentation/generate/interface.md
@@ -8,4 +8,4 @@
 ## Options
 `--app` Specifies app name or index to use.
 
-`type` Pptional String to specify the type of interface.
+`type` Optional String to specify the type of interface.
diff --git a/docs/documentation/generate/service.md b/docs/documentation/generate/service.md
@@ -10,6 +10,6 @@
 
 `--flat` Flag to indicate if a dir is created.
 
-`--module` (`-m`) Allows specification of the declaring module.
+`--module` (`-m`) Allows you to specify the module where the service should be provided
 
-`--spec` Specifies if a spec file is generated.
+`--spec` Specifies if a spec file is generated.
diff --git a/docs/documentation/home.md b/docs/documentation/home.md
@@ -50,9 +50,10 @@ End-to-end tests are run via [Protractor](https://angular.github.io/protractor/)
 * [ng e2e](e2e)
 * [ng build](build)
 * [ng get/ng set](config)
-* [ng docs](docs)
+* [ng doc](doc)
 * [ng eject](eject)
+* [ng xi18n](xi18n)
 
 ### Additional Information
 There are several [stories](stories) which will walk you through setting up
-additional aspects of Angular applciations.
+additional aspects of Angular applications.
diff --git a/docs/documentation/serve.md b/docs/documentation/serve.md
@@ -5,7 +5,7 @@
 ## Overview
 `ng serve` builds the application and starts a web server
 
-All the build Options are available in serve below are the additional options.
+All the build Options are available in serve, below are the additional options.
 
 ## Options
 `--host` (`-H`) Listens only on localhost by default.
@@ -24,4 +24,7 @@ All the build Options are available in serve below are the additional options.
 
 `--ssl-cert` SSL certificate to use for serving HTTPS.
 
-`--ssl-key` SSL key to use for serving HTTPS.
+`--ssl-key` SSL key to use for serving HTTPS.
+
+## Note
+When running `ng serve`, the compiled output is served from memory, not from disk. This means that the application being served is not located on disk in the `dist` folder.
diff --git a/docs/documentation/stories.md b/docs/documentation/stories.md
@@ -20,3 +20,5 @@
  - [Routing](stories/routing)
  - [3rd Party Lib](stories/third-party-lib)
  - [Corporate Proxy](stories/using-corporate-proxy)
+ - [Internationalization (i18n)](stories/internationalization)
+ - [Serve from Disk](stories/disk-serve)
diff --git a/docs/documentation/stories/disk-serve.md b/docs/documentation/stories/disk-serve.md
@@ -0,0 +1,23 @@
+# Serve from Disk
+
+The CLI supports running a live browser reload experience to users by running `ng serve`. This will compile the application upon file saves and reload the browser with the newly compiled application. This is done by hosting the application in memory and serving it via [webpack-dev-server](https://webpack.js.org/guides/development/#webpack-dev-server).
+
+If you wish to get a similar experience with the application output to disk please use the steps below. This practice will allow you to ensure that serving the contents of your `dist` dir will be closer to how your application will behave when it is deployed.
+
+## Environment Setup
+### Install a web server
+You will not be using webpack-dev-server, so you will need to install a web server for the browser to request the application. There are many to choose from but a good one to try is [lite-server](https://github.com/johnpapa/lite-server) as it will auto-reload your browser when new files are output.
+
+## Usage
+You will need two terminals to get the live-reload experience. The first will run the build in a watch mode to compile the application to the `dist` folder. The second will run the web server against the `dist` folder. The combination of these two processes will mimic the same behavior of ng serve.
+
+### 1st terminal - Start the build
+```bash
+ng build --watch
+```
+
+### 2nd terminal - Start the web server
+```bash
+lite-server --baseDir="dist"
+```
+When using `lite-server` the default browser will open to the appropriate URL.
diff --git a/docs/documentation/stories/include-angular-material.md b/docs/documentation/stories/include-angular-material.md
@@ -24,7 +24,7 @@ import { MaterialModule } from '@angular/material';
 @NgModule({
   imports: [
     ...
-    MaterialModule.forRoot()
+    MaterialModule
   ],
   ...
 })

diff --git a/docs/documentation/stories/internationalization.md b/docs/documentation/stories/internationalization.md
@@ -0,0 +1,72 @@
+# Internationalization (i18n)
+
+If you are working on internationalization, the CLI can help you with the following steps: 
+- extraction
+- serve
+- build
+
+The first thing that you have to do is to setup your application to use i18n.
+To do that you can follow [the cookbook on angular.io](https://angular.io/docs/ts/latest/cookbook/i18n.html).
+
+### Extraction
+When your app is ready, you can extract the strings to translate from your templates with the
+`ng xi18n` command.
+
+By default it will create a file named `messages.xlf` in your `src` folder.
+You can use [parameters from the xi18n command](../xi18n) to change the format,
+the name, the location and the source locale of the extracted file.
+
+For example to create a file in the `src/locale` folder you would use:
+```sh
+ng xi18n --output-path src/locale
+```
+
+### Serve
+Now that you have generated a messages bundle source file, you can translate it.
+Let's say that your file containing the french translations is named `messages.fr.xlf` 
+and is located in the `src/locale` folder.
+If you want to use it when you serve your application you can use the 3 following commands:
+- `--i18n-file` Localization file to use for i18n.
+- `--i18n-format` Format of the localization file specified with --i18n-file.
+- `--locale` Locale to use for i18n.
+
+In our case we can load the french translations with the following command:
+```sh
+ng serve --aot --locale fr --i18n-format xlf --i18n-file src/locale/messages.fr.xlf
+```
+
+Our application is exactly the same but the `LOCALE_ID` has been provided with "fr",
+`TRANSLATIONS_FORMAT` with "xlf" and `TRANSLATIONS` with the content of `messages.fr.xlf`.
+All the strings flagged for i18n have been replaced with their french translations.
+
+Note: this only works for AOT, if you want to use i18n in JIT you will have to update
+your bootstrap file yourself.
+
+### Build
+To build your application with a specific locale you can use the exact same commands
+that you used for `serve`:
+```sh
+ng build --aot --locale fr --i18n-format xlf --i18n-file src/i18n/messages.fr.xlf
+```
+
+When you build your application for a specific locale, it is probably a good idea to change
+the output path with the command `--output-path` in order to save the files to a different location.
+
+```sh
+ng build --aot --output-path dist/fr --locale fr --i18n-format xlf --i18n-file src/i18n/messages.fr.xlf
+```
+
+If you end up serving this specific version from a subdirectory, you can also change
+the base url used by your application with the command `--base-href`.
+
+For example if the french version of your application is served from https://myapp.com/fr/
+then you would build the french version like this:
+
+```sh
+ng build --aot --output-path dist/fr --base-href fr --locale fr --i18n-format xlf --i18n-file src/i18n/messages.fr.xlf
+```
+
+If you need more details about how to create scripts to generate the app in multiple
+languages and how to setup Apache 2 to serve them from different subdirectories,
+you can read [this great tutorial](https://medium.com/@feloy/deploying-an-i18n-angular-app-with-angular-cli-fc788f17e358#.1xq4iy6fp)
+by Philippe Martin.
diff --git a/docs/documentation/stories/rc-update.md b/docs/documentation/stories/rc-update.md
@@ -320,16 +320,17 @@ Packages in `dependencies`:
 - `@angular/*` packages now have a `^2.4.0` minimum (`^3.4.0` for router)
 - `core-js` remains unchanged at `^2.4.1`
 - `rxjs` to `^5.1.0`
+- `ts-helpers` was **removed**
 - `zone.js` to `^0.7.6`
 
-Packages in `dependencies`:
+Packages in `devDependencies`:
 - `@angular/cli` at `1.0.0-rc.0` replaces `angular-cli`
 - `@angular/compiler-cli` is also at `^2.4.0`
 - `@types/jasmine` remains unchanged and pinned at `2.5.38`
 - `@types/node` was updated to `~6.0.60`
 - `codelyzer` was updated to `~2.0.0`
 - `jasmine-core` was updated to `~2.5.2`
-- `jasmine-spec-reporter` was **removed**
+- `jasmine-spec-reporter` was updated to `~3.2.0`
 - `karma` was updated to `~1.4.1`
 - `karma-chrome-launcher` was updated to `~2.0.0`
 - `karma-cli` was updated to `~1.0.1`
@@ -353,6 +354,7 @@ We also updated the scripts section to make it more simple:
 "scripts": {
   "ng": "ng",
   "start": "ng serve",
+  "build": "ng build",
   "test": "ng test",
   "lint": "ng lint",
   "e2e": "ng e2e"

diff --git a/docs/documentation/test.md b/docs/documentation/test.md
@@ -20,8 +20,6 @@ You can run tests with coverage via `--code-coverage`. The coverage report will
 
 `--browsers` Override which browsers tests are run against.
 
-`--build` Build prior to running tests.
-
 `--code-coverage` Coverage report will be in the coverage/ directory.
 
 `--colors` Enable or disable colors in the output (reporters and logs).

diff --git a/docs/documentation/xi18n.md b/docs/documentation/xi18n.md
@@ -0,0 +1,21 @@
+<!-- Links in /docs/documentation should NOT have `.md` at the end, because they end up in our wiki at release. -->
+
+# ng xi18n
+
+## Overview
+`ng xi18n` Extracts i18n messages from the templates.
+
+## Options
+`--i18n-format` (`-f`) Output format for the generated file: either `xmb` or `xlf`.
+
+`--output-path` (`-op`) Path where output will be placed.
+
+`--locale` (`-l`) Specifies the source language of the application.
+
+`--outfile` (`-of`)  Name of the file to output.
+
+`--verbose` Adds more details to output logging.
+
+`--progress` Log progress to the console while running.
+
+`--app` (`-a`) Specifies app name to use.
diff --git a/lib/bootstrap-local.js b/lib/bootstrap-local.js
@@ -6,6 +6,8 @@ const path = require('path');
 const ts = require('typescript');
 
 
+Error.stackTraceLimit = Infinity;
+
 global.angularCliIsLocal = true;
 global.angularCliPackages = require('./packages');
 

diff --git a/packages/@angular/cli/blueprints/component/index.ts b/packages/@angular/cli/blueprints/component/index.ts
@@ -12,6 +12,27 @@ const getFiles = Blueprint.prototype.files;
 const stringUtils = require('ember-cli-string-utils');
 const astUtils = require('../../utilities/ast-utils');
 
+const viewEncapsulationMap: any = {
+  'emulated': 'Emulated',
+  'native': 'Native',
+  'none': 'None'
+};
+
+const changeDetectionMap: any = {
+  'default': 'Default',
+  'onpush': 'OnPush'
+};
+
+function correctCase(options: any) {
+  if (options.viewEncapsulation) {
+    options.viewEncapsulation = viewEncapsulationMap[options.viewEncapsulation.toLowerCase()];
+  }
+
+  if (options.changeDetection) {
+    options.changeDetection = changeDetectionMap[options.changeDetection.toLowerCase()];
+  }
+}
+
 export default Blueprint.extend({
   description: '',
 
@@ -95,8 +116,7 @@ export default Blueprint.extend({
       }
     } else {
       try {
-        this.pathToModule = findParentModule(
-          this.project.root, appConfig.root, this.dynamicPath.dir);
+        this.pathToModule = findParentModule(this.project.root, appConfig.root, this.generatePath);
       } catch (e) {
         if (!options.skipImport) {
           throw `Error locating module for declaration\n\t${e}`;
@@ -147,6 +167,8 @@ export default Blueprint.extend({
     options.changeDetection = options.changeDetection !== undefined ?
       options.changeDetection : CliConfig.getValue('defaults.component.changeDetection');
 
+    correctCase(options);
+
     return {
       dynamicPath: this.dynamicPath.dir.replace(this.dynamicPath.appRoot, ''),
       flat: options.flat,

diff --git a/packages/@angular/cli/blueprints/directive/index.ts b/packages/@angular/cli/blueprints/directive/index.ts
@@ -70,8 +70,7 @@ export default Blueprint.extend({
       }
     } else {
       try {
-        this.pathToModule = findParentModule
-          (this.project.root, appConfig.root, this.dynamicPath.dir);
+        this.pathToModule = findParentModule(this.project.root, appConfig.root, this.generatePath);
       } catch (e) {
         if (!options.skipImport) {
           throw `Error locating module for declaration\n\t${e}`;

diff --git a/packages/@angular/cli/blueprints/module/files/__path__/__name__-routing.module.ts b/packages/@angular/cli/blueprints/module/files/__path__/__name__-routing.module.ts
@@ -5,7 +5,6 @@ const routes: Routes = [];
 
 @NgModule({
   imports: [RouterModule.forChild(routes)],
-  exports: [RouterModule],
-  providers: []
+  exports: [RouterModule]
 })
 export class <%= classifiedModuleName %>RoutingModule { }
diff --git a/packages/@angular/cli/blueprints/ng/files/README.md b/packages/@angular/cli/blueprints/ng/files/README.md
@@ -3,6 +3,7 @@
 This project was generated with [Angular CLI](https://github.com/angular/angular-cli) version <%= version %>.
 
 ## Development server
+
 Run `ng serve` for a dev server. Navigate to `http://localhost:4200/`. The app will automatically reload if you change any of the source files.
 
 ## Code scaffolding

diff --git a/packages/@angular/cli/blueprints/ng/files/__path__/app/app-routing.module.ts b/packages/@angular/cli/blueprints/ng/files/__path__/app/app-routing.module.ts
@@ -10,7 +10,6 @@ const routes: Routes = [
 
 @NgModule({
   imports: [RouterModule.forRoot(routes)],
-  exports: [RouterModule],
-  providers: []
+  exports: [RouterModule]
 })
 export class AppRoutingModule { }
diff --git a/packages/@angular/cli/blueprints/ng/files/e2e/tsconfig.e2e.json b/packages/@angular/cli/blueprints/ng/files/e2e/tsconfig.e2e.json
@@ -10,7 +10,7 @@
     "lib": [
       "es2016"
     ],<% } %>
-    "outDir": "../dist/out-tsc-e2e",
+    "outDir": "../out-tsc/e2e",
     "module": "commonjs",
     "target": "es5",
     "types":[

diff --git a/packages/@angular/cli/blueprints/ng/files/gitignore b/packages/@angular/cli/blueprints/ng/files/gitignore
@@ -3,6 +3,7 @@
 # compiled output
 /dist
 /tmp
+/out-tsc
 
 # dependencies
 /node_modules
@@ -36,6 +37,6 @@ testem.log
 /e2e/*.js
 /e2e/*.map
 
-#System Files
+# System Files
 .DS_Store
 Thumbs.db
diff --git a/packages/@angular/cli/blueprints/ng/files/package.json b/packages/@angular/cli/blueprints/ng/files/package.json
@@ -40,7 +40,7 @@
     "karma-coverage-istanbul-reporter": "^0.2.0",
     "protractor": "~5.1.0",
     "ts-node": "~2.0.0",
-    "tslint": "~4.4.2",
+    "tslint": "~4.5.0",
     "typescript": "<%= ng4 ? '~2.1.0' : '~2.0.0' %>"
   }
 }
diff --git a/packages/@angular/cli/blueprints/pipe/index.ts b/packages/@angular/cli/blueprints/pipe/index.ts
@@ -65,8 +65,7 @@ export default Blueprint.extend({
       }
     } else {
       try {
-        this.pathToModule = findParentModule
-          (this.project.root, appConfig.root, this.dynamicPath.dir);
+        this.pathToModule = findParentModule(this.project.root, appConfig.root, this.generatePath);
       } catch (e) {
         if (!options.skipImport) {
           throw `Error locating module for declaration\n\t${e}`;