docs(i18n): add internationalization (i18n) guide (#2491)

* docs(i18n): add internationalization (i18n) guide

* docs(cb-i18n): revamped to System.import the translation file

Author: wardbell

gulpfile.js

@@ -297,7 +297,7 @@ function runE2eTsTests(appDir, outputFile) {
   } catch (e) {
     exampleConfig = {};
   }
-  
+
   var config = {
     build: exampleConfig.build || 'tsc',
     run: exampleConfig.run || 'http-server:e2e'
@@ -1263,7 +1263,7 @@ function apiExamplesWatch(postShredAction) {
 }
 
 function devGuideExamplesWatch(shredOptions, postShredAction, focus) {
-  var watchPattern = focus ? '**/' + focus + '/**/*.*' : '**/*.*';
+  var watchPattern = focus ? '**/{' + focus + ',cb-' + focus+ '}/**/*.*' : '**/*.*';
   var includePattern = path.join(shredOptions.examplesDir, watchPattern);
   // removed this version because gulp.watch has the same glob issue that dgeni has.
   // var excludePattern = '!' + path.join(shredOptions.examplesDir, '**/node_modules/**/*.*');

public/docs/_examples/cb-i18n/e2e-spec.ts

@@ -0,0 +1,13 @@
+/// <reference path='../_protractor/e2e.d.ts' />
+'use strict';
+describe('i18n E2E Tests', () => {
+
+  beforeEach(function () {
+    browser.get('');
+  });
+
+  it('should display i18n translated welcome: Bonjour i18n!', function () {
+    expect(element(by.css('h1')).getText()).toEqual('Bonjour i18n!');
+  });
+
+});

public/docs/_examples/cb-i18n/ts/.gitignore

@@ -0,0 +1,6 @@
+**/*.ngfactory.ts
+**/*.metadata.json
+**/messages.xlf
+dist
+!app/tsconfig.json
+!rollup.js

public/docs/_examples/cb-i18n/ts/app/app.component.1.html

@@ -0,0 +1,11 @@
+<!--#docregion greeting-->
+<h1>Hello i18n!</h1>
+<!--#enddocregion greeting-->
+
+<!--#docregion i18n-attribute-->
+<h1 i18n>Hello i18n!</h1>
+<!--#enddocregion i18n-attribute-->
+
+<!--#docregion i18n-attribute-desc-->
+<h1 i18n="An introduction header for this sample">Hello i18n!</h1>
+<!--#enddocregion i18n-attribute-desc-->

public/docs/_examples/cb-i18n/ts/app/app.component.html

@@ -0,0 +1,4 @@
+<!--#docregion-->
+<!--#docregion i18n-attribute-meaning-->
+<h1 i18n="User welcome|An introduction header for this sample">Hello i18n!</h1>
+<!--#enddocregion i18n-attribute-meaning-->

public/docs/_examples/cb-i18n/ts/app/app.component.ts

@@ -0,0 +1,10 @@
+// #docregion
+import { Component } from '@angular/core';
+
+@Component({
+  moduleId: module.id,
+  selector: 'my-app',
+  templateUrl: 'app.component.html'
+})
+export class AppComponent { }
+

public/docs/_examples/cb-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 { }

public/docs/_examples/cb-i18n/ts/app/i18n-providers.ts

@@ -0,0 +1,33 @@
+// #docregion
+import { TRANSLATIONS, TRANSLATIONS_FORMAT, LOCALE_ID } from '@angular/core';
+
+export function getTranslationProviders(): Promise<Object[]> {
+
+  // Get the locale id from the global
+  const locale = document['locale'] as string;
+
+  // return no providers if fail to get translation file for locale
+  const noProviders: Object[] = [];
+
+  // No locale or English: no translation providers
+  if (!locale || locale === 'en') {
+    return Promise.resolve(noProviders);
+  }
+
+  // Ex: 'i18n/fr/messages.fr.xlf`
+  const translationFile = `./i18n/${locale}/messages.${locale}.xlf`;
+
+  return getTranslationsWithSystemJs(translationFile)
+    .then( (translations: string ) => [
+      { provide: TRANSLATIONS, useValue: translations },
+      { provide: TRANSLATIONS_FORMAT, useValue: 'xlf' },
+      { provide: LOCALE_ID, useValue: locale }
+    ])
+    .catch(() => noProviders); // ignore if file not found
+}
+
+declare var System: any;
+
+function getTranslationsWithSystemJs(file: string) {
+  return System.import(file + '!text'); // relies on text plugin
+}

public/docs/_examples/cb-i18n/ts/app/main.1.ts

@@ -0,0 +1,6 @@
+// #docregion
+import { platformBrowserDynamic } from '@angular/platform-browser-dynamic';
+
+import { AppModule } from './app.module';
+
+platformBrowserDynamic().bootstrapModule(AppModule);

public/docs/_examples/cb-i18n/ts/app/main.ts

@@ -0,0 +1,10 @@
+// #docregion
+import { platformBrowserDynamic }  from '@angular/platform-browser-dynamic';
+import { getTranslationProviders } from './i18n-providers';
+
+import { AppModule } from './app.module';
+
+getTranslationProviders().then(providers => {
+  const options = { providers };
+  platformBrowserDynamic().bootstrapModule(AppModule, options);
+});