Skip to content

Commit

Permalink
docs(aio): Update i18n example to Angular V6 (#23660)
Browse files Browse the repository at this point in the history
PR Close #23660
  • Loading branch information
brandonroberts authored and IgorMinar committed May 8, 2018
1 parent 5581e97 commit 29600cb
Show file tree
Hide file tree
Showing 9 changed files with 438 additions and 128 deletions.
Binary file removed aio/content/examples/.DS_Store
Binary file not shown.
103 changes: 78 additions & 25 deletions aio/content/guide/i18n.md
Original file line number Diff line number Diff line change
Expand Up @@ -42,11 +42,10 @@ locale id to find the correct corresponding locale data.

By default, Angular uses the locale `en-US`, which is English as spoken in the United States of America.

To set your app's locale to another value, use the CLI parameter `--locale` with the value
of the locale id that you want to use:
To set your app's locale to another value, use the CLI parameter `--configuration` with the value of the locale id that you want to use:

<code-example language="sh" class="code-shell">
ng serve --aot --locale fr
ng serve --configuration=fr
</code-example>

If you use JIT, you also need to define the `LOCALE_ID` provider in your main module:
Expand Down Expand Up @@ -86,7 +85,7 @@ and `PercentPipe` use locale data to format data based on the `LOCALE_ID`.

By default, Angular only contains locale data for `en-US`. If you set the value of
`LOCALE_ID` to another locale, you must import locale data for that new locale.
The CLI imports the locale data for you when you use the parameter `--locale` with `ng serve` and
The CLI imports the locale data for you when you use the parameter `--configuration` with `ng serve` and
`ng build`.

If you want to import locale data for other languages, you can do it manually:
Expand Down Expand Up @@ -424,9 +423,9 @@ You can specify the translation format explicitly with the `--i18nFormat` flag a
these example commands:

<code-example language="sh" class="code-shell">
ng xi18n --i18nFormat=xlf
ng xi18n --i18nFormat=xlf2
ng xi18n --i18nFormat=xmb
ng xi18n --i18n-format=xlf
ng xi18n --i18n-format=xlf2
ng xi18n --i18n-format=xmb
</code-example>

The sample in this guide uses the default XLIFF 1.2 format.
Expand All @@ -442,11 +441,11 @@ The sample in this guide uses the default XLIFF 1.2 format.
### Other options

You can specify the output path used by the CLI to extract your translation source file with
the parameter `--outputPath`:
the parameter `--output-path`:

<code-example language="sh" class="code-shell">

ng xi18n --outputPath src/locale
ng xi18n --output-path locale

</code-example>

Expand All @@ -455,15 +454,15 @@ the parameter `--outFile`:

<code-example language="sh" class="code-shell">

ng xi18n --outFile source.xlf
ng xi18n --out-file source.xlf

</code-example>

You can specify the base locale of your app with the parameter `--locale`:
You can specify the base locale of your app with the parameter `--i18n-locale`:

<code-example language="sh" class="code-shell">

ng xi18n --locale fr
ng xi18n --i18n-locale fr

</code-example>

Expand Down Expand Up @@ -663,7 +662,7 @@ format that Angular understands, such as `.xtb`.
How you provide this information depends upon whether you compile with
the JIT compiler or the AOT compiler.

* With [AOT](guide/i18n#merge-aot), you pass the information as a CLI parameter.
* With [AOT](guide/i18n#merge-aot), you pass the information as a configuration
* With [JIT](guide/i18n#merge-jit), you provide the information at bootstrap time.


Expand All @@ -677,18 +676,67 @@ When you internationalize with the AOT compiler, you must pre-build a separate a
package for each language and serve the appropriate package based on either server-side language
detection or url parameters.

You also need to instruct the AOT compiler to use your translation file. To do so, you use three
options with the `ng serve` or `ng build` commands:
You also need to instruct the AOT compiler to use your translation configuration. To do so, you configure the translation with three options in your `angular.json` file.

* `--i18nFile`: the path to the translation file.
* `--i18nFormat`: the format of the translation file.
* `--locale`: the locale id.
* `i18nFile`: the path to the translation file.
* `i18nFormat`: the format of the translation file.
* `i18nLocale`: the locale id.

The example below shows how to serve the French language file created in previous sections of this
guide:
<code-example format="." language="ts">
"configurations": {
...
"fr": {
"aot": true,
"outputPath": "dist/my-project-fr/",
"i18nFile": "src/locale/messages.fr.xlf",
"i18nFormat": "xlf",
"i18nLocale": "fr",
...
}
}
</code-example>

You then pass the configuration with the `ng serve` or `ng build` commands. The example below shows how to serve the French language file created in previous sections of this guide:

<code-example language="sh" class="code-shell">
ng serve --aot --i18nFile=src/locale/messages.fr.xlf --i18nFormat=xlf --locale=fr
ng serve --configuration=fr
</code-example>

For production builds, you define a separate `production-fr` build configuration in your `angular.json`.

<code-example format="." language="ts">
"configurations": {
...
"production-fr": {
"fileReplacements": [
{
"replace": "src/environments/environment.ts",
"with": "src/environments/environment.prod.ts"
}
],
"optimization": true,
"outputHashing": "all",
"sourceMap": false,
"extractCss": true,
"namedChunks": false,
"aot": true,
"extractLicenses": true,
"vendorChunk": false,
"buildOptimizer": true,
"outputPath": "dist/my-project-fr/",
"i18nFile": "src/locale/messages.fr.xlf",
"i18nFormat": "xlf",
"i18nLocale": "fr",
"i18nMissingTranslation": "error"
},
...
}
</code-example>

The same configuration options can also be provided through the CLI with your existing `production` configuration.

<code-example language="sh" class="code-shell">
ng build --prod --i18n-file src/locale/messages.fr.xlf --i18n-format xlf --i18n-locale fr
</code-example>

{@a merge-jit}
Expand Down Expand Up @@ -731,11 +779,16 @@ compilation, the app will fail to load.
* Warning (default): show a 'Missing translation' warning in the console or shell.
* Ignore: do nothing.

If you use the AOT compiler, specify the warning level by using the CLI parameter
`--missingTranslation`. The example below shows how to set the warning level to error:
You specify the warning level in the `configurations` section your Angular CLI build configuration. The example below shows how to set the warning level to error:

<code-example language="sh" class="code-shell">
ng serve --aot --missingTranslation=error
<code-example format="." language="ts">
"configurations": {
...
"fr": {
...
"i18nMissingTranslation": "error"
}
}
</code-example>

If you use the JIT compiler, specify the warning level in the compiler config at bootstrap by adding
Expand Down
11 changes: 6 additions & 5 deletions aio/tools/example-zipper/customizer/package-json/i18n.json
Original file line number Diff line number Diff line change
@@ -1,17 +1,18 @@
{
"scripts": [
{ "name": "start", "command": "ng serve --aot" },
{ "name": "start:fr", "command": "ng serve --aot --i18nFile=src/locale/messages.fr.xlf --i18nFormat=xlf --locale=fr" },
{ "name": "start", "command": "ng serve" },
{ "name": "start:fr", "command": "ng serve --configuration=fr" },
{ "name": "build", "command": "ng build --prod" },
{ "name": "build:fr", "command": "ng build --prod --i18nFile=src/locale/messages.fr.xlf --i18nFormat=xlf --locale=fr" },
{ "name": "build:fr", "command": "ng build --configuration=production-fr" },
{ "name": "test", "command": "ng test" },
{ "name": "lint", "command": "ng lint" },
{ "name": "e2e", "command": "ng e2e --aot --i18nFile=src/locale/messages.fr.xlf --i18nFormat=xlf --locale=fr" },
{ "name": "extract", "command": "ng xi18n --outputPath=src/locale" }
{ "name": "e2e", "command": "ng e2e" },
{ "name": "extract", "command": "ng xi18n --output-path=locale" }
],
"dependencies": [],
"devDependencies": [
"@angular/cli",
"@angular-devkit/build-angular",
"@types/jasminewd2",
"jasmine-spec-reporter",
"karma-coverage-istanbul-reporter",
Expand Down
3 changes: 2 additions & 1 deletion aio/tools/examples/example-boilerplate.js
Original file line number Diff line number Diff line change
Expand Up @@ -52,6 +52,7 @@ const cliRelativePath = BOILERPLATE_PATHS.cli.map(file => `../cli/${file}`);

BOILERPLATE_PATHS.i18n = [
...cliRelativePath,
'angular.json',
'package.json'
];

Expand All @@ -63,7 +64,7 @@ BOILERPLATE_PATHS.universal = [

BOILERPLATE_PATHS.testing = [
...cliRelativePath,
'.angular-cli.json'
'angular.json'
];

const EXAMPLE_CONFIG_FILENAME = 'example-config.json';
Expand Down
2 changes: 1 addition & 1 deletion aio/tools/examples/example-boilerplate.spec.js
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@ describe('example-boilerplate tool', () => {
const sharedNodeModulesDir = path.resolve(sharedDir, 'node_modules');
const BPFiles = {
cli: 19,
i18n: 1,
i18n: 2,
universal: 2,
systemjs: 7,
common: 1
Expand Down
172 changes: 172 additions & 0 deletions aio/tools/examples/shared/boilerplate/i18n/angular.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,172 @@
{
"$schema": "./node_modules/@angular-devkit/core/src/workspace/workspace-schema.json",
"version": 1,
"newProjectRoot": "projects",
"projects": {
"angular.io-example": {
"root": "",
"projectType": "application",
"prefix": "app",
"architect": {
"build": {
"builder": "@angular-devkit/build-angular:browser",
"options": {
"outputPath": "dist/angular.io-example",
"index": "src/index.html",
"main": "src/main.ts",
"polyfills": "src/polyfills.ts",
"tsConfig": "src/tsconfig.app.json",
"assets": [
{
"glob": "favicon.ico",
"input": "src",
"output": "/"
},
{
"glob": "**/*",
"input": "src/assets",
"output": "/assets"
}
],
"styles": [
{
"input": "src/styles.css"
}
],
"scripts": []
},
"configurations": {
"production": {
"fileReplacements": [
{
"replace": "src/environments/environment.ts",
"with": "src/environments/environment.prod.ts"
}
],
"optimization": true,
"outputHashing": "all",
"sourceMap": false,
"extractCss": true,
"namedChunks": false,
"aot": true,
"extractLicenses": true,
"vendorChunk": false,
"buildOptimizer": true
},
"production-fr": {
"fileReplacements": [
{
"replace": "src/environments/environment.ts",
"with": "src/environments/environment.prod.ts"
}
],
"optimization": true,
"outputHashing": "all",
"sourceMap": false,
"extractCss": true,
"namedChunks": false,
"aot": true,
"extractLicenses": true,
"vendorChunk": false,
"buildOptimizer": true,
"outputPath": "dist/my-project-fr/",
"i18nFile": "src/locale/messages.fr.xlf",
"i18nFormat": "xlf",
"i18nLocale": "fr",
"i18nMissingTranslation": "error"
},
"fr": {
"aot": true,
"outputPath": "dist/my-project-fr/",
"i18nFile": "src/locale/messages.fr.xlf",
"i18nFormat": "xlf",
"i18nLocale": "fr",
"i18nMissingTranslation": "error"
}
}
},
"serve": {
"builder": "@angular-devkit/build-angular:dev-server",
"options": {
"browserTarget": "angular.io-example:build"
},
"configurations": {
"production": {
"browserTarget": "angular.io-example:build:production"
},
"fr": {
"browserTarget": "angular.io-example:build:fr"
}
}
},
"extract-i18n": {
"builder": "@angular-devkit/build-angular:extract-i18n",
"options": {
"browserTarget": "angular.io-example:build"
}
},
"test": {
"builder": "@angular-devkit/build-angular:karma",
"options": {
"main": "src/test.ts",
"polyfills": "src/polyfills.ts",
"tsConfig": "src/tsconfig.spec.json",
"karmaConfig": "src/karma.conf.js",
"styles": [
{
"input": "styles.css"
}
],
"scripts": [],
"assets": [
{
"glob": "favicon.ico",
"input": "src/",
"output": "/"
},
{
"glob": "**/*",
"input": "src/assets",
"output": "/assets"
}
]
}
},
"lint": {
"builder": "@angular-devkit/build-angular:tslint",
"options": {
"tsConfig": [
"src/tsconfig.app.json",
"src/tsconfig.spec.json"
],
"exclude": [
"**/node_modules/**"
]
}
}
}
},
"angular.io-example-e2e": {
"root": "e2e/",
"projectType": "application",
"architect": {
"e2e": {
"builder": "@angular-devkit/build-angular:protractor",
"options": {
"protractorConfig": "e2e/protractor.conf.js",
"devServerTarget": "angular.io-example:serve:fr"
}
},
"lint": {
"builder": "@angular-devkit/build-angular:tslint",
"options": {
"tsConfig": "e2e/tsconfig.e2e.json",
"exclude": [
"**/node_modules/**"
]
}
}
}
}
}
}

0 comments on commit 29600cb

Please sign in to comment.