From 68fdbcef2fd3234317d50862b6d0eebd22a75ad1 Mon Sep 17 00:00:00 2001 From: Olivier Combe Date: Sun, 11 Sep 2016 21:09:22 +0200 Subject: [PATCH 01/21] docs(guide): document internationalization (i18n) --- public/docs/_examples/i18n/e2e-spec.ts | 19 ++ .../i18n/ts-snippets/i18n.config.snippets.ts | 130 ++++++++ public/docs/dart/latest/guide/i18n.jade | 1 + public/docs/js/latest/guide/i18n.jade | 1 + public/docs/ts/latest/guide/_data.json | 5 + public/docs/ts/latest/guide/i18n.jade | 306 ++++++++++++++++++ 6 files changed, 462 insertions(+) create mode 100644 public/docs/_examples/i18n/e2e-spec.ts create mode 100644 public/docs/_examples/i18n/ts-snippets/i18n.config.snippets.ts create mode 100644 public/docs/dart/latest/guide/i18n.jade create mode 100644 public/docs/js/latest/guide/i18n.jade create mode 100644 public/docs/ts/latest/guide/i18n.jade diff --git a/public/docs/_examples/i18n/e2e-spec.ts b/public/docs/_examples/i18n/e2e-spec.ts new file mode 100644 index 0000000000..85dbcd8626 --- /dev/null +++ b/public/docs/_examples/i18n/e2e-spec.ts @@ -0,0 +1,19 @@ +/// +'use strict'; +describe('QuickStart E2E Tests', function () { + + let expectedMsg = 'Hello from Angular 2 App with i18n'; + + beforeEach(function () { + browser.get(''); + }); + + it(`should display: ${expectedMsg}`, function () { + expect(element(by.css('h1')).getText()).toEqual(expectedMsg); + }); + + it('should display an image', function () { + expect(element(by.css('img')).isPresent()).toBe(true); + }); + +}); diff --git a/public/docs/_examples/i18n/ts-snippets/i18n.config.snippets.ts b/public/docs/_examples/i18n/ts-snippets/i18n.config.snippets.ts new file mode 100644 index 0000000000..34b8b04c7c --- /dev/null +++ b/public/docs/_examples/i18n/ts-snippets/i18n.config.snippets.ts @@ -0,0 +1,130 @@ +/* tslint:disable */ +// #docregion i18n-directive +

Hello i18n

+// #enddocregion i18n-directive + +// #docregion i18n-directive-desc +

Hello i18n

+// #enddocregion i18n-directive-desc + +// #docregion i18n-directive-meaning +

Hello i18n

+// #enddocregion i18n-directive-meaning + +// #docregion i18n-plural-pipe +@Component({ + selector: 'app', + template: ` +
+ {{ messages.length | i18nPlural: messageMapping }} +
+ `, +}) +class MyApp { + messages: any[]; + messageMapping: {[k:string]: string} = { + '=0': 'No messages.', + '=1': 'One message.', + 'other': '# messages.' + } +} +// #enddocregion i18n-plural-pipe + +// #docregion i18n-select-pipe +@Component({ + selector: 'app', + template: ` +
+ {{ gender | i18nSelect: inviteMap }} +
+ `, +}) +class MyApp { + gender: string = 'male'; + inviteMap: any = { + 'male': 'Invite him.', + 'female': 'Invite her.', + 'other': 'Invite them.' + } +} +// #enddocregion i18n-select-pipe + +// #docregion tsconfig1 +{ + "compilerOptions": { + "emitDecoratorMetadata": true, + "experimentalDecorators": true, + "target": "es5", + "module": "commonjs", + "outDir": "./dist/out-tsc" + }, + "files": [ + "./src/main.ts" + ] +} +// #enddocregion tsconfig1 + +// #docregion tsconfig2 +{ + "compilerOptions": { + "emitDecoratorMetadata": true, + "experimentalDecorators": true, + "target": "es5", + "module": "commonjs", + "outDir": "./dist/out-tsc" + }, + "files": [ + "./src/main.ts" + ], + "angularCompilerOptions": { + "genDir": "./src/i18n" + } +} +// #enddocregion tsconfig2 + +// #docregion bootstrap +import { platformBrowserDynamic } from '@angular/platform-browser-dynamic'; +import { enableProdMode } from '@angular/core'; +import { environment } from './environments/environment'; +import { AppModule } from './app/'; + +if (environment.production) { + enableProdMode(); +} + +platformBrowserDynamic().bootstrapModule(AppModule); +// #enddocregion bootstrap + +// #docregion bootstrap-i18n +import { platformBrowserDynamic } from '@angular/platform-browser-dynamic'; +import { enableProdMode, TRANSLATIONS, TRANSLATIONS_FORMAT, LOCALE_ID } from '@angular/core'; +import { environment } from './environments/environment'; +import { AppModule } from './app/'; +import { TRANSLATION } from './i18n/messages.fr'; + +if (environment.production) { + enableProdMode(); +} + +// Compile using french translations +platformBrowserDynamic().bootstrapModule( + AppModule, + { + providers: [ + {provide: TRANSLATIONS, useValue: TRANSLATION}, + {provide: TRANSLATIONS_FORMAT, useValue: 'xlf'}, + {provide: LOCALE_ID, useValue: 'fr'} + ] + } +); +// #enddocregion bootstrap-i18n + + +// #docregion messages-ts +export const TRANSLATION = ` + + + ... + + `; +// #enddocregion messages-ts diff --git a/public/docs/dart/latest/guide/i18n.jade b/public/docs/dart/latest/guide/i18n.jade new file mode 100644 index 0000000000..6778b6af28 --- /dev/null +++ b/public/docs/dart/latest/guide/i18n.jade @@ -0,0 +1 @@ +!= partial("../../../_includes/_ts-temp") diff --git a/public/docs/js/latest/guide/i18n.jade b/public/docs/js/latest/guide/i18n.jade new file mode 100644 index 0000000000..6778b6af28 --- /dev/null +++ b/public/docs/js/latest/guide/i18n.jade @@ -0,0 +1 @@ +!= partial("../../../_includes/_ts-temp") diff --git a/public/docs/ts/latest/guide/_data.json b/public/docs/ts/latest/guide/_data.json index 97c35aa8fb..333e9737a0 100644 --- a/public/docs/ts/latest/guide/_data.json +++ b/public/docs/ts/latest/guide/_data.json @@ -153,5 +153,10 @@ "webpack": { "title": "Webpack: an introduction", "intro": "Create your Angular 2 applications with a Webpack based tooling" + }, + + "i18n": { + "title": "Internationalization (i18n)", + "intro": "Easily translate your website into multiple languages" } } diff --git a/public/docs/ts/latest/guide/i18n.jade b/public/docs/ts/latest/guide/i18n.jade new file mode 100644 index 0000000000..814609ee11 --- /dev/null +++ b/public/docs/ts/latest/guide/i18n.jade @@ -0,0 +1,306 @@ +include ../_util-fns + +:marked + With internationalization, also known as i18n, we can display our website in multiple languages. There are two different + approaches to internationalization: with AoT compilation which requires a build step and a full reload when the language changes, + or with JiT which doesn't require a full reload and uses bindings to determine when a translation is needed. + + + + + ## Table of contents + + [Different approaches to internationalization](#approaches-internationalization) + + * [JiT](#jit) + * [AoT](#aot) + + [Angular 2 and i18n](#angular2-i18n) + + * [i18n directive](#i18n-directive) + * [i18n plural pipe](#i18n-plural-pipe) + * [i18n select pipe](#i18n-select-pipe) + + [Extract and use translations](#extract) + + * [Extract messages with ng-xi18n](#ng-xi18n) + * [Translate messages](#translate) + * [Use translations with the JiT approach](#use-jit) + * [Use translations with the AoT approach](#use-aot) + + +.l-main-section + +:marked + ## Different approaches to internationalization + + +a(id="jit") +.l-main-section +:marked + ### Just in time (JiT) approach + + The JiT approach relies on providing the translations to our application and binding them to our templates using directives, pipes and interpolations. + + Its main features are: + * Minimal server side support required: The same version of the application code is served by the server. + However, the server must also serve translated message bundles back to the application or have tools that embed all + translations in the application code at build time. + * Our application must track all the pieces of the UI that need to be updated when the locale changes. + In addition, if the new language strings are being loaded over the network, this could take time and the UI needs to indicate this in some way to the user. + * Allows one to support multiple languages in the same view. + As an example, a page could display a table showing how the user's advertising message might look in different locales. + This is fairly easy to do with this approach since it's fairly simple to have one locale per root node. + * The server is not required to determine the locale from the request – the client side can use cookies, the browser + language, and JS APIs to determine the language. + However, it's still be beneficial for the server to do some of this (e.g. to serve the likely language pack together with the application) + but that can be done at a later stage in development or for production. + + +a(id="aot") +.l-main-section +:marked + ### Ahead of time (AoT) compilation approach + + The AoT approach relies on precompiling the templates using the `ngc` compiler and then injecting the translations into these files. + + Its main features are: + * Performance win: by reloading the entire app, there is no need to track and update the bindings/UI that change as a result of the locale change. + * The locale changes so rarely that the cost of the reload is usually incurred only once. + * No information/state is (typically) lost. The user is presumably changing the language because he could not understand the earlier language. + This means that he doesn't have unsaved information in the application. + * Tools support: the strings to translate are easily extracted from our templates. + The resulting translations are in a generic format that can be consumed both by Angular 2 and one of the many translation softwares available. + * Cannot support multiple languages in the same application view. + * We have to reload the app to change the language. + * Extra server side support is needed: Since we generate different precompiled files for each language, the server must perform cookie/user agent analysis + to decide which localized version of the application code should be returned to the user. This also causes a cache miss. + * The server is now responsible for determining the default localized version to serve. (e.g. cookies / geo-ip / Accept-Language header, etc.) + + +a(id="angular2-i18n") +.l-main-section +:marked + ## Angular 2 and i18n + + Whatever approach we decide to use, we must update our templates to define which strings will be translated. + + +a(id="i18n-directive") +.l-main-section +:marked + ### i18n directive + + The i18n directive is what tells Angular where it should inject the translations. + It is used by both the JiT and the AoT approaches. + + We simply add the attribute `i18n` to an element and the content string will be replaced when necessary. + ++makeExample('i18n/ts-snippets/i18n.config.snippets.ts', 'i18n-directive')(format=".") + +:marked + To help the translators, we can add more information about the meaning and context of this string. + Simply add a description to the i18n attribute: + ++makeExample('i18n/ts-snippets/i18n.config.snippets.ts', 'i18n-directive-desc')(format=".") + +:marked + We can add some meaning as well, separate the meaning from the description with a pipe `|`: + ++makeExample('i18n/ts-snippets/i18n.config.snippets.ts', 'i18n-directive-meaning')(format=".") + +:marked + Both the meaning and the description will be extracted by our messages extractor and added to the messages file. + It will help our translators to translate our application with a better understanding of what our text means. + + +a(id="i18n-plural-pipe") +.l-main-section +:marked + ### i18n plural pipe + + When we need to pluralize some terms based on values, we can use the plural pipe. + + This pipe provides different translations based on a number and on a mapping (which is an object + that mimics the [ICU format](http://userguide.icu-project.org/formatparse/messages)): + ++makeExample('i18n/ts-snippets/i18n.config.snippets.ts', 'i18n-plural-pipe')(format=".") + +.alert.is-important + :marked + The plural pipe is not yet supported by the ng-xi18n messages extractor. + + +a(id="i18n-select-pipe") +.l-main-section +:marked + ### i18n select pipe + + Just like the plural pipe displays different translations based on a number, the select pipe is used to display different + translations based on a string that matches the current value. + + It also uses a mapping object that mimics the [ICU format](http://userguide.icu-project.org/formatparse/messages): + ++makeExample('i18n/ts-snippets/i18n.config.snippets.ts', 'i18n-select-pipe')(format=".") +.alert.is-important + :marked + The select pipe is not yet supported by the ng-xi18n messages extractor. + + +a(id="extract") +.l-main-section +:marked + ## Extract and use translations + +a(id="ng-xi18n") +.l-main-section +:marked + ### Extract messages with ng-xi18n + + Now that our templates have been updated to support i18n translations, we can use the `ng-xi18n` messages extractor. + This cli tool is based on `ngc`, and is available in the `@angular/compiler-cli` npm package. + + To use it, the first thing that we have to do is to install it: + +code-example(language="sh"). + npm install @angular/compiler-cli --save + +:marked + Like `ngc`, `ng-xi18n` is based on `tsc`, the TypeScript compiler. It uses the file `tsconfig.json` to determine where + are our files. We have to make sure that we have defined the parameter `files` so that it knows what is the entry point + of our application. + ++makeExample('i18n/ts-snippets/i18n.config.snippets.ts', 'tsconfig1')(format=".") + +:marked + We can then use the `ng-xi18n` binary to generate a file named `messages.xlf` at the root of our application. + +code-example(language="sh"). + ./node_modules/.bin/ng-xi18n + +.alert.is-helpful + :marked + It is considered good practice to create a new npm command that will be used to run `ng-xi18n`. + + Edit package.json and add the following command in the `scripts` property: `"extract": "ng-xi18n"`. + We can now generate our translations using the command `npm run extract`. + +:marked + If we want to generate this `messages.xlf` file somewhere in particular, `ng-xi18n` uses the same parameters as `ngc`. + + Let's edit our `tsconfig.json` file and add the `angularCompilerOptions` with `genDir` pointing to the folder where we + want `ng-xi18n` to generate the file. + ++makeExample('i18n/ts-snippets/i18n.config.snippets.ts', 'tsconfig2')(format=".") + +:marked + The generated `messages.xlf` file uses by default the format `XML Localisation Interchange File Format` (XLIFF, version 1.2). + + `ng-x18n` and Angular 2 also support the `XML Message Bundle`(XMB) format. We can switch to this format by setting + the cli option `i18nFormat` to the value `xmb`: + +code-example(language="sh"). + ./node_modules/.bin/ng-xi18n --i18nFormat=xmb + +a(id="translate") +.l-main-section +:marked + ### Translate messages + + Now that we have generated a `messages` file, we have to make a copy by language that we want to support. + + If we want to support french for example, we can copy the file as `messages.fr`. We can start translating the messages, + or send those files to our translators. + + You can find a list of editors supporting the xlf format [here](https://en.wikipedia.org/wiki/XLIFF#Editors). + +.alert.is-helpful + :marked + If we choose the default `XLIFF` format, we have to add the translations into the `` elements of our `messages.xlf` + file, such as: `Bonjour i18n`. + +:marked + Whenever we add new messages in our application, we should run `ng-xi18n` again, and copy the added translations into + each of our localization files. + +.alert.is-helpful + :marked + Using a versionning system such as `GIT` can help us find out easily what new translations have been generated by + the messages extractor. + +a(id="use-jit") +.l-main-section +:marked + ### Use translations with the JiT approach + + Now that we have a localized file, we can tell Angular 2 to use it for all of our elements that have the `i18n` directive attribute. + + Angular 2 understand `xlf` and `xmb` formats, but we have to provide these message into our application. + To do that we will have to define a few providers at bootstrap time. + + Let's say that we have the following bootstrap file: + ++makeExample('i18n/ts-snippets/i18n.config.snippets.ts', 'bootstrap')(format=".") + +:marked + We have to provide three values: `TRANSLATIONS`, `TRANSLATIONS_FORMAT` and `LOCALE_ID`: + * `TRANSLATIONS` is a string containing the content of our `messages` file for the chosen localization. + * `TRANSLATIONS_FORMAT` is either `xlf` or `xmb` depending on the format of our `messages` file. + * `LOCALE_ID` is a string representing the locale of our chosen language. + + For our `messages.fr.xlf` file, we would change the bootstrap like this: + ++makeExample('i18n/ts-snippets/i18n.config.snippets.ts', 'bootstrap-i18n')(format=".") + +:marked + Since TypeScript is unable to import an `xlf` file, we have to create a `.ts` file that exports the content of our + `messages.fr.xlf` file. + + ++makeExample('i18n/ts-snippets/i18n.config.snippets.ts', 'messages-ts')(format=".") + +.alert.is-helpful + :marked + If you use Webpack you can use the [raw loader](https://github.com/webpack/raw-loader) to import your translations + file directly like this: `const TRANSLATION = require("raw!./i18n/messages.fr.xlf");` + +:marked + That's it, our application is now internationalized! Angular 2 will replace the content of our elements using + the `i18n` attribute directive with the french translations that we provided at bootstrap. + +.alert.is-important + :marked + Angular 2 is focused on providing the best AoT approach as possible which means that even if you can use i18n with the + JiT approach, the mecanism behind i18n in Angular 2 requires a full reload to change the language, you won't be able + to do it at runtime. + +a(id="use-aot") +.l-main-section +:marked + ### Use translations with the AoT approach + + Using the AoT approach requires a little bit of setup to make the `ngc` compiler work. Refer to the + [AoT cookbook](../cookbook/aot-compiler.html) to learn more about it. + + Once our project is ngc-ready, we will use `ngc` to compile a version of our application per locale. To do that + we will add three arguments to the cli command: + * `--i18nFile`: the path to our localization file + * `--locale`: the name of the locale + * `--i18nFormat`: the format of our localization file + + If we want to generate precompiled files for our french translations, we will use: + +code-example(language="sh"). + ngc --i18nFile=./src/i18n/messages.fr.xlf --locale=fr --i18nFormat=xlf + +.alert.is-helpful + :marked + Since you're supposed to generate precompiled file for each locale, you should probably use different `tsconfig.json` + files with a different `genDir` for each, and different npm commands pointing to each locale. + + You could also write a script that directly calls the `CodeGenerator` class (exported by the package `@angular/compiler-cli`) + for each locale. + +:marked + That's all that we have to do, the `ngc` compiler will replace the content of our elements using the i18n attribute + directive with our translations in the AoT precompiled files. From cb7225efbf9e22431f41c970f8a49c527cc79bae Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jesu=CC=81s=20Rodri=CC=81guez?= Date: Wed, 14 Sep 2016 18:32:01 +0200 Subject: [PATCH 02/21] Jesus' tweaks --- .../{e2e-spec.ts => e2e-spec.ts.disabled} | 0 .../i18n/ts-snippets/i18n.config.snippets.ts | 68 ++++++------------- public/docs/ts/latest/guide/_data.json | 10 +-- public/docs/ts/latest/guide/i18n.jade | 28 ++++---- 4 files changed, 39 insertions(+), 67 deletions(-) rename public/docs/_examples/i18n/{e2e-spec.ts => e2e-spec.ts.disabled} (100%) diff --git a/public/docs/_examples/i18n/e2e-spec.ts b/public/docs/_examples/i18n/e2e-spec.ts.disabled similarity index 100% rename from public/docs/_examples/i18n/e2e-spec.ts rename to public/docs/_examples/i18n/e2e-spec.ts.disabled diff --git a/public/docs/_examples/i18n/ts-snippets/i18n.config.snippets.ts b/public/docs/_examples/i18n/ts-snippets/i18n.config.snippets.ts index 34b8b04c7c..035f9e1e9b 100644 --- a/public/docs/_examples/i18n/ts-snippets/i18n.config.snippets.ts +++ b/public/docs/_examples/i18n/ts-snippets/i18n.config.snippets.ts @@ -13,15 +13,15 @@ // #docregion i18n-plural-pipe @Component({ - selector: 'app', + selector: 'my-app', template: `
{{ messages.length | i18nPlural: messageMapping }}
- `, + ` }) -class MyApp { - messages: any[]; +export class AppComponent { + messages: string[]; messageMapping: {[k:string]: string} = { '=0': 'No messages.', '=1': 'One message.', @@ -32,16 +32,16 @@ class MyApp { // #docregion i18n-select-pipe @Component({ - selector: 'app', + selector: 'my-app', template: `
- {{ gender | i18nSelect: inviteMap }} + {{ gender | i18nSelect: genderMap }}
- `, + ` }) -class MyApp { - gender: string = 'male'; - inviteMap: any = { +export class AppComponent { + gender = 'male'; + genderMap = { 'male': 'Invite him.', 'female': 'Invite her.', 'other': 'Invite them.' @@ -49,62 +49,39 @@ class MyApp { } // #enddocregion i18n-select-pipe -// #docregion tsconfig1 +// #docregion tsconfig { "compilerOptions": { - "emitDecoratorMetadata": true, - "experimentalDecorators": true, "target": "es5", "module": "commonjs", - "outDir": "./dist/out-tsc" - }, - "files": [ - "./src/main.ts" - ] -} -// #enddocregion tsconfig1 - -// #docregion tsconfig2 -{ - "compilerOptions": { + "moduleResolution": "node", + "sourceMap": true, "emitDecoratorMetadata": true, "experimentalDecorators": true, - "target": "es5", - "module": "commonjs", - "outDir": "./dist/out-tsc" + "removeComments": false, + "noImplicitAny": true, + "suppressImplicitAnyIndexErrors": true }, - "files": [ - "./src/main.ts" - ], "angularCompilerOptions": { - "genDir": "./src/i18n" + "genDir": "./app/i18n" } } -// #enddocregion tsconfig2 +// #enddocregion tsconfig // #docregion bootstrap import { platformBrowserDynamic } from '@angular/platform-browser-dynamic'; -import { enableProdMode } from '@angular/core'; -import { environment } from './environments/environment'; -import { AppModule } from './app/'; -if (environment.production) { - enableProdMode(); -} +import { AppModule } from './app.module'; platformBrowserDynamic().bootstrapModule(AppModule); // #enddocregion bootstrap // #docregion bootstrap-i18n import { platformBrowserDynamic } from '@angular/platform-browser-dynamic'; -import { enableProdMode, TRANSLATIONS, TRANSLATIONS_FORMAT, LOCALE_ID } from '@angular/core'; -import { environment } from './environments/environment'; -import { AppModule } from './app/'; -import { TRANSLATION } from './i18n/messages.fr'; +import { TRANSLATIONS, TRANSLATIONS_FORMAT, LOCALE_ID } from '@angular/core'; -if (environment.production) { - enableProdMode(); -} +import { AppModule } from './app.module'; +import { TRANSLATION } from './i18n/messages.fr'; // Compile using french translations platformBrowserDynamic().bootstrapModule( @@ -119,7 +96,6 @@ platformBrowserDynamic().bootstrapModule( ); // #enddocregion bootstrap-i18n - // #docregion messages-ts export const TRANSLATION = ` diff --git a/public/docs/ts/latest/guide/_data.json b/public/docs/ts/latest/guide/_data.json index 333e9737a0..a36a4e0f1b 100644 --- a/public/docs/ts/latest/guide/_data.json +++ b/public/docs/ts/latest/guide/_data.json @@ -105,6 +105,11 @@ "intro": "Talk to a remote server with an HTTP Client." }, + "i18n": { + "title": "Internationalization (i18n)", + "intro": "Easily translate your website into multiple languages" + }, + "lifecycle-hooks": { "title": "Lifecycle Hooks", "intro": "Angular calls lifecycle hook methods on directives and components as it creates, changes, and destroys them." @@ -153,10 +158,5 @@ "webpack": { "title": "Webpack: an introduction", "intro": "Create your Angular 2 applications with a Webpack based tooling" - }, - - "i18n": { - "title": "Internationalization (i18n)", - "intro": "Easily translate your website into multiple languages" } } diff --git a/public/docs/ts/latest/guide/i18n.jade b/public/docs/ts/latest/guide/i18n.jade index 814609ee11..986c796cfd 100644 --- a/public/docs/ts/latest/guide/i18n.jade +++ b/public/docs/ts/latest/guide/i18n.jade @@ -91,7 +91,7 @@ a(id="i18n-directive") :marked ### i18n directive - The i18n directive is what tells Angular where it should inject the translations. + The `i18n` directive is what tells Angular where it should inject the translations. It is used by both the JiT and the AoT approaches. We simply add the attribute `i18n` to an element and the content string will be replaced when necessary. @@ -128,7 +128,7 @@ a(id="i18n-plural-pipe") .alert.is-important :marked - The plural pipe is not yet supported by the ng-xi18n messages extractor. + The ng-xi18n messages extractor doesn't support the plural pipe right now. a(id="i18n-select-pipe") @@ -144,7 +144,7 @@ a(id="i18n-select-pipe") +makeExample('i18n/ts-snippets/i18n.config.snippets.ts', 'i18n-select-pipe')(format=".") .alert.is-important :marked - The select pipe is not yet supported by the ng-xi18n messages extractor. + The ng-xi18n messages extractor doesn't support the select pipe right now. a(id="extract") @@ -163,14 +163,15 @@ a(id="ng-xi18n") To use it, the first thing that we have to do is to install it: code-example(language="sh"). - npm install @angular/compiler-cli --save + npm install @angular/compiler-cli @angular/platform-server typescript@2.0.2 --save :marked - Like `ngc`, `ng-xi18n` is based on `tsc`, the TypeScript compiler. It uses the file `tsconfig.json` to determine where - are our files. We have to make sure that we have defined the parameter `files` so that it knows what is the entry point - of our application. + Like `ngc`, `ng-xi18n` is based on `tsc`, the TypeScript compiler. -+makeExample('i18n/ts-snippets/i18n.config.snippets.ts', 'tsconfig1')(format=".") + Let's edit our `tsconfig.json` file and add the `angularCompilerOptions` with `genDir` pointing to the folder where we + want `ng-xi18n` to generate the file. + ++makeExample('i18n/ts-snippets/i18n.config.snippets.ts', 'tsconfig')(format=".") :marked We can then use the `ng-xi18n` binary to generate a file named `messages.xlf` at the root of our application. @@ -187,11 +188,6 @@ code-example(language="sh"). :marked If we want to generate this `messages.xlf` file somewhere in particular, `ng-xi18n` uses the same parameters as `ngc`. - - Let's edit our `tsconfig.json` file and add the `angularCompilerOptions` with `genDir` pointing to the folder where we - want `ng-xi18n` to generate the file. - -+makeExample('i18n/ts-snippets/i18n.config.snippets.ts', 'tsconfig2')(format=".") :marked The generated `messages.xlf` file uses by default the format `XML Localisation Interchange File Format` (XLIFF, version 1.2). @@ -225,7 +221,7 @@ a(id="translate") .alert.is-helpful :marked - Using a versionning system such as `GIT` can help us find out easily what new translations have been generated by + Using a versioning system such as `GIT` can help us find out easily what new translations have been generated by the messages extractor. a(id="use-jit") @@ -238,7 +234,7 @@ a(id="use-jit") Angular 2 understand `xlf` and `xmb` formats, but we have to provide these message into our application. To do that we will have to define a few providers at bootstrap time. - Let's say that we have the following bootstrap file: + Having the following bootstrap file: +makeExample('i18n/ts-snippets/i18n.config.snippets.ts', 'bootstrap')(format=".") @@ -291,7 +287,7 @@ a(id="use-aot") If we want to generate precompiled files for our french translations, we will use: code-example(language="sh"). - ngc --i18nFile=./src/i18n/messages.fr.xlf --locale=fr --i18nFormat=xlf + ngc --i18nFile=./app/i18n/messages.fr.xlf --locale=fr --i18nFormat=xlf .alert.is-helpful :marked From 3552db7b489d46ce6deabc75baad61d5d924afe7 Mon Sep 17 00:00:00 2001 From: Ward Bell Date: Wed, 14 Sep 2016 10:32:53 -0700 Subject: [PATCH 03/21] docs(i18n): fix _data.json --- public/docs/ts/latest/guide/_data.json | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/public/docs/ts/latest/guide/_data.json b/public/docs/ts/latest/guide/_data.json index a36a4e0f1b..704cc8b5bf 100644 --- a/public/docs/ts/latest/guide/_data.json +++ b/public/docs/ts/latest/guide/_data.json @@ -106,8 +106,8 @@ }, "i18n": { - "title": "Internationalization (i18n)", - "intro": "Easily translate your website into multiple languages" + "title": "Internationalization", + "intro": "Translate your application into multiple languages" }, "lifecycle-hooks": { From b3e44c88dd8cd6b37da64e56d275e058314922fd Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jesu=CC=81s=20Rodri=CC=81guez?= Date: Wed, 14 Sep 2016 21:34:59 +0200 Subject: [PATCH 04/21] chore: remove typescript installation instruction --- public/docs/ts/latest/guide/i18n.jade | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/public/docs/ts/latest/guide/i18n.jade b/public/docs/ts/latest/guide/i18n.jade index 986c796cfd..8c3b4a0bb1 100644 --- a/public/docs/ts/latest/guide/i18n.jade +++ b/public/docs/ts/latest/guide/i18n.jade @@ -163,7 +163,7 @@ a(id="ng-xi18n") To use it, the first thing that we have to do is to install it: code-example(language="sh"). - npm install @angular/compiler-cli @angular/platform-server typescript@2.0.2 --save + npm install @angular/compiler-cli @angular/platform-server --save :marked Like `ngc`, `ng-xi18n` is based on `tsc`, the TypeScript compiler. From 17ed3cab55d03daaa6215eb971601953ecfed1e7 Mon Sep 17 00:00:00 2001 From: Filipe Silva Date: Fri, 23 Sep 2016 03:13:26 +0100 Subject: [PATCH 05/21] angular 2 -> angular --- public/docs/ts/latest/guide/i18n.jade | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/public/docs/ts/latest/guide/i18n.jade b/public/docs/ts/latest/guide/i18n.jade index 8c3b4a0bb1..6029bd01e0 100644 --- a/public/docs/ts/latest/guide/i18n.jade +++ b/public/docs/ts/latest/guide/i18n.jade @@ -15,7 +15,7 @@ include ../_util-fns * [JiT](#jit) * [AoT](#aot) - [Angular 2 and i18n](#angular2-i18n) + [Angular and i18n](#angular2-i18n) * [i18n directive](#i18n-directive) * [i18n plural pipe](#i18n-plural-pipe) @@ -70,7 +70,7 @@ a(id="aot") * No information/state is (typically) lost. The user is presumably changing the language because he could not understand the earlier language. This means that he doesn't have unsaved information in the application. * Tools support: the strings to translate are easily extracted from our templates. - The resulting translations are in a generic format that can be consumed both by Angular 2 and one of the many translation softwares available. + The resulting translations are in a generic format that can be consumed both by Angular and one of the many translation softwares available. * Cannot support multiple languages in the same application view. * We have to reload the app to change the language. * Extra server side support is needed: Since we generate different precompiled files for each language, the server must perform cookie/user agent analysis @@ -81,7 +81,7 @@ a(id="aot") a(id="angular2-i18n") .l-main-section :marked - ## Angular 2 and i18n + ## Angular and i18n Whatever approach we decide to use, we must update our templates to define which strings will be translated. @@ -192,7 +192,7 @@ code-example(language="sh"). :marked The generated `messages.xlf` file uses by default the format `XML Localisation Interchange File Format` (XLIFF, version 1.2). - `ng-x18n` and Angular 2 also support the `XML Message Bundle`(XMB) format. We can switch to this format by setting + `ng-x18n` and Angular also support the `XML Message Bundle`(XMB) format. We can switch to this format by setting the cli option `i18nFormat` to the value `xmb`: code-example(language="sh"). @@ -229,9 +229,9 @@ a(id="use-jit") :marked ### Use translations with the JiT approach - Now that we have a localized file, we can tell Angular 2 to use it for all of our elements that have the `i18n` directive attribute. + Now that we have a localized file, we can tell Angular to use it for all of our elements that have the `i18n` directive attribute. - Angular 2 understand `xlf` and `xmb` formats, but we have to provide these message into our application. + Angular understands `xlf` and `xmb` formats, but we have to provide these message into our application. To do that we will have to define a few providers at bootstrap time. Having the following bootstrap file: @@ -261,13 +261,13 @@ a(id="use-jit") file directly like this: `const TRANSLATION = require("raw!./i18n/messages.fr.xlf");` :marked - That's it, our application is now internationalized! Angular 2 will replace the content of our elements using + That's it, our application is now internationalized! Angular will replace the content of our elements using the `i18n` attribute directive with the french translations that we provided at bootstrap. .alert.is-important :marked - Angular 2 is focused on providing the best AoT approach as possible which means that even if you can use i18n with the - JiT approach, the mecanism behind i18n in Angular 2 requires a full reload to change the language, you won't be able + Angular is focused on providing the best AoT approach as possible which means that even if you can use i18n with the + JiT approach, the mecanism behind i18n in Angular requires a full reload to change the language, you won't be able to do it at runtime. a(id="use-aot") From dc9bd4d0a4bba7f52c0aa178cd69bcef72dce772 Mon Sep 17 00:00:00 2001 From: Filipe Silva Date: Sat, 24 Sep 2016 01:27:58 +0100 Subject: [PATCH 06/21] add base jit app --- public/docs/_examples/i18n/ts/.gitignore | 6 +++ .../_examples/i18n/ts/app/app.component.html | 23 ++++++++++++ .../_examples/i18n/ts/app/app.component.ts | 27 ++++++++++++++ .../docs/_examples/i18n/ts/app/app.module.ts | 13 +++++++ public/docs/_examples/i18n/ts/app/main.ts | 7 ++++ .../_examples/i18n/ts/example-config.json | 0 public/docs/_examples/i18n/ts/index.html | 37 +++++++++++++++++++ .../docs/_examples/i18n/ts/tsconfig-aot.json | 16 ++++++++ public/docs/ts/latest/guide/i18n.jade | 20 +++++----- 9 files changed, 140 insertions(+), 9 deletions(-) create mode 100644 public/docs/_examples/i18n/ts/.gitignore create mode 100644 public/docs/_examples/i18n/ts/app/app.component.html create mode 100644 public/docs/_examples/i18n/ts/app/app.component.ts create mode 100644 public/docs/_examples/i18n/ts/app/app.module.ts create mode 100644 public/docs/_examples/i18n/ts/app/main.ts create mode 100644 public/docs/_examples/i18n/ts/example-config.json create mode 100644 public/docs/_examples/i18n/ts/index.html create mode 100644 public/docs/_examples/i18n/ts/tsconfig-aot.json diff --git a/public/docs/_examples/i18n/ts/.gitignore b/public/docs/_examples/i18n/ts/.gitignore new file mode 100644 index 0000000000..8357331dc7 --- /dev/null +++ b/public/docs/_examples/i18n/ts/.gitignore @@ -0,0 +1,6 @@ +**/*.ngfactory.ts +**/*.metadata.json +**/messages.xlf +dist +!app/tsconfig.json +!rollup.js \ No newline at end of file diff --git a/public/docs/_examples/i18n/ts/app/app.component.html b/public/docs/_examples/i18n/ts/app/app.component.html new file mode 100644 index 0000000000..b751eaec3f --- /dev/null +++ b/public/docs/_examples/i18n/ts/app/app.component.html @@ -0,0 +1,23 @@ + +

Hello i18n

+ + + +

Hello i18n

+ + + +

Hello i18n

+ + + +
+ {{ messages.length | i18nPlural: messageMapping }} +
+ + + +
+ {{ gender | i18nSelect: genderMap }} +
+ \ No newline at end of file diff --git a/public/docs/_examples/i18n/ts/app/app.component.ts b/public/docs/_examples/i18n/ts/app/app.component.ts new file mode 100644 index 0000000000..ff6035201a --- /dev/null +++ b/public/docs/_examples/i18n/ts/app/app.component.ts @@ -0,0 +1,27 @@ +// #docregion +import { Component } from '@angular/core'; + +@Component({ + moduleId: module.id, + selector: 'my-app', + templateUrl: './app.component.html' +}) +export class AppComponent { + // #docregion i18n-plural-pipe + messages: string[] = []; + messageMapping: {[k: string]: string} = { + '=0': 'No messages.', + '=1': 'One message.', + 'other': '# messages.' + }; + // #enddocregion i18n-plural-pipe + // #docregion i18n-select-pipe + gender = 'male'; + genderMap = { + 'male': 'Invite him.', + 'female': 'Invite her.', + 'other': 'Invite them.' + }; + // #enddocregion i18n-select-pipe +} + diff --git a/public/docs/_examples/i18n/ts/app/app.module.ts b/public/docs/_examples/i18n/ts/app/app.module.ts new file mode 100644 index 0000000000..a8b40a7650 --- /dev/null +++ b/public/docs/_examples/i18n/ts/app/app.module.ts @@ -0,0 +1,13 @@ +// #docregion +import { NgModule } from '@angular/core'; +import { BrowserModule } from '@angular/platform-browser'; + +import { AppComponent } from './app.component'; + +@NgModule({ + imports: [ BrowserModule ], + declarations: [ AppComponent ], + bootstrap: [ AppComponent ] +}) + +export class AppModule { } diff --git a/public/docs/_examples/i18n/ts/app/main.ts b/public/docs/_examples/i18n/ts/app/main.ts new file mode 100644 index 0000000000..e11324f519 --- /dev/null +++ b/public/docs/_examples/i18n/ts/app/main.ts @@ -0,0 +1,7 @@ +// #docregion +import { platformBrowserDynamic } from '@angular/platform-browser-dynamic'; + +import { AppModule } from './app.module'; + +const platform = platformBrowserDynamic(); +platform.bootstrapModule(AppModule); diff --git a/public/docs/_examples/i18n/ts/example-config.json b/public/docs/_examples/i18n/ts/example-config.json new file mode 100644 index 0000000000..e69de29bb2 diff --git a/public/docs/_examples/i18n/ts/index.html b/public/docs/_examples/i18n/ts/index.html new file mode 100644 index 0000000000..4ee082433c --- /dev/null +++ b/public/docs/_examples/i18n/ts/index.html @@ -0,0 +1,37 @@ + + + + + Angular QuickStart + + + + + + + + + + + + + + + + + + + + + + + + + + + Loading... + + + diff --git a/public/docs/_examples/i18n/ts/tsconfig-aot.json b/public/docs/_examples/i18n/ts/tsconfig-aot.json new file mode 100644 index 0000000000..3026cf7c95 --- /dev/null +++ b/public/docs/_examples/i18n/ts/tsconfig-aot.json @@ -0,0 +1,16 @@ +{ + "compilerOptions": { + "target": "es5", + "module": "commonjs", + "moduleResolution": "node", + "sourceMap": true, + "emitDecoratorMetadata": true, + "experimentalDecorators": true, + "removeComments": false, + "noImplicitAny": true, + "suppressImplicitAnyIndexErrors": true + }, + "angularCompilerOptions": { + "genDir": "./app/i18n" + } +} diff --git a/public/docs/ts/latest/guide/i18n.jade b/public/docs/ts/latest/guide/i18n.jade index 6029bd01e0..51b41f910a 100644 --- a/public/docs/ts/latest/guide/i18n.jade +++ b/public/docs/ts/latest/guide/i18n.jade @@ -96,18 +96,18 @@ a(id="i18n-directive") We simply add the attribute `i18n` to an element and the content string will be replaced when necessary. -+makeExample('i18n/ts-snippets/i18n.config.snippets.ts', 'i18n-directive')(format=".") ++makeExample('i18n/ts/app/app.component.html', 'i18n-directive', 'app/app.component.html')(format=".") :marked To help the translators, we can add more information about the meaning and context of this string. Simply add a description to the i18n attribute: -+makeExample('i18n/ts-snippets/i18n.config.snippets.ts', 'i18n-directive-desc')(format=".") ++makeExample('i18n/ts/app/app.component.html', 'i18n-directive-desc', 'app/app.component.html')(format=".") :marked We can add some meaning as well, separate the meaning from the description with a pipe `|`: -+makeExample('i18n/ts-snippets/i18n.config.snippets.ts', 'i18n-directive-meaning')(format=".") ++makeExample('i18n/ts/app/app.component.html', 'i18n-directive-meaning', 'app/app.component.html')(format=".") :marked Both the meaning and the description will be extracted by our messages extractor and added to the messages file. @@ -124,7 +124,8 @@ a(id="i18n-plural-pipe") This pipe provides different translations based on a number and on a mapping (which is an object that mimics the [ICU format](http://userguide.icu-project.org/formatparse/messages)): -+makeExample('i18n/ts-snippets/i18n.config.snippets.ts', 'i18n-plural-pipe')(format=".") ++makeExample('i18n/ts/app/app.component.html', 'i18n-plural-pipe', 'app/app.component.html')(format=".") ++makeExample('i18n/ts/app/app.component.ts', 'i18n-plural-pipe', 'app/app.component.ts')(format=".") .alert.is-important :marked @@ -141,7 +142,9 @@ a(id="i18n-select-pipe") It also uses a mapping object that mimics the [ICU format](http://userguide.icu-project.org/formatparse/messages): -+makeExample('i18n/ts-snippets/i18n.config.snippets.ts', 'i18n-select-pipe')(format=".") ++makeExample('i18n/ts/app/app.component.html', 'i18n-select-pipe', 'app/app.component.html')(format=".") ++makeExample('i18n/ts/app/app.component.ts', 'i18n-select-pipe', 'app/app.component.ts')(format=".") + .alert.is-important :marked The ng-xi18n messages extractor doesn't support the select pipe right now. @@ -168,16 +171,15 @@ code-example(language="sh"). :marked Like `ngc`, `ng-xi18n` is based on `tsc`, the TypeScript compiler. - Let's edit our `tsconfig.json` file and add the `angularCompilerOptions` with `genDir` pointing to the folder where we - want `ng-xi18n` to generate the file. + Let's make a copy of our `tsconfig.json` file called `tsconfig-aot.json` and add the `angularCompilerOptions` with `genDir` pointing to the folder where we want `ng-xi18n` to generate the file. -+makeExample('i18n/ts-snippets/i18n.config.snippets.ts', 'tsconfig')(format=".") ++makeExample('i18n/ts/tsconfig-aot.json', null, 'tsconfig-aot.json')(format=".") :marked We can then use the `ng-xi18n` binary to generate a file named `messages.xlf` at the root of our application. code-example(language="sh"). - ./node_modules/.bin/ng-xi18n + ./node_modules/.bin/ng-xi18n -p tsconfig-aot.json .alert.is-helpful :marked From 586f47efdafedb61ec1faa01b528de1cd7c43695 Mon Sep 17 00:00:00 2001 From: Filipe Silva Date: Sat, 24 Sep 2016 02:02:13 +0100 Subject: [PATCH 07/21] wording fixes --- .../_examples/i18n/ts/app/app.component.ts | 2 +- public/docs/ts/latest/guide/i18n.jade | 18 +++++++++--------- 2 files changed, 10 insertions(+), 10 deletions(-) diff --git a/public/docs/_examples/i18n/ts/app/app.component.ts b/public/docs/_examples/i18n/ts/app/app.component.ts index ff6035201a..baa0307399 100644 --- a/public/docs/_examples/i18n/ts/app/app.component.ts +++ b/public/docs/_examples/i18n/ts/app/app.component.ts @@ -11,7 +11,7 @@ export class AppComponent { messages: string[] = []; messageMapping: {[k: string]: string} = { '=0': 'No messages.', - '=1': 'One message.', + 'one': 'One message.', 'other': '# messages.' }; // #enddocregion i18n-plural-pipe diff --git a/public/docs/ts/latest/guide/i18n.jade b/public/docs/ts/latest/guide/i18n.jade index 51b41f910a..fe34a57556 100644 --- a/public/docs/ts/latest/guide/i18n.jade +++ b/public/docs/ts/latest/guide/i18n.jade @@ -17,7 +17,7 @@ include ../_util-fns [Angular and i18n](#angular2-i18n) - * [i18n directive](#i18n-directive) + * [i18n directives](#i18n-directives) * [i18n plural pipe](#i18n-plural-pipe) * [i18n select pipe](#i18n-select-pipe) @@ -86,12 +86,12 @@ a(id="angular2-i18n") Whatever approach we decide to use, we must update our templates to define which strings will be translated. -a(id="i18n-directive") +a(id="i18n-directives") .l-main-section :marked - ### i18n directive + ### i18n directives - The `i18n` directive is what tells Angular where it should inject the translations. + The `i18n` directive is what tells Angular where it should insert the translations. It is used by both the JiT and the AoT approaches. We simply add the attribute `i18n` to an element and the content string will be replaced when necessary. @@ -129,7 +129,7 @@ a(id="i18n-plural-pipe") .alert.is-important :marked - The ng-xi18n messages extractor doesn't support the plural pipe right now. + The ng-xi18n messages extractor doesn't support the plural pipe. a(id="i18n-select-pipe") @@ -147,7 +147,7 @@ a(id="i18n-select-pipe") .alert.is-important :marked - The ng-xi18n messages extractor doesn't support the select pipe right now. + The ng-xi18n messages extractor doesn't support the select pipe. a(id="extract") @@ -194,7 +194,7 @@ code-example(language="sh"). :marked The generated `messages.xlf` file uses by default the format `XML Localisation Interchange File Format` (XLIFF, version 1.2). - `ng-x18n` and Angular also support the `XML Message Bundle`(XMB) format. We can switch to this format by setting + `ng-x18n` and Angular also supports the `XML Message Bundle`(XMB) format. We can switch to this format by setting the cli option `i18nFormat` to the value `xmb`: code-example(language="sh"). @@ -233,7 +233,7 @@ a(id="use-jit") Now that we have a localized file, we can tell Angular to use it for all of our elements that have the `i18n` directive attribute. - Angular understands `xlf` and `xmb` formats, but we have to provide these message into our application. + Angular understands `xlf`,`xlif` and `xtb` formats, but we have to provide these message into our application. To do that we will have to define a few providers at bootstrap time. Having the following bootstrap file: @@ -243,7 +243,7 @@ a(id="use-jit") :marked We have to provide three values: `TRANSLATIONS`, `TRANSLATIONS_FORMAT` and `LOCALE_ID`: * `TRANSLATIONS` is a string containing the content of our `messages` file for the chosen localization. - * `TRANSLATIONS_FORMAT` is either `xlf` or `xmb` depending on the format of our `messages` file. + * `TRANSLATIONS_FORMAT` is either `xlf`, `xlif` or `xtb` depending on the format of our `messages` file. * `LOCALE_ID` is a string representing the locale of our chosen language. For our `messages.fr.xlf` file, we would change the bootstrap like this: From 76848c4c3329fea10aa7a551bde8fc5817724b5b Mon Sep 17 00:00:00 2001 From: Filipe Silva Date: Sat, 24 Sep 2016 02:30:19 +0100 Subject: [PATCH 08/21] add translated jit example --- .../i18n/ts-snippets/i18n.config.snippets.ts | 106 ------------------ .../i18n/ts/app/app.component.1.html | 23 ++++ .../_examples/i18n/ts/app/app.component.html | 16 +-- .../_examples/i18n/ts/app/i18n/messages.fr.ts | 16 +++ public/docs/_examples/i18n/ts/app/main.1.ts | 7 ++ public/docs/_examples/i18n/ts/app/main.ts | 14 ++- public/docs/ts/latest/guide/i18n.jade | 10 +- 7 files changed, 68 insertions(+), 124 deletions(-) delete mode 100644 public/docs/_examples/i18n/ts-snippets/i18n.config.snippets.ts create mode 100644 public/docs/_examples/i18n/ts/app/app.component.1.html create mode 100644 public/docs/_examples/i18n/ts/app/i18n/messages.fr.ts create mode 100644 public/docs/_examples/i18n/ts/app/main.1.ts diff --git a/public/docs/_examples/i18n/ts-snippets/i18n.config.snippets.ts b/public/docs/_examples/i18n/ts-snippets/i18n.config.snippets.ts deleted file mode 100644 index 035f9e1e9b..0000000000 --- a/public/docs/_examples/i18n/ts-snippets/i18n.config.snippets.ts +++ /dev/null @@ -1,106 +0,0 @@ -/* tslint:disable */ -// #docregion i18n-directive -

Hello i18n

-// #enddocregion i18n-directive - -// #docregion i18n-directive-desc -

Hello i18n

-// #enddocregion i18n-directive-desc - -// #docregion i18n-directive-meaning -

Hello i18n

-// #enddocregion i18n-directive-meaning - -// #docregion i18n-plural-pipe -@Component({ - selector: 'my-app', - template: ` -
- {{ messages.length | i18nPlural: messageMapping }} -
- ` -}) -export class AppComponent { - messages: string[]; - messageMapping: {[k:string]: string} = { - '=0': 'No messages.', - '=1': 'One message.', - 'other': '# messages.' - } -} -// #enddocregion i18n-plural-pipe - -// #docregion i18n-select-pipe -@Component({ - selector: 'my-app', - template: ` -
- {{ gender | i18nSelect: genderMap }} -
- ` -}) -export class AppComponent { - gender = 'male'; - genderMap = { - 'male': 'Invite him.', - 'female': 'Invite her.', - 'other': 'Invite them.' - } -} -// #enddocregion i18n-select-pipe - -// #docregion tsconfig -{ - "compilerOptions": { - "target": "es5", - "module": "commonjs", - "moduleResolution": "node", - "sourceMap": true, - "emitDecoratorMetadata": true, - "experimentalDecorators": true, - "removeComments": false, - "noImplicitAny": true, - "suppressImplicitAnyIndexErrors": true - }, - "angularCompilerOptions": { - "genDir": "./app/i18n" - } -} -// #enddocregion tsconfig - -// #docregion bootstrap -import { platformBrowserDynamic } from '@angular/platform-browser-dynamic'; - -import { AppModule } from './app.module'; - -platformBrowserDynamic().bootstrapModule(AppModule); -// #enddocregion bootstrap - -// #docregion bootstrap-i18n -import { platformBrowserDynamic } from '@angular/platform-browser-dynamic'; -import { TRANSLATIONS, TRANSLATIONS_FORMAT, LOCALE_ID } from '@angular/core'; - -import { AppModule } from './app.module'; -import { TRANSLATION } from './i18n/messages.fr'; - -// Compile using french translations -platformBrowserDynamic().bootstrapModule( - AppModule, - { - providers: [ - {provide: TRANSLATIONS, useValue: TRANSLATION}, - {provide: TRANSLATIONS_FORMAT, useValue: 'xlf'}, - {provide: LOCALE_ID, useValue: 'fr'} - ] - } -); -// #enddocregion bootstrap-i18n - -// #docregion messages-ts -export const TRANSLATION = ` - - - ... - - `; -// #enddocregion messages-ts diff --git a/public/docs/_examples/i18n/ts/app/app.component.1.html b/public/docs/_examples/i18n/ts/app/app.component.1.html new file mode 100644 index 0000000000..b751eaec3f --- /dev/null +++ b/public/docs/_examples/i18n/ts/app/app.component.1.html @@ -0,0 +1,23 @@ + +

Hello i18n

+ + + +

Hello i18n

+ + + +

Hello i18n

+ + + +
+ {{ messages.length | i18nPlural: messageMapping }} +
+ + + +
+ {{ gender | i18nSelect: genderMap }} +
+ \ No newline at end of file diff --git a/public/docs/_examples/i18n/ts/app/app.component.html b/public/docs/_examples/i18n/ts/app/app.component.html index b751eaec3f..c83bcf2d28 100644 --- a/public/docs/_examples/i18n/ts/app/app.component.html +++ b/public/docs/_examples/i18n/ts/app/app.component.html @@ -1,23 +1,15 @@ - -

Hello i18n

- - - -

Hello i18n

- -

Hello i18n

-
+

{{ messages.length | i18nPlural: messageMapping }} -

+

-
+

{{ gender | i18nSelect: genderMap }} -

+

\ No newline at end of file diff --git a/public/docs/_examples/i18n/ts/app/i18n/messages.fr.ts b/public/docs/_examples/i18n/ts/app/i18n/messages.fr.ts new file mode 100644 index 0000000000..84a1f122fe --- /dev/null +++ b/public/docs/_examples/i18n/ts/app/i18n/messages.fr.ts @@ -0,0 +1,16 @@ +// #docregion +export const TRANSLATION = ` + + + + + + Hello i18n + Bonjour i18n + An introduction header for this sample + User welcome + + + + +`; diff --git a/public/docs/_examples/i18n/ts/app/main.1.ts b/public/docs/_examples/i18n/ts/app/main.1.ts new file mode 100644 index 0000000000..e11324f519 --- /dev/null +++ b/public/docs/_examples/i18n/ts/app/main.1.ts @@ -0,0 +1,7 @@ +// #docregion +import { platformBrowserDynamic } from '@angular/platform-browser-dynamic'; + +import { AppModule } from './app.module'; + +const platform = platformBrowserDynamic(); +platform.bootstrapModule(AppModule); diff --git a/public/docs/_examples/i18n/ts/app/main.ts b/public/docs/_examples/i18n/ts/app/main.ts index e11324f519..3f4b695d29 100644 --- a/public/docs/_examples/i18n/ts/app/main.ts +++ b/public/docs/_examples/i18n/ts/app/main.ts @@ -1,7 +1,19 @@ // #docregion import { platformBrowserDynamic } from '@angular/platform-browser-dynamic'; +import { TRANSLATIONS, TRANSLATIONS_FORMAT, LOCALE_ID } from '@angular/core'; import { AppModule } from './app.module'; +import { TRANSLATION } from './i18n/messages.fr'; +// Compile using french translations const platform = platformBrowserDynamic(); -platform.bootstrapModule(AppModule); +platform.bootstrapModule( + AppModule, + { + providers: [ + {provide: TRANSLATIONS, useValue: TRANSLATION}, + {provide: TRANSLATIONS_FORMAT, useValue: 'xlf'}, + {provide: LOCALE_ID, useValue: 'fr'} + ] + } +); diff --git a/public/docs/ts/latest/guide/i18n.jade b/public/docs/ts/latest/guide/i18n.jade index fe34a57556..c99915b0b9 100644 --- a/public/docs/ts/latest/guide/i18n.jade +++ b/public/docs/ts/latest/guide/i18n.jade @@ -96,13 +96,13 @@ a(id="i18n-directives") We simply add the attribute `i18n` to an element and the content string will be replaced when necessary. -+makeExample('i18n/ts/app/app.component.html', 'i18n-directive', 'app/app.component.html')(format=".") ++makeExample('i18n/ts/app/app.component.1.html', 'i18n-directive', 'app/app.component.html')(format=".") :marked To help the translators, we can add more information about the meaning and context of this string. Simply add a description to the i18n attribute: -+makeExample('i18n/ts/app/app.component.html', 'i18n-directive-desc', 'app/app.component.html')(format=".") ++makeExample('i18n/ts/app/app.component.1.html', 'i18n-directive-desc', 'app/app.component.html')(format=".") :marked We can add some meaning as well, separate the meaning from the description with a pipe `|`: @@ -238,7 +238,7 @@ a(id="use-jit") Having the following bootstrap file: -+makeExample('i18n/ts-snippets/i18n.config.snippets.ts', 'bootstrap')(format=".") ++makeExample('i18n/ts/app/main.1.ts', null, 'app/main.ts')(format=".") :marked We have to provide three values: `TRANSLATIONS`, `TRANSLATIONS_FORMAT` and `LOCALE_ID`: @@ -248,14 +248,14 @@ a(id="use-jit") For our `messages.fr.xlf` file, we would change the bootstrap like this: -+makeExample('i18n/ts-snippets/i18n.config.snippets.ts', 'bootstrap-i18n')(format=".") ++makeExample('i18n/ts/app/main.ts', null, 'app/main.ts')(format=".") :marked Since TypeScript is unable to import an `xlf` file, we have to create a `.ts` file that exports the content of our `messages.fr.xlf` file. -+makeExample('i18n/ts-snippets/i18n.config.snippets.ts', 'messages-ts')(format=".") ++makeExample('i18n/ts/app/i18n/messages.fr.ts', null, 'app/i18n/messages.fr.ts')(format=".") .alert.is-helpful :marked From 1576c081e3384632808bd1a647dc206662007662 Mon Sep 17 00:00:00 2001 From: Filipe Silva Date: Sat, 24 Sep 2016 03:03:43 +0100 Subject: [PATCH 09/21] add e2e test --- public/docs/_examples/i18n/e2e-spec.ts | 21 +++++++++++++++++++ .../docs/_examples/i18n/e2e-spec.ts.disabled | 19 ----------------- .../_examples/i18n/ts/app/app.component.html | 2 +- .../_examples/i18n/ts/app/i18n/messages.fr.ts | 6 +++--- public/docs/_examples/i18n/ts/index.html | 2 +- 5 files changed, 26 insertions(+), 24 deletions(-) create mode 100644 public/docs/_examples/i18n/e2e-spec.ts delete mode 100644 public/docs/_examples/i18n/e2e-spec.ts.disabled diff --git a/public/docs/_examples/i18n/e2e-spec.ts b/public/docs/_examples/i18n/e2e-spec.ts new file mode 100644 index 0000000000..4d2ddf7524 --- /dev/null +++ b/public/docs/_examples/i18n/e2e-spec.ts @@ -0,0 +1,21 @@ +/// +'use strict'; +describe('i18n E2E Tests', function () { + + beforeEach(function () { + browser.get(''); + }); + + it('should display i18n translated welcome: Bonjour i18n!', function () { + expect(element(by.css('h1')).getText()).toEqual('Bonjour i18n!'); + }); + + it('should display i18nPlural message: No messages.', function () { + expect(element.all(by.css('p')).first().getText()).toEqual('No messages.'); + }); + + it('should display i18nSelect message: Invite him.', function () { + expect(element.all(by.css('p')).last().getText()).toEqual('Invite him.'); + }); + +}); diff --git a/public/docs/_examples/i18n/e2e-spec.ts.disabled b/public/docs/_examples/i18n/e2e-spec.ts.disabled deleted file mode 100644 index 85dbcd8626..0000000000 --- a/public/docs/_examples/i18n/e2e-spec.ts.disabled +++ /dev/null @@ -1,19 +0,0 @@ -/// -'use strict'; -describe('QuickStart E2E Tests', function () { - - let expectedMsg = 'Hello from Angular 2 App with i18n'; - - beforeEach(function () { - browser.get(''); - }); - - it(`should display: ${expectedMsg}`, function () { - expect(element(by.css('h1')).getText()).toEqual(expectedMsg); - }); - - it('should display an image', function () { - expect(element(by.css('img')).isPresent()).toBe(true); - }); - -}); diff --git a/public/docs/_examples/i18n/ts/app/app.component.html b/public/docs/_examples/i18n/ts/app/app.component.html index c83bcf2d28..04aaa7d4dd 100644 --- a/public/docs/_examples/i18n/ts/app/app.component.html +++ b/public/docs/_examples/i18n/ts/app/app.component.html @@ -1,5 +1,5 @@ -

Hello i18n

+

Hello i18n!

diff --git a/public/docs/_examples/i18n/ts/app/i18n/messages.fr.ts b/public/docs/_examples/i18n/ts/app/i18n/messages.fr.ts index 84a1f122fe..449a0e3691 100644 --- a/public/docs/_examples/i18n/ts/app/i18n/messages.fr.ts +++ b/public/docs/_examples/i18n/ts/app/i18n/messages.fr.ts @@ -4,9 +4,9 @@ export const TRANSLATION = ` - - Hello i18n - Bonjour i18n + + Hello i18n! + Bonjour i18n! An introduction header for this sample User welcome diff --git a/public/docs/_examples/i18n/ts/index.html b/public/docs/_examples/i18n/ts/index.html index 4ee082433c..685110c5d1 100644 --- a/public/docs/_examples/i18n/ts/index.html +++ b/public/docs/_examples/i18n/ts/index.html @@ -2,7 +2,7 @@ - Angular QuickStart + Angular i18n example From c48eff3f0eaff3f0505f5b53896f294ba1e239f0 Mon Sep 17 00:00:00 2001 From: Filipe Silva Date: Sat, 24 Sep 2016 03:06:29 +0100 Subject: [PATCH 10/21] add jit plunker support --- public/docs/_examples/i18n/ts/plnkr.json | 9 +++++++++ 1 file changed, 9 insertions(+) create mode 100644 public/docs/_examples/i18n/ts/plnkr.json diff --git a/public/docs/_examples/i18n/ts/plnkr.json b/public/docs/_examples/i18n/ts/plnkr.json new file mode 100644 index 0000000000..598722979b --- /dev/null +++ b/public/docs/_examples/i18n/ts/plnkr.json @@ -0,0 +1,9 @@ +{ + "description": "i18n", + "files": [ + "!**/*.d.ts", + "!**/*.js", + "!**/*.[1].*" + ], + "tags": ["i18n"] +} \ No newline at end of file From a72607656a6d76c3bc6361cc04bba8c77345ccd8 Mon Sep 17 00:00:00 2001 From: Filipe Silva Date: Mon, 26 Sep 2016 11:28:59 +0100 Subject: [PATCH 11/21] remove references to reloading --- public/docs/ts/latest/guide/i18n.jade | 13 ++----------- 1 file changed, 2 insertions(+), 11 deletions(-) diff --git a/public/docs/ts/latest/guide/i18n.jade b/public/docs/ts/latest/guide/i18n.jade index c99915b0b9..9cba3054e5 100644 --- a/public/docs/ts/latest/guide/i18n.jade +++ b/public/docs/ts/latest/guide/i18n.jade @@ -2,8 +2,8 @@ include ../_util-fns :marked With internationalization, also known as i18n, we can display our website in multiple languages. There are two different - approaches to internationalization: with AoT compilation which requires a build step and a full reload when the language changes, - or with JiT which doesn't require a full reload and uses bindings to determine when a translation is needed. + approaches to internationalization: with AoT compilation which requires a build step, + or with JiT uses bindings to determine when a translation is needed. @@ -65,14 +65,11 @@ a(id="aot") The AoT approach relies on precompiling the templates using the `ngc` compiler and then injecting the translations into these files. Its main features are: - * Performance win: by reloading the entire app, there is no need to track and update the bindings/UI that change as a result of the locale change. - * The locale changes so rarely that the cost of the reload is usually incurred only once. * No information/state is (typically) lost. The user is presumably changing the language because he could not understand the earlier language. This means that he doesn't have unsaved information in the application. * Tools support: the strings to translate are easily extracted from our templates. The resulting translations are in a generic format that can be consumed both by Angular and one of the many translation softwares available. * Cannot support multiple languages in the same application view. - * We have to reload the app to change the language. * Extra server side support is needed: Since we generate different precompiled files for each language, the server must perform cookie/user agent analysis to decide which localized version of the application code should be returned to the user. This also causes a cache miss. * The server is now responsible for determining the default localized version to serve. (e.g. cookies / geo-ip / Accept-Language header, etc.) @@ -265,12 +262,6 @@ a(id="use-jit") :marked That's it, our application is now internationalized! Angular will replace the content of our elements using the `i18n` attribute directive with the french translations that we provided at bootstrap. - -.alert.is-important - :marked - Angular is focused on providing the best AoT approach as possible which means that even if you can use i18n with the - JiT approach, the mecanism behind i18n in Angular requires a full reload to change the language, you won't be able - to do it at runtime. a(id="use-aot") .l-main-section From c3e219cc5bc21ffa848d4833c4479d6092b70124 Mon Sep 17 00:00:00 2001 From: Filipe Silva Date: Mon, 26 Sep 2016 11:32:36 +0100 Subject: [PATCH 12/21] remove comparison of server requirements --- public/docs/ts/latest/guide/i18n.jade | 5 ----- 1 file changed, 5 deletions(-) diff --git a/public/docs/ts/latest/guide/i18n.jade b/public/docs/ts/latest/guide/i18n.jade index 9cba3054e5..a15bb71962 100644 --- a/public/docs/ts/latest/guide/i18n.jade +++ b/public/docs/ts/latest/guide/i18n.jade @@ -51,10 +51,6 @@ a(id="jit") * Allows one to support multiple languages in the same view. As an example, a page could display a table showing how the user's advertising message might look in different locales. This is fairly easy to do with this approach since it's fairly simple to have one locale per root node. - * The server is not required to determine the locale from the request – the client side can use cookies, the browser - language, and JS APIs to determine the language. - However, it's still be beneficial for the server to do some of this (e.g. to serve the likely language pack together with the application) - but that can be done at a later stage in development or for production. a(id="aot") @@ -72,7 +68,6 @@ a(id="aot") * Cannot support multiple languages in the same application view. * Extra server side support is needed: Since we generate different precompiled files for each language, the server must perform cookie/user agent analysis to decide which localized version of the application code should be returned to the user. This also causes a cache miss. - * The server is now responsible for determining the default localized version to serve. (e.g. cookies / geo-ip / Accept-Language header, etc.) a(id="angular2-i18n") From e413ae97b9dfb1374ff20027c5bbfc9ef733832d Mon Sep 17 00:00:00 2001 From: Filipe Silva Date: Mon, 26 Sep 2016 11:46:25 +0100 Subject: [PATCH 13/21] replace directive with attribute --- .../i18n/ts/app/app.component.1.html | 12 +++++----- public/docs/ts/latest/guide/i18n.jade | 22 +++++++++---------- 2 files changed, 17 insertions(+), 17 deletions(-) diff --git a/public/docs/_examples/i18n/ts/app/app.component.1.html b/public/docs/_examples/i18n/ts/app/app.component.1.html index b751eaec3f..2d073b3e24 100644 --- a/public/docs/_examples/i18n/ts/app/app.component.1.html +++ b/public/docs/_examples/i18n/ts/app/app.component.1.html @@ -1,14 +1,14 @@ - +

Hello i18n

- + - +

Hello i18n

- + - +

Hello i18n

- +
diff --git a/public/docs/ts/latest/guide/i18n.jade b/public/docs/ts/latest/guide/i18n.jade index a15bb71962..029fc2de17 100644 --- a/public/docs/ts/latest/guide/i18n.jade +++ b/public/docs/ts/latest/guide/i18n.jade @@ -17,7 +17,7 @@ include ../_util-fns [Angular and i18n](#angular2-i18n) - * [i18n directives](#i18n-directives) + * [i18n attribute](#i18n-attribute) * [i18n plural pipe](#i18n-plural-pipe) * [i18n select pipe](#i18n-select-pipe) @@ -40,7 +40,7 @@ a(id="jit") :marked ### Just in time (JiT) approach - The JiT approach relies on providing the translations to our application and binding them to our templates using directives, pipes and interpolations. + The JiT approach relies on providing the translations to our application and binding them to our templates using attribute, pipes and interpolations. Its main features are: * Minimal server side support required: The same version of the application code is served by the server. @@ -78,28 +78,28 @@ a(id="angular2-i18n") Whatever approach we decide to use, we must update our templates to define which strings will be translated. -a(id="i18n-directives") +a(id="i18n-attribute") .l-main-section :marked - ### i18n directives + ### i18n attribute - The `i18n` directive is what tells Angular where it should insert the translations. + The `i18n` attribute is what tells Angular where it should insert the translations. It is used by both the JiT and the AoT approaches. We simply add the attribute `i18n` to an element and the content string will be replaced when necessary. -+makeExample('i18n/ts/app/app.component.1.html', 'i18n-directive', 'app/app.component.html')(format=".") ++makeExample('i18n/ts/app/app.component.1.html', 'i18n-attribute', 'app/app.component.html')(format=".") :marked To help the translators, we can add more information about the meaning and context of this string. Simply add a description to the i18n attribute: -+makeExample('i18n/ts/app/app.component.1.html', 'i18n-directive-desc', 'app/app.component.html')(format=".") ++makeExample('i18n/ts/app/app.component.1.html', 'i18n-attribute-desc', 'app/app.component.html')(format=".") :marked We can add some meaning as well, separate the meaning from the description with a pipe `|`: -+makeExample('i18n/ts/app/app.component.html', 'i18n-directive-meaning', 'app/app.component.html')(format=".") ++makeExample('i18n/ts/app/app.component.1.html', 'i18n-attribute-meaning', 'app/app.component.html')(format=".") :marked Both the meaning and the description will be extracted by our messages extractor and added to the messages file. @@ -223,7 +223,7 @@ a(id="use-jit") :marked ### Use translations with the JiT approach - Now that we have a localized file, we can tell Angular to use it for all of our elements that have the `i18n` directive attribute. + Now that we have a localized file, we can tell Angular to use it for all of our elements that have the `i18n` marker. Angular understands `xlf`,`xlif` and `xtb` formats, but we have to provide these message into our application. To do that we will have to define a few providers at bootstrap time. @@ -256,7 +256,7 @@ a(id="use-jit") :marked That's it, our application is now internationalized! Angular will replace the content of our elements using - the `i18n` attribute directive with the french translations that we provided at bootstrap. + the `i18n` attribute with the french translations that we provided at bootstrap. a(id="use-aot") .l-main-section @@ -287,4 +287,4 @@ code-example(language="sh"). :marked That's all that we have to do, the `ngc` compiler will replace the content of our elements using the i18n attribute - directive with our translations in the AoT precompiled files. + with our translations in the AoT precompiled files. From 94b6ea24b3f9b6b71a4d93524ccf16541b059174 Mon Sep 17 00:00:00 2001 From: Filipe Silva Date: Mon, 26 Sep 2016 11:51:30 +0100 Subject: [PATCH 14/21] explain relevant of meaning in i18n --- public/docs/ts/latest/guide/i18n.jade | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/public/docs/ts/latest/guide/i18n.jade b/public/docs/ts/latest/guide/i18n.jade index 029fc2de17..5c3c0ec2bb 100644 --- a/public/docs/ts/latest/guide/i18n.jade +++ b/public/docs/ts/latest/guide/i18n.jade @@ -97,11 +97,13 @@ a(id="i18n-attribute") +makeExample('i18n/ts/app/app.component.1.html', 'i18n-attribute-desc', 'app/app.component.html')(format=".") :marked - We can add some meaning as well, separate the meaning from the description with a pipe `|`: + We can add some meaning as well, separate the meaning from the description with the `|` character: +makeExample('i18n/ts/app/app.component.1.html', 'i18n-attribute-meaning', 'app/app.component.html')(format=".") :marked + While the same text with the same meaning should have the same translation, + the same text with different meanings can have different translations. Both the meaning and the description will be extracted by our messages extractor and added to the messages file. It will help our translators to translate our application with a better understanding of what our text means. From ce1de168bdeb75fbcafbaa3f9fb2b401458d7e45 Mon Sep 17 00:00:00 2001 From: Filipe Silva Date: Mon, 26 Sep 2016 11:53:58 +0100 Subject: [PATCH 15/21] replace git and specialized translation software for versioning --- public/docs/ts/latest/guide/i18n.jade | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/public/docs/ts/latest/guide/i18n.jade b/public/docs/ts/latest/guide/i18n.jade index 5c3c0ec2bb..3b375c0464 100644 --- a/public/docs/ts/latest/guide/i18n.jade +++ b/public/docs/ts/latest/guide/i18n.jade @@ -217,7 +217,7 @@ a(id="translate") .alert.is-helpful :marked - Using a versioning system such as `GIT` can help us find out easily what new translations have been generated by + Using specialized translation software can help us find out easily what new translations have been generated by the messages extractor. a(id="use-jit") From 89e45d7909b45b4a028519fb212cfec70c2a2ad5 Mon Sep 17 00:00:00 2001 From: Filipe Silva Date: Mon, 26 Sep 2016 11:58:02 +0100 Subject: [PATCH 16/21] remove dynamic language switching --- public/docs/ts/latest/guide/i18n.jade | 2 -- 1 file changed, 2 deletions(-) diff --git a/public/docs/ts/latest/guide/i18n.jade b/public/docs/ts/latest/guide/i18n.jade index 3b375c0464..11aa2b8577 100644 --- a/public/docs/ts/latest/guide/i18n.jade +++ b/public/docs/ts/latest/guide/i18n.jade @@ -48,7 +48,6 @@ a(id="jit") translations in the application code at build time. * Our application must track all the pieces of the UI that need to be updated when the locale changes. In addition, if the new language strings are being loaded over the network, this could take time and the UI needs to indicate this in some way to the user. - * Allows one to support multiple languages in the same view. As an example, a page could display a table showing how the user's advertising message might look in different locales. This is fairly easy to do with this approach since it's fairly simple to have one locale per root node. @@ -65,7 +64,6 @@ a(id="aot") This means that he doesn't have unsaved information in the application. * Tools support: the strings to translate are easily extracted from our templates. The resulting translations are in a generic format that can be consumed both by Angular and one of the many translation softwares available. - * Cannot support multiple languages in the same application view. * Extra server side support is needed: Since we generate different precompiled files for each language, the server must perform cookie/user agent analysis to decide which localized version of the application code should be returned to the user. This also causes a cache miss. From 8b8ccf2206d568dd4ca4221bf87060cae5086de5 Mon Sep 17 00:00:00 2001 From: Filipe Silva Date: Mon, 26 Sep 2016 12:04:58 +0100 Subject: [PATCH 17/21] remove pipe usage --- .../i18n/ts/app/app.component.1.html | 18 +------- .../_examples/i18n/ts/app/app.component.html | 16 +------ .../_examples/i18n/ts/app/app.component.ts | 19 +------- public/docs/ts/latest/guide/i18n.jade | 45 ++----------------- 4 files changed, 7 insertions(+), 91 deletions(-) diff --git a/public/docs/_examples/i18n/ts/app/app.component.1.html b/public/docs/_examples/i18n/ts/app/app.component.1.html index 2d073b3e24..c312da5340 100644 --- a/public/docs/_examples/i18n/ts/app/app.component.1.html +++ b/public/docs/_examples/i18n/ts/app/app.component.1.html @@ -4,20 +4,4 @@

Hello i18n

Hello i18n

- - - -

Hello i18n

- - - -
- {{ messages.length | i18nPlural: messageMapping }} -
- - - -
- {{ gender | i18nSelect: genderMap }} -
- \ No newline at end of file + \ No newline at end of file diff --git a/public/docs/_examples/i18n/ts/app/app.component.html b/public/docs/_examples/i18n/ts/app/app.component.html index 04aaa7d4dd..369aa33952 100644 --- a/public/docs/_examples/i18n/ts/app/app.component.html +++ b/public/docs/_examples/i18n/ts/app/app.component.html @@ -1,15 +1,3 @@ - +

Hello i18n!

- - - -

- {{ messages.length | i18nPlural: messageMapping }} -

- - - -

- {{ gender | i18nSelect: genderMap }} -

- \ No newline at end of file + \ No newline at end of file diff --git a/public/docs/_examples/i18n/ts/app/app.component.ts b/public/docs/_examples/i18n/ts/app/app.component.ts index baa0307399..76c99e60c7 100644 --- a/public/docs/_examples/i18n/ts/app/app.component.ts +++ b/public/docs/_examples/i18n/ts/app/app.component.ts @@ -6,22 +6,5 @@ import { Component } from '@angular/core'; selector: 'my-app', templateUrl: './app.component.html' }) -export class AppComponent { - // #docregion i18n-plural-pipe - messages: string[] = []; - messageMapping: {[k: string]: string} = { - '=0': 'No messages.', - 'one': 'One message.', - 'other': '# messages.' - }; - // #enddocregion i18n-plural-pipe - // #docregion i18n-select-pipe - gender = 'male'; - genderMap = { - 'male': 'Invite him.', - 'female': 'Invite her.', - 'other': 'Invite them.' - }; - // #enddocregion i18n-select-pipe -} +export class AppComponent { } diff --git a/public/docs/ts/latest/guide/i18n.jade b/public/docs/ts/latest/guide/i18n.jade index 11aa2b8577..abc1d672df 100644 --- a/public/docs/ts/latest/guide/i18n.jade +++ b/public/docs/ts/latest/guide/i18n.jade @@ -18,8 +18,6 @@ include ../_util-fns [Angular and i18n](#angular2-i18n) * [i18n attribute](#i18n-attribute) - * [i18n plural pipe](#i18n-plural-pipe) - * [i18n select pipe](#i18n-select-pipe) [Extract and use translations](#extract) @@ -40,7 +38,7 @@ a(id="jit") :marked ### Just in time (JiT) approach - The JiT approach relies on providing the translations to our application and binding them to our templates using attribute, pipes and interpolations. + The JiT approach relies on providing the translations to our application and binding them to our templates using attributes and interpolations. Its main features are: * Minimal server side support required: The same version of the application code is served by the server. @@ -97,50 +95,13 @@ a(id="i18n-attribute") :marked We can add some meaning as well, separate the meaning from the description with the `|` character: -+makeExample('i18n/ts/app/app.component.1.html', 'i18n-attribute-meaning', 'app/app.component.html')(format=".") ++makeExample('i18n/ts/app/app.component.html', 'i18n-attribute-meaning', 'app/app.component.html')(format=".") :marked While the same text with the same meaning should have the same translation, the same text with different meanings can have different translations. Both the meaning and the description will be extracted by our messages extractor and added to the messages file. - It will help our translators to translate our application with a better understanding of what our text means. - - -a(id="i18n-plural-pipe") -.l-main-section -:marked - ### i18n plural pipe - - When we need to pluralize some terms based on values, we can use the plural pipe. - - This pipe provides different translations based on a number and on a mapping (which is an object - that mimics the [ICU format](http://userguide.icu-project.org/formatparse/messages)): - -+makeExample('i18n/ts/app/app.component.html', 'i18n-plural-pipe', 'app/app.component.html')(format=".") -+makeExample('i18n/ts/app/app.component.ts', 'i18n-plural-pipe', 'app/app.component.ts')(format=".") - -.alert.is-important - :marked - The ng-xi18n messages extractor doesn't support the plural pipe. - - -a(id="i18n-select-pipe") -.l-main-section -:marked - ### i18n select pipe - - Just like the plural pipe displays different translations based on a number, the select pipe is used to display different - translations based on a string that matches the current value. - - It also uses a mapping object that mimics the [ICU format](http://userguide.icu-project.org/formatparse/messages): - -+makeExample('i18n/ts/app/app.component.html', 'i18n-select-pipe', 'app/app.component.html')(format=".") -+makeExample('i18n/ts/app/app.component.ts', 'i18n-select-pipe', 'app/app.component.ts')(format=".") - -.alert.is-important - :marked - The ng-xi18n messages extractor doesn't support the select pipe. - + It will help our translators to translate our application with a better understanding of what our text means. a(id="extract") .l-main-section From 635b4e4026eb0da0097c6e76c7f73f8bd2fab9ee Mon Sep 17 00:00:00 2001 From: Filipe Silva Date: Mon, 26 Sep 2016 16:44:38 +0100 Subject: [PATCH 18/21] edit prose --- public/docs/_examples/i18n/e2e-spec.ts | 8 - .../i18n/ts/app/app.component.1.html | 10 +- .../_examples/i18n/ts/app/app.component.html | 1 + public/docs/_examples/i18n/ts/app/main.ts | 2 +- .../_examples/i18n/ts/app/messages.fr.1.ts | 5 + .../i18n/ts/app/{i18n => }/messages.fr.ts | 3 +- public/docs/_examples/i18n/ts/messages.fr.xlf | 13 + .../docs/_examples/i18n/ts/messages.fr.xlf.ts | 15 + public/docs/_examples/i18n/ts/plnkr.json | 3 +- .../docs/_examples/i18n/ts/tsconfig-aot.json | 16 - public/docs/_examples/package.json | 3 +- public/docs/ts/latest/guide/i18n.jade | 278 +++++++++--------- 12 files changed, 192 insertions(+), 165 deletions(-) create mode 100644 public/docs/_examples/i18n/ts/app/messages.fr.1.ts rename public/docs/_examples/i18n/ts/app/{i18n => }/messages.fr.ts (94%) create mode 100644 public/docs/_examples/i18n/ts/messages.fr.xlf create mode 100644 public/docs/_examples/i18n/ts/messages.fr.xlf.ts delete mode 100644 public/docs/_examples/i18n/ts/tsconfig-aot.json diff --git a/public/docs/_examples/i18n/e2e-spec.ts b/public/docs/_examples/i18n/e2e-spec.ts index 4d2ddf7524..138a7c878e 100644 --- a/public/docs/_examples/i18n/e2e-spec.ts +++ b/public/docs/_examples/i18n/e2e-spec.ts @@ -10,12 +10,4 @@ describe('i18n E2E Tests', function () { expect(element(by.css('h1')).getText()).toEqual('Bonjour i18n!'); }); - it('should display i18nPlural message: No messages.', function () { - expect(element.all(by.css('p')).first().getText()).toEqual('No messages.'); - }); - - it('should display i18nSelect message: Invite him.', function () { - expect(element.all(by.css('p')).last().getText()).toEqual('Invite him.'); - }); - }); diff --git a/public/docs/_examples/i18n/ts/app/app.component.1.html b/public/docs/_examples/i18n/ts/app/app.component.1.html index c312da5340..7813de7d31 100644 --- a/public/docs/_examples/i18n/ts/app/app.component.1.html +++ b/public/docs/_examples/i18n/ts/app/app.component.1.html @@ -1,7 +1,11 @@ + +

Hello i18n!

+ + -

Hello i18n

+

Hello i18n!

-

Hello i18n

- \ No newline at end of file +

Hello i18n!

+ diff --git a/public/docs/_examples/i18n/ts/app/app.component.html b/public/docs/_examples/i18n/ts/app/app.component.html index 369aa33952..3469b42e86 100644 --- a/public/docs/_examples/i18n/ts/app/app.component.html +++ b/public/docs/_examples/i18n/ts/app/app.component.html @@ -1,3 +1,4 @@ +

Hello i18n!

\ No newline at end of file diff --git a/public/docs/_examples/i18n/ts/app/main.ts b/public/docs/_examples/i18n/ts/app/main.ts index 3f4b695d29..76801570b0 100644 --- a/public/docs/_examples/i18n/ts/app/main.ts +++ b/public/docs/_examples/i18n/ts/app/main.ts @@ -3,7 +3,7 @@ import { platformBrowserDynamic } from '@angular/platform-browser-dynamic'; import { TRANSLATIONS, TRANSLATIONS_FORMAT, LOCALE_ID } from '@angular/core'; import { AppModule } from './app.module'; -import { TRANSLATION } from './i18n/messages.fr'; +import { TRANSLATION } from './messages.fr'; // Compile using french translations const platform = platformBrowserDynamic(); diff --git a/public/docs/_examples/i18n/ts/app/messages.fr.1.ts b/public/docs/_examples/i18n/ts/app/messages.fr.1.ts new file mode 100644 index 0000000000..5f78563420 --- /dev/null +++ b/public/docs/_examples/i18n/ts/app/messages.fr.1.ts @@ -0,0 +1,5 @@ +// #docregion +export const TRANSLATION = ` + +`; + diff --git a/public/docs/_examples/i18n/ts/app/i18n/messages.fr.ts b/public/docs/_examples/i18n/ts/app/messages.fr.ts similarity index 94% rename from public/docs/_examples/i18n/ts/app/i18n/messages.fr.ts rename to public/docs/_examples/i18n/ts/app/messages.fr.ts index 449a0e3691..c01e1c02bd 100644 --- a/public/docs/_examples/i18n/ts/app/i18n/messages.fr.ts +++ b/public/docs/_examples/i18n/ts/app/messages.fr.ts @@ -2,7 +2,7 @@ export const TRANSLATION = ` - + Hello i18n! @@ -14,3 +14,4 @@ export const TRANSLATION = ` `; + diff --git a/public/docs/_examples/i18n/ts/messages.fr.xlf b/public/docs/_examples/i18n/ts/messages.fr.xlf new file mode 100644 index 0000000000..f6b0094bd9 --- /dev/null +++ b/public/docs/_examples/i18n/ts/messages.fr.xlf @@ -0,0 +1,13 @@ + + + + + + Hello i18n! + + An introduction header for this sample + User welcome + + + + \ No newline at end of file diff --git a/public/docs/_examples/i18n/ts/messages.fr.xlf.ts b/public/docs/_examples/i18n/ts/messages.fr.xlf.ts new file mode 100644 index 0000000000..a8b3923dc8 --- /dev/null +++ b/public/docs/_examples/i18n/ts/messages.fr.xlf.ts @@ -0,0 +1,15 @@ +/* tslint:disable */ +// #docregion + + + + + + Hello i18n! + + An introduction header for this sample + User welcome + + + + \ No newline at end of file diff --git a/public/docs/_examples/i18n/ts/plnkr.json b/public/docs/_examples/i18n/ts/plnkr.json index 598722979b..9886709b1e 100644 --- a/public/docs/_examples/i18n/ts/plnkr.json +++ b/public/docs/_examples/i18n/ts/plnkr.json @@ -3,7 +3,8 @@ "files": [ "!**/*.d.ts", "!**/*.js", - "!**/*.[1].*" + "!**/*.[1].*", + "!**/*.metadata.json" ], "tags": ["i18n"] } \ No newline at end of file diff --git a/public/docs/_examples/i18n/ts/tsconfig-aot.json b/public/docs/_examples/i18n/ts/tsconfig-aot.json deleted file mode 100644 index 3026cf7c95..0000000000 --- a/public/docs/_examples/i18n/ts/tsconfig-aot.json +++ /dev/null @@ -1,16 +0,0 @@ -{ - "compilerOptions": { - "target": "es5", - "module": "commonjs", - "moduleResolution": "node", - "sourceMap": true, - "emitDecoratorMetadata": true, - "experimentalDecorators": true, - "removeComments": false, - "noImplicitAny": true, - "suppressImplicitAnyIndexErrors": true - }, - "angularCompilerOptions": { - "genDir": "./app/i18n" - } -} diff --git a/public/docs/_examples/package.json b/public/docs/_examples/package.json index 7baee8a5a9..693ce2a99d 100644 --- a/public/docs/_examples/package.json +++ b/public/docs/_examples/package.json @@ -20,7 +20,8 @@ "test:webpack": "karma start karma.webpack.conf.js", "build:webpack": "rimraf dist && webpack --config config/webpack.prod.js --bail", "build:cli": "ng build", - "build:aot": "ngc -p tsconfig-aot.json && rollup -c rollup.js" + "build:aot": "ngc -p tsconfig-aot.json && rollup -c rollup.js", + "extract": "ng-xi18n" }, "keywords": [], "author": "", diff --git a/public/docs/ts/latest/guide/i18n.jade b/public/docs/ts/latest/guide/i18n.jade index abc1d672df..55685e5e62 100644 --- a/public/docs/ts/latest/guide/i18n.jade +++ b/public/docs/ts/latest/guide/i18n.jade @@ -1,89 +1,54 @@ include ../_util-fns :marked - With internationalization, also known as i18n, we can display our website in multiple languages. There are two different - approaches to internationalization: with AoT compilation which requires a build step, - or with JiT uses bindings to determine when a translation is needed. - - + With internationalization, also known as i18n, we can display our website in multiple languages. + Angular provides tools to export translation files that translators and work on. + Those finished translations can then be loaded alongside with your application to make it + available to multiple audiences. ## Table of contents - - [Different approaches to internationalization](#approaches-internationalization) - - * [JiT](#jit) - * [AoT](#aot) - - [Angular and i18n](#angular2-i18n) - - * [i18n attribute](#i18n-attribute) - [Extract and use translations](#extract) - + * [Angular and i18n](#angular-i18n) + * [The i18n attribute](#the-i18n-attribute) * [Extract messages with ng-xi18n](#ng-xi18n) * [Translate messages](#translate) - * [Use translations with the JiT approach](#use-jit) - * [Use translations with the AoT approach](#use-aot) + * [Loading translations](#loading-translations) + * [Using JiT](#use-jit) + * [Using AoT](#use-aot) - -.l-main-section - :marked - ## Different approaches to internationalization + **Try it out**. Here's a link to a of the JiT application. -a(id="jit") +a(id="angular-i18n") .l-main-section :marked - ### Just in time (JiT) approach - - The JiT approach relies on providing the translations to our application and binding them to our templates using attributes and interpolations. - - Its main features are: - * Minimal server side support required: The same version of the application code is served by the server. - However, the server must also serve translated message bundles back to the application or have tools that embed all - translations in the application code at build time. - * Our application must track all the pieces of the UI that need to be updated when the locale changes. - In addition, if the new language strings are being loaded over the network, this could take time and the UI needs to indicate this in some way to the user. - As an example, a page could display a table showing how the user's advertising message might look in different locales. - This is fairly easy to do with this approach since it's fairly simple to have one locale per root node. + ## Angular and i18n + Angular allows us to replace text in our application with the translation of our choice. -a(id="aot") -.l-main-section -:marked - ### Ahead of time (AoT) compilation approach - - The AoT approach relies on precompiling the templates using the `ngc` compiler and then injecting the translations into these files. - - Its main features are: - * No information/state is (typically) lost. The user is presumably changing the language because he could not understand the earlier language. - This means that he doesn't have unsaved information in the application. - * Tools support: the strings to translate are easily extracted from our templates. - The resulting translations are in a generic format that can be consumed both by Angular and one of the many translation softwares available. - * Extra server side support is needed: Since we generate different precompiled files for each language, the server must perform cookie/user agent analysis - to decide which localized version of the application code should be returned to the user. This also causes a cache miss. - + We would usually start with a working application that already has text in a single language. + We then we extract from our app a translation file that translators can load on their translation software to work on the translation. + Finally we use their translation on our app to override the original text. + + We can then build the application for each language we need, and deploy each translated application to it's own server. -a(id="angular2-i18n") -.l-main-section -:marked - ## Angular and i18n - - Whatever approach we decide to use, we must update our templates to define which strings will be translated. - -a(id="i18n-attribute") +a(id="the-i18n-attribute") .l-main-section :marked ### i18n attribute The `i18n` attribute is what tells Angular where it should insert the translations. - It is used by both the JiT and the AoT approaches. - - We simply add the attribute `i18n` to an element and the content string will be replaced when necessary. - + + We'll start with a simple greeting in a `

` tag: + ++makeExample('i18n/ts/app/app.component.1.html', 'greeting', 'app/app.component.html')(format=".") + +:marked + We simply add the attribute `i18n` to our tag to mark it as a translation point. + +makeExample('i18n/ts/app/app.component.1.html', 'i18n-attribute', 'app/app.component.html')(format=".") :marked @@ -99,116 +64,157 @@ a(id="i18n-attribute") :marked While the same text with the same meaning should have the same translation, - the same text with different meanings can have different translations. + the same text with *different meanings* can have different translations. Both the meaning and the description will be extracted by our messages extractor and added to the messages file. - It will help our translators to translate our application with a better understanding of what our text means. - -a(id="extract") -.l-main-section -:marked - ## Extract and use translations + This will help our translators to translate our application with a better understanding of what our text means. + + a(id="ng-xi18n") .l-main-section :marked ### Extract messages with ng-xi18n - Now that our templates have been updated to support i18n translations, we can use the `ng-xi18n` messages extractor. - This cli tool is based on `ngc`, and is available in the `@angular/compiler-cli` npm package. + Now that our template has been updated to support i18n translations, we can use the `ng-xi18n` messages extractor. + + This CLI tool is based on `ngc`, and is available in the `@angular/compiler-cli` npm package. + You can read more about `ngc` on the [AoT cookbook](../cookbook/aot-compiler.html). - To use it, the first thing that we have to do is to install it: + To use it, the first thing that we have to do is to install it and it's `platform-server` peer dependency: code-example(language="sh"). npm install @angular/compiler-cli @angular/platform-server --save :marked - Like `ngc`, `ng-xi18n` is based on `tsc`, the TypeScript compiler. - - Let's make a copy of our `tsconfig.json` file called `tsconfig-aot.json` and add the `angularCompilerOptions` with `genDir` pointing to the folder where we want `ng-xi18n` to generate the file. - -+makeExample('i18n/ts/tsconfig-aot.json', null, 'tsconfig-aot.json')(format=".") - -:marked - We can then use the `ng-xi18n` binary to generate a file named `messages.xlf` at the root of our application. + Like `ngc`, `ng-xi18n` is based on `tsc`, the TypeScript compiler. + We can use it to generate our transfile file at the root of our project: code-example(language="sh"). - ./node_modules/.bin/ng-xi18n -p tsconfig-aot.json + ./node_modules/.bin/ng-xi18n + +:marked + The translation file is generated by default in the format `XML Localisation Interchange File Format` (XLIFF, version 1.2). + + `ng-x18n` and Angular also supports the `XML Message Bundle`(XMB) format. We can switch to this + format by adding the `--i18nFormat=xmb` to our command. .alert.is-helpful :marked It is considered good practice to create a new npm command that will be used to run `ng-xi18n`. - Edit package.json and add the following command in the `scripts` property: `"extract": "ng-xi18n"`. + Edit `package.json` and add the following command in the `scripts` property: `"extract": "ng-xi18n"`. We can now generate our translations using the command `npm run extract`. -:marked - If we want to generate this `messages.xlf` file somewhere in particular, `ng-xi18n` uses the same parameters as `ngc`. - -:marked - The generated `messages.xlf` file uses by default the format `XML Localisation Interchange File Format` (XLIFF, version 1.2). - - `ng-x18n` and Angular also supports the `XML Message Bundle`(XMB) format. We can switch to this format by setting - the cli option `i18nFormat` to the value `xmb`: - -code-example(language="sh"). - ./node_modules/.bin/ng-xi18n --i18nFormat=xmb a(id="translate") .l-main-section :marked - ### Translate messages + ### Translate le message - Now that we have generated a `messages` file, we have to make a copy by language that we want to support. + Now that we have generated a `./messages.xlf` file we could edit it, or send it to + translators to edit, using one of the many editors that support `xlf`. + You can find a list of editors [here](https://en.wikipedia.org/wiki/XLIFF#Editors). - If we want to support french for example, we can copy the file as `messages.fr`. We can start translating the messages, - or send those files to our translators. - - You can find a list of editors supporting the xlf format [here](https://en.wikipedia.org/wiki/XLIFF#Editors). - -.alert.is-helpful - :marked - If we choose the default `XLIFF` format, we have to add the translations into the `` elements of our `messages.xlf` - file, such as: `Bonjour i18n`. - -:marked - Whenever we add new messages in our application, we should run `ng-xi18n` again, and copy the added translations into - each of our localization files. + For the sake of simplicity, we will make our French by editing the translation file manually in our text editor. + + Make a copy of `messages.xlf` called `messages.fr.xlf`, open it and find the following section: + + ``` + + Hello i18n! + + An introduction header for this sample + User welcome + + ``` + + This XML element represents the translation of our header tag. + You might have a different string in `id="af2ccf4b5dba59616e92cf1531505af02da8f6d2"`, this is normal. + + Replace `` with `Bonjour i18n!` to add our French translation. + That's all for our french translation! .alert.is-helpful :marked + Whenever we add new messages - or edit existing ones - in our application, we have to repeat this process. + Using specialized translation software can help us find out easily what new translations have been generated by the messages extractor. -a(id="use-jit") + +a(id="loading-translations") .l-main-section :marked - ### Use translations with the JiT approach - + ## Loading translations + Now that we have a localized file, we can tell Angular to use it for all of our elements that have the `i18n` marker. Angular understands `xlf`,`xlif` and `xtb` formats, but we have to provide these message into our application. - To do that we will have to define a few providers at bootstrap time. - - Having the following bootstrap file: + + However, our paths diverge depending on whether we use JiT or AoT: -+makeExample('i18n/ts/app/main.1.ts', null, 'app/main.ts')(format=".") + * if we are using Just-in-Time compilation, we must incorporate our translation file content into + our application code at bootstrap time. + * if we are using Ahead-in-Time compilation, we can include our translation file via `ngc` options. + + In both approaches the general idea is the same. we have to give angular these three things: + * Translations file + * Translation format + * Locale ID + + Our untranslated app now looks like this: ++makeTabs(` + i18n/ts/app/app.component.html, + i18n/ts/app/app.component.ts, + i18n/ts/app/app.module.ts, + i18n/ts/app/main.1.ts, + i18n/ts/messages.fr.xlf.ts +`, '', ` + app/app.component.html, + app/app.component.ts, + app/app.module.ts, + app/main.ts, + messages.fr.xlf +`) + +a(id="use-jit") +.l-main-section :marked - We have to provide three values: `TRANSLATIONS`, `TRANSLATIONS_FORMAT` and `LOCALE_ID`: + ### Load translations with the JiT approach + + When we use JiT, we'll provide those three things when bootstrapping out `AppModule`. + + We have to provide three values: `TRANSLATIONS`, `TRANSLATIONS_FORMAT` and `LOCALE_ID`. * `TRANSLATIONS` is a string containing the content of our `messages` file for the chosen localization. * `TRANSLATIONS_FORMAT` is either `xlf`, `xlif` or `xtb` depending on the format of our `messages` file. * `LOCALE_ID` is a string representing the locale of our chosen language. + + Starting out with our default `main.ts`: - For our `messages.fr.xlf` file, we would change the bootstrap like this: ++makeExample('i18n/ts/app/main.1.ts', null, 'app/main.ts')(format=".") + +:marked + We'll import `TRANSLATIONS`, `TRANSLATIONS_FORMAT` and `LOCALE_ID` from `@angular/core`, then + use them to provide our own values in the `providers` array: +makeExample('i18n/ts/app/main.ts', null, 'app/main.ts')(format=".") :marked + But... We don't have a `./messages.fr.ts` file yet. + Since TypeScript is unable to import an `xlf` file, we have to create a `.ts` file that exports the content of our `messages.fr.xlf` file. + Create `app/messages.fr.ts`. We just want to export a string, so we'll start out with a very + simple file exporting an empty template literal: + ++makeExample('i18n/ts/app/messages.fr.1.ts', null, 'app/messages.fr.ts')(format=".") -+makeExample('i18n/ts/app/i18n/messages.fr.ts', null, 'app/i18n/messages.fr.ts')(format=".") +:marked + Now copy the contents of `message.fr.xlf` into the empty template literal: + ++makeExample('i18n/ts/app/messages.fr.ts', null, 'app/messages.fr.ts')(format=".") .alert.is-helpful :marked @@ -219,33 +225,37 @@ a(id="use-jit") That's it, our application is now internationalized! Angular will replace the content of our elements using the `i18n` attribute with the french translations that we provided at bootstrap. + Your JiT app should now look just like the app at the end of [Loading translations](#loading-translations) + except for these two files: + ++makeTabs(` + i18n/ts/app/main.ts, + i18n/ts/app/messages.fr.ts + `, '', ` + app/main.ts, + app/messages.fr.ts + `) + a(id="use-aot") .l-main-section :marked ### Use translations with the AoT approach - Using the AoT approach requires a little bit of setup to make the `ngc` compiler work. Refer to the - [AoT cookbook](../cookbook/aot-compiler.html) to learn more about it. + Using the AoT approach requires a little bit of setup to make the `ngc` compiler work. Start with + the files shown at the end of [Loading translations](#loading-translations) and refer to the + [AoT cookbook](../cookbook/aot-compiler.html) to make it AoT ready. - Once our project is ngc-ready, we will use `ngc` to compile a version of our application per locale. To do that + Once our project is AoT-ready, we will use `ngc` to compile a version of our application per locale. To do that we will add three arguments to the cli command: * `--i18nFile`: the path to our localization file * `--locale`: the name of the locale * `--i18nFormat`: the format of our localization file - If we want to generate precompiled files for our french translations, we will use: - code-example(language="sh"). - ngc --i18nFile=./app/i18n/messages.fr.xlf --locale=fr --i18nFormat=xlf + ./node_modules/.bin/ngc --i18nFile=./messages.fr.xlf --locale=fr --i18nFormat=xlf -.alert.is-helpful - :marked - Since you're supposed to generate precompiled file for each locale, you should probably use different `tsconfig.json` - files with a different `genDir` for each, and different npm commands pointing to each locale. - - You could also write a script that directly calls the `CodeGenerator` class (exported by the package `@angular/compiler-cli`) - for each locale. - :marked - That's all that we have to do, the `ngc` compiler will replace the content of our elements using the i18n attribute - with our translations in the AoT precompiled files. + That's all that we have to do! The `ngc` compiler will replace the content of our elements that have + the i18n attribute with our translations in the AoT precompiled files. + + From 3373fad9a2a05378f562fbede1ab5ff1d4e0b4ef Mon Sep 17 00:00:00 2001 From: Filipe Silva Date: Mon, 26 Sep 2016 16:48:55 +0100 Subject: [PATCH 19/21] fix code shell example --- public/docs/ts/latest/guide/i18n.jade | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/public/docs/ts/latest/guide/i18n.jade b/public/docs/ts/latest/guide/i18n.jade index 55685e5e62..ede9680544 100644 --- a/public/docs/ts/latest/guide/i18n.jade +++ b/public/docs/ts/latest/guide/i18n.jade @@ -82,14 +82,14 @@ a(id="ng-xi18n") To use it, the first thing that we have to do is to install it and it's `platform-server` peer dependency: -code-example(language="sh"). +code-example(language="sh" class="code-shell"). npm install @angular/compiler-cli @angular/platform-server --save :marked Like `ngc`, `ng-xi18n` is based on `tsc`, the TypeScript compiler. We can use it to generate our transfile file at the root of our project: -code-example(language="sh"). +code-example(language="sh" class="code-shell"). ./node_modules/.bin/ng-xi18n :marked @@ -251,7 +251,7 @@ a(id="use-aot") * `--locale`: the name of the locale * `--i18nFormat`: the format of our localization file -code-example(language="sh"). +code-example(language="sh" class="code-shell"). ./node_modules/.bin/ngc --i18nFile=./messages.fr.xlf --locale=fr --i18nFormat=xlf :marked From e8422004ae793bcc21937de004031e36b84ea2bd Mon Sep 17 00:00:00 2001 From: Filipe Silva Date: Mon, 26 Sep 2016 22:58:40 +0100 Subject: [PATCH 20/21] incorporate vicb's feedback --- public/docs/_examples/i18n/e2e-spec.ts | 2 +- public/docs/ts/latest/guide/i18n.jade | 45 +++++++++++++------------- 2 files changed, 24 insertions(+), 23 deletions(-) diff --git a/public/docs/_examples/i18n/e2e-spec.ts b/public/docs/_examples/i18n/e2e-spec.ts index 138a7c878e..6606ca8878 100644 --- a/public/docs/_examples/i18n/e2e-spec.ts +++ b/public/docs/_examples/i18n/e2e-spec.ts @@ -1,6 +1,6 @@ /// 'use strict'; -describe('i18n E2E Tests', function () { +describe('i18n E2E Tests', () => { beforeEach(function () { browser.get(''); diff --git a/public/docs/ts/latest/guide/i18n.jade b/public/docs/ts/latest/guide/i18n.jade index ede9680544..8ed64bb91c 100644 --- a/public/docs/ts/latest/guide/i18n.jade +++ b/public/docs/ts/latest/guide/i18n.jade @@ -2,8 +2,8 @@ include ../_util-fns :marked With internationalization, also known as i18n, we can display our website in multiple languages. - Angular provides tools to export translation files that translators and work on. - Those finished translations can then be loaded alongside with your application to make it + Angular provides tools to export translation files that translators can work on. + Those finished translations can then be merged with your application to make it available to multiple audiences. @@ -13,9 +13,9 @@ include ../_util-fns * [The i18n attribute](#the-i18n-attribute) * [Extract messages with ng-xi18n](#ng-xi18n) * [Translate messages](#translate) - * [Loading translations](#loading-translations) - * [Using JiT](#use-jit) - * [Using AoT](#use-aot) + * [Merging translations](#merging-translations) + * [JiT configuration](#jit-configuration) + * [AoT configuration](#aot-configuration) :marked **Try it out**. Here's a link to a of the JiT application. @@ -29,10 +29,10 @@ a(id="angular-i18n") Angular allows us to replace text in our application with the translation of our choice. We would usually start with a working application that already has text in a single language. - We then we extract from our app a translation file that translators can load on their translation software to work on the translation. + We then extract from our app a translation file that translators can open on their translation software to work on the translation. Finally we use their translation on our app to override the original text. - We can then build the application for each language we need, and deploy each translated application to it's own server. + We can then build the application for each language we need, and deploy each translated application separately. a(id="the-i18n-attribute") @@ -40,7 +40,7 @@ a(id="the-i18n-attribute") :marked ### i18n attribute - The `i18n` attribute is what tells Angular where it should insert the translations. + The `i18n` attribute is a market for translatable content. We'll start with a simple greeting in a `

` tag: @@ -77,7 +77,7 @@ a(id="ng-xi18n") Now that our template has been updated to support i18n translations, we can use the `ng-xi18n` messages extractor. - This CLI tool is based on `ngc`, and is available in the `@angular/compiler-cli` npm package. + This CLI tool is based on `ngc` and is available in the `@angular/compiler-cli` npm package. You can read more about `ngc` on the [AoT cookbook](../cookbook/aot-compiler.html). To use it, the first thing that we have to do is to install it and it's `platform-server` peer dependency: @@ -115,7 +115,7 @@ a(id="translate") translators to edit, using one of the many editors that support `xlf`. You can find a list of editors [here](https://en.wikipedia.org/wiki/XLIFF#Editors). - For the sake of simplicity, we will make our French by editing the translation file manually in our text editor. + For the sake of simplicity, we will make our French translation by editing the translation file manually in our text editor. Make a copy of `messages.xlf` called `messages.fr.xlf`, open it and find the following section: @@ -130,6 +130,7 @@ a(id="translate") This XML element represents the translation of our header tag. You might have a different string in `id="af2ccf4b5dba59616e92cf1531505af02da8f6d2"`, this is normal. + It depends on the content of the message and it's meaning, so if you change either it will also change. Replace `` with `Bonjour i18n!` to add our French translation. That's all for our french translation! @@ -142,10 +143,10 @@ a(id="translate") the messages extractor. -a(id="loading-translations") +a(id="merging-translations") .l-main-section :marked - ## Loading translations + ## Merging translations Now that we have a localized file, we can tell Angular to use it for all of our elements that have the `i18n` marker. @@ -159,8 +160,8 @@ a(id="loading-translations") In both approaches the general idea is the same. we have to give angular these three things: * Translations file - * Translation format - * Locale ID + * Translation file format + * Locale ID (`en-US` for instance) Our untranslated app now looks like this: @@ -178,15 +179,15 @@ a(id="loading-translations") messages.fr.xlf `) -a(id="use-jit") +a(id="jit-configuration") .l-main-section :marked - ### Load translations with the JiT approach + ### Merge translations with the JiT approach When we use JiT, we'll provide those three things when bootstrapping out `AppModule`. We have to provide three values: `TRANSLATIONS`, `TRANSLATIONS_FORMAT` and `LOCALE_ID`. - * `TRANSLATIONS` is a string containing the content of our `messages` file for the chosen localization. + * `TRANSLATIONS` is a string containing the content of our `messages` file for the chosen locale. * `TRANSLATIONS_FORMAT` is either `xlf`, `xlif` or `xtb` depending on the format of our `messages` file. * `LOCALE_ID` is a string representing the locale of our chosen language. @@ -225,7 +226,7 @@ a(id="use-jit") That's it, our application is now internationalized! Angular will replace the content of our elements using the `i18n` attribute with the french translations that we provided at bootstrap. - Your JiT app should now look just like the app at the end of [Loading translations](#loading-translations) + Your JiT app should now look just like the app at the end of [Merging translations](#merging-translations) except for these two files: +makeTabs(` @@ -236,13 +237,13 @@ a(id="use-jit") app/messages.fr.ts `) -a(id="use-aot") +a(id="aot-configuration") .l-main-section :marked - ### Use translations with the AoT approach + ### Merge translations with the AoT approach Using the AoT approach requires a little bit of setup to make the `ngc` compiler work. Start with - the files shown at the end of [Loading translations](#loading-translations) and refer to the + the files shown at the end of [Merging translations](#merging-translations) and refer to the [AoT cookbook](../cookbook/aot-compiler.html) to make it AoT ready. Once our project is AoT-ready, we will use `ngc` to compile a version of our application per locale. To do that @@ -256,6 +257,6 @@ code-example(language="sh" class="code-shell"). :marked That's all that we have to do! The `ngc` compiler will replace the content of our elements that have - the i18n attribute with our translations in the AoT precompiled files. + the i18n attribute with our translations in the AoT generated templates. From 6ff5c74a08a383cdc0aa7bf6191cc7c6bda46aa1 Mon Sep 17 00:00:00 2001 From: Filipe Silva Date: Mon, 26 Sep 2016 23:03:57 +0100 Subject: [PATCH 21/21] fix typo --- public/docs/ts/latest/guide/i18n.jade | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/public/docs/ts/latest/guide/i18n.jade b/public/docs/ts/latest/guide/i18n.jade index 8ed64bb91c..8d69c169fd 100644 --- a/public/docs/ts/latest/guide/i18n.jade +++ b/public/docs/ts/latest/guide/i18n.jade @@ -150,7 +150,7 @@ a(id="merging-translations") Now that we have a localized file, we can tell Angular to use it for all of our elements that have the `i18n` marker. - Angular understands `xlf`,`xlif` and `xtb` formats, but we have to provide these message into our application. + Angular understands `xlf`, `xlif` and `xtb` formats, but we have to provide these messages into our application. However, our paths diverge depending on whether we use JiT or AoT: