i18n.jade

include ../_util-fns

a#top
:marked
  Angular's _internationalization_ ("_i18n_") tools help make your app available in multiple languages.
  
  ## Table of contents

    * [Angular and i18n template translation](#angular-i18n)
    * [Mark text with the _i18n_ attribute](#i18n-attribute)
    * [Add _i18n-..._ translation attributes](#translate-attributes)
    * [Handle singular and plural](#cardinality)
    * [Select among alternative texts](#select)
    * [Use the **_ng-xi18n_ extraction tool** to create a translation source file](#ng-xi18n)
    * [Translate](#translate)
    * [Merge the completed translation file into the app](#merge)
      * [JiT configuration](#jit)
      * [AoT configuration](#aot)
    * [Translation file maintenance and _id_ changes](#maintenance)

:marked
  **Try this** <live-example name="cb-i18n" title="i18n Example in Spanish">live example</live-example> 
  of a JiT-compiled app, translated into Spanish.

  
a#angular-i18n
.l-main-section
:marked
  ## Angular and _i18n_ template translation

  Application internationalization is a challenging, many-faceted effort that 
  takes dedication and enduring commitment.
  Angular's _i18n_ internationalization facilities can help.

  This page describes the _i18n_ tools to assist translation of component template text
  into multiple languages.


.l-sub-section
  :marked
    Practitioners of _internationalization_ refer to a translatable text as a "_message_".
    This page uses the words "_text_" and "_message_" interchangably and in the combination, "_text message_".
  
:marked
  The _i18n_ template translation process has four phases:

  1. Mark static text messages in your component templates for translation.
  
  1. An angular _i18n_ tool extracts the marked messages into an industry standard translation source file.

  1. A translator edits that file, translating the extracted text messages into the target language, 
  and returns the file to you.

  1. The Angular compiler imports the completed translation files, 
  replaces the original messages with translated text, and generates a new version of the application
  in the target language.

  You build and deploy a separate version of the application for each supported language.

a#i18n-attribute
.l-main-section
:marked
  ## Mark text with the _i18n_ attribute
  
  The Angular `i18n` attribute is a marker for translatable content.
  Place it on every element tag whose fixed text should be translated.

.alert.is-helpful
  :marked
    `i18n` is not an Angular _directive_. 
    It's a custom _attribute_, recognized by Angular tools and compilers.
    It will be removed by the compiler _after_ translation.

:marked
  In the accompanying sample, an `<h1>` tag displays a simple English language greeting which you will translate to Spanish:
+makeExample('cb-i18n/ts/app/app.component.1.html', 'greeting', 'app/app.component.html')(format=".")
:marked
  Add the `i18n` attribute to the tag to mark it for translation.

+makeExample('cb-i18n/ts/app/app.component.1.html', 'i18n-attribute', 'app/app.component.html')(format=".")

:marked
  ### Help the translator with a _description_ and _intent_

  The translator may need a description of the message to translate it accurately.
  Assign a description to the i18n attribute:
  
+makeExample('cb-i18n/ts/app/app.component.1.html', 'i18n-attribute-desc', 'app/app.component.html')(format=".")

:marked
  The translator may need to know your _intent_ &mdash; 
  the true _meaning_ of the text within _this particular_ application context &mdash; 
  in order to deliver a correct translation.
  Add some contextual meaning to the assigned string, in front of the description,
  separating it from the description with the `|` character (`<meaning>|<description>`):
  
+makeExample('cb-i18n/ts/app/app.component.html', 'i18n-attribute-meaning', 'app/app.component.html')(format=".")

:marked
  ### Strengthen translation messages consistancy with an explicit _id_

  By default the angular _i18n_ extractor tool generates a unique ID for each `i18n` attributes in templates.
  If you fix a typo in a translatable block of your template, the extractor tool will generate another new _id_ for your translation.
  To avoid this behavior, you can specify an explicit _id_ in the `i18n` attribute that will be used by the extractor tool and compiler.
  To specify an _id_, just prefix it with `@@` in the i18n attribute:

+makeExample('cb-i18n/ts/app/app.component.1.html', 'i18n-attribute-id', 'app/app.component.html')(format=".")
:marked
  With a _meaning_ and a _description_ :

+makeExample('cb-i18n/ts/app/app.component.1.html', 'i18n-attribute-meaning-and-id', 'app/app.component.html')(format=".")
:marked
  Moreover, you can just specify an _id_ in the `i18n` attribute :
+makeExample('cb-i18n/ts/app/app.component.1.html', 'i18n-attribute-solo-id', 'app/app.component.html')(format=".")

:marked
  While all appearances of a message with the _same_ meaning have the _same_ translation, 
  a message with *different meanings* could have different translations.
  The Angular extraction tool preserves both the _meaning_ and the _description_ in the translation source file
  to facilitiate contextually-specific translations.

  ### Translate text without creating an element

  Suppose there is a stretch of text that you'd like to translate.
  You could wrap it in a `<span>` but for some reason (CSS comes to mind)
  you don't want to create a new DOM element merely to facilitate translation.
  
  Here are two techniques to try.

  (1) Wrap the text in an `<ng-container>` element. The `<ng-container>` is never renderered:

+makeExample('cb-i18n/ts/app/app.component.html', 'i18n-ng-container', 'app/app.component.html')(format=".")

:marked
  (2) Wrap the text in a pair of HTML comments:

+makeExample('cb-i18n/ts/app/app.component.html', 'i18n-with-comment', 'app/app.component.html')(format=".")

.l-main-section
a#translate-attributes
:marked
  ## Add _i18n-..._ translation attributes
  You've added an image to your template. You care about accessibility too so you add a `title` tag:

+makeExample('cb-i18n/ts/app/app.component.1.html', 'i18n-title', 'app/app.component.html')(format=".")

:marked
  The `title` attribute needs to be translated. 
  Angular i18n support has more translation attributes in the form,`i18n-x`, where `x` is the
  name of the attribute to translate. 
  
  To translate the `title` on the `img` tag from the previous example, write:

+makeExample('cb-i18n/ts/app/app.component.html', 'i18n-title-translate', 'app/app.component.html')(format=".")

:marked
  You can also assign a meaning and a description with the `i18n-x="<meaning>|<description>"` syntax.

.l-main-section
a#cardinality
:marked
  ## Handle singular and plural
  
  Different languages have different pluralization rules.
  
  Suppose your application says something about a collection of wolves. 
  In English, depending upon the number of wolves, you could display "no wolves", "one wolf", "two wolves", or "a wolf pack".
  Other languages might express the _cardinality_ differently. 
  
  Here's how you could markup the component template to display the phrase appropriate to the number of wolves:

+makeExample('cb-i18n/ts/app/app.component.html', 'i18n-plural', 'app/app.component.html')(format=".")

:marked
  * The first parameter is the key. It will be bound to the component property (`wolves`) that determines the number of wolves.
  * The second parameter indentifies this as a `plural` translation type.
  * The third parameter defines a pluralization pattern consisting of pluralization categories and their matching values.

  Pluralization categories include:
  * =0
  * =1
  * =5
  * few
  * other

  Put the default _English_ translation in braces (`{}`) next to the pluralization category.
  * When you're talking about one wolf, you could write `=1 {one wolf}`.
  * For zero wolves, you could write `=0 {no wolves}`.
  * For two wolves, you could write `=2 {two wolves}`. 

  You could keep this up for three, four, and every other number of wolves.
  Or you could specify the **`other`** category as a catch-all for any unmatched cardinality
  and write something like: `other {a wolf pack}`.

.l-sub-section
  :marked
    This syntax conforms to the
    <a href="http://userguide.icu-project.org/formatparse/messages" target="_blank" title="ICU Message Format">ICU Message Format</a>
    which derives from the 
    <a href="http://cldr.unicode.org/" target="_blank" title="CLDR">Common Locale Data Repository (CLDR)</a>
    which specifies the
    <a href="http://unicode.org/reports/tr35/tr35-numbers.html#Language_Plural_Rules" target="_blank" title="Pluralization Rules">pluralization rules</a>.

a#select
:marked
  ## Select
  The application displays different text depending upon whether the hero is male or female.
  These text alternatives require translation too.

  You can handle this with a `select` translation. 
  A `select` also follows the
  <a href="http://userguide.icu-project.org/formatparse/messages" target="_blank" title="ICU Message Format">ICU message syntax</a>. 
  You choose among alternative translation based on a string value instead of a number.

  The following format message in the component template binds to the component's `gender` property which outputs either an 'm' or an 'f'.
  The message maps those values to the appropriate translation:

+makeExample('cb-i18n/ts/app/app.component.html', 'i18n-select', 'app/app.component.html')(format=".")

a#ng-xi18n
.l-main-section
:marked
  ## Create a translation source file with the _ng-xi18n_ tool
  
  Use the **_ng-xi18n_ extraction tool** to extract the `i18n`-marked texts 
  into a translation source file in an industry standard format.
  
  This is an Angular CLI tool in the `@angular/compiler-cli` npm package.
  If you haven't already installed the CLI and its `platform-server` peer dependency, do so now:
  
code-example(language="sh" class="code-shell").
  npm install @angular/compiler-cli @angular/platform-server --save

:marked
  Open a terminal window at the root of the application project and enter the `ng-xi18n` command:
 
code-example(language="sh" class="code-shell").
  ./node_modules/.bin/ng-xi18n

.l-sub-section
  :marked
    Windows users may have to quote the command: like this `"./node_modules/.bin/ng-xi18n"`

:marked
  By default the tool generates a translation file named **`messages.xlf`** in the
  <a href="https://en.wikipedia.org/wiki/XLIFF" target="_blank">XML Localisation Interchange File Format (XLIFF, version 1.2)</a>.

a#other-formats
:marked
  ### Other translation formats

  You can generate a file named **`messages.xmb`** in the 
  <a href="http://cldr.unicode.org/development/development-process/design-proposals/xmb"  target="_blank">XML Message Bundle (XMB)</a> format
  by adding the `--i18nFormat=xmb` flag.

code-example(language="sh" class="code-shell").
  ./node_modules/.bin/ng-xi18n  --i18nFormat=xmb

:marked
  This sample sticks with the _XLIFF_ format.

a#ng-xi18n-options
:marked
  ### Other options
  You may have to specify additional options. 
  For example, if the `tsconfig.json` TypeScript configuration file is located other than in the root folder,
  you must identify the path to it with the `-p` option:
code-example(language="sh" class="code-shell").
  ./node_modules/.bin/ng-xi18n -p path/to/tsconfig.json
  ./node_modules/.bin/ng-xi18n  --i18nFormat=xmb -p path/to/tsconfig.json


a#npm-i18n-script
:marked
  ### Add an _npm_ script for convenience
  
  Consider adding a convenience shortcut to the `scripts` section of the `package.json`
  to make the command easier to remember and run:
code-example(format='.' language='sh' ).
  "scripts": {
    "i18n": "ng-xi18n", 
    ...
  }
:marked
  Now you can issue command variations such as these:
code-example(language="sh" class="code-shell").
  npm run i18n
  npm run i18n -- -p path/to/tsconfig.json
  npm run i18n -- --i18nFormat=xmb -p path/to/tsconfig.json
:marked
  Note the `--` flag before the options. 
  It tells _npm_ that every flag thereafter should be passed through to `ng-xi18n`.

a#translate
.l-main-section
:marked
  ## Translate _los mensajes de texto_
  
  The `ng-xi18n` command generated a translation source file in the project root folder named `messages.xlf`.
  The next step is to translate the English language template text into the specific language translation
  files. The cookbook sample creates a Spanish translation file.

a#localization-folder
:marked
  ### Create a localization folder

  You will probably translate into more than one other language so it's a good idea
  for the project structure to reflect your entire internationalization effort.
  
  One approach is to dedicate a folder to localization and store related assets 
  (e.g. internationalization files) there.
.l-sub-section
  :marked
    Localization and internationalization are 
    <a href="https://en.wikipedia.org/wiki/Internationalization_and_localization" target="_blank">different but closely related terms</a>.
:marked
  This sample follows that suggestion. It has a `locale` folder under the project root.
  Assets within the folder carry a filename extension that matches a language-culture code from a
  <a href="https://msdn.microsoft.com/en-us/library/ee825488(v=cs.20).aspx" target="_blank">well-known codeset</a>.

  Make a copy of the `messages.xlf` file in the `locale` folder and 
  rename it `messages.es.xlf`for the Spanish language translation.
  Do the same for each target language.

  ### Translate text nodes
  In the real world, you send the `messages.es.xlf` file to a Spanish translator who fills in the translations
  using one of the
  <a href="https://en.wikipedia.org/wiki/XLIFF#Editors" target="_blank">many XLIFF file editors</a>.

  This sample file is easy to translate without a special editor or knowledge of Spanish.
  Open `messages.es.xlf` and find the first `<trans-unit>` section:

+makeExample('cb-i18n/ts/locale/messages.es.xlf.html', 'translated-hello', 'locale/messages.es.xlf (<trans-unit>)')(format=".")
:marked
  This XML element represents the translation of the `<h1>` greeting tag you marked with the `i18n` attribute. 
  
  Using the _source_, _description_, and _meaning_ elements to guide your translation,
  replace the `<target/>` tag with the Spanish greeting:
+makeExample('cb-i18n/ts/locale/messages.es.xlf.html', 'translated-hello', 'locale/messages.es.xlf (<trans-unit>, after translation)')(format=".")

.alert.is-important
  :marked
    Note that the `id` is generated by the tool. **Don't touch it.**
    Its value depends on the content of the message and its assigned meaning.
    Change either factor and the `id` changes as well.
    See the **[translation file maintenance discussion](#maintenance)** below.

:marked
  Translate the other text nodes the same way:

+makeExample('cb-i18n/ts/locale/messages.es.xlf.html', 'translated-other-nodes', 'locale/messages.es.xlf (<trans-unit>)')(format=".")

a#translate-plural-select
:marked
  ## Translate _plural_ and _select_
  Translating _plural_ and _select_ messages is a little tricky.

  The `<source>` tag is empty for `plural` and `select` translation units which makes them hard to correlate with the original template.
  The ICU rules are not yet supported in the `XLIFF` format; they soon will be.
  The ICU rules _are_ supported in the `XMB` format.  

  You'll just have to look for them in relation to other translation units that you recognize from elsewhere in the source template.
  In this example, you know the translation unit for the `select` must be just below the translation unit for the logo.

:marked
  ### Translate _plural_ 
  To translate a `plural`, translate its ICU format match values:

+makeExample('cb-i18n/ts/locale/messages.es.xlf.html', 'translated-plural', 'locale/messages.es.xlf (<trans-unit>)')(format=".")

:marked
  ### Translate _select_ 
  The `select` behaves a little differently. Here again is the ICU format message in the component template:

+makeExample('cb-i18n/ts/app/app.component.html', 'i18n-select', 'app/app.component.html')(format=".")

:marked
  The extraction tool broke that into _two_ translation units.
  
  The first unit contains the text that was _outside_ the `select`.
  In place of the `select` is a placeholder, `<x id="ICU">`, that represents the `select` message. 
  Translate the text and leave the placeholder where it is.

+makeExample('cb-i18n/ts/locale/messages.es.xlf.html', 'translate-select-1', 'locale/messages.es.xlf (<trans-unit>)')(format=".")

:marked
  The second translation unit, immediately below the first one, contains the `select` message. Translate that.

+makeExample('cb-i18n/ts/locale/messages.es.xlf.html', 'translate-select-2', 'locale/messages.es.xlf (<trans-unit>)')(format=".")

:marked
  Here they are together, after translation:

+makeExample('cb-i18n/ts/locale/messages.es.xlf.html', 'translated-select', 'locale/messages.es.xlf (<trans-unit>)')(format=".")

.l-main-content
:marked
  The entire template translation is complete. It's time to incorporate that translation in the application.

#app-pre-translation
:marked
  ### The app before translation

  After the previous steps, the sample app _and_ its translation file are as follows:

+makeTabs(`
  cb-i18n/ts/app/app.component.html,
  cb-i18n/ts/app/app.component.ts,
  cb-i18n/ts/app/app.module.ts,
  cb-i18n/ts/app/main.1.ts,
  cb-i18n/ts/locale/messages.es.xlf.html
`, '', `
  app/app.component.html,
  app/app.component.ts,
  app/app.module.ts,
  app/main.ts,
  locale/messages.es.xlf
`)

a#merge
.l-main-section
:marked
  ## Merge the completed translation file

  To merge the translated text into component templates,
  you compile the application with the completed translation file.
  The process is the same whether the file is in `.xlf` format or 
  in one of the other formats (`.xlif` and `.xtb`) that Angular understands.
  
  You provide the Angular compiler with three new pieces of information:
    * the translation file
    * the translation file format 
    * the   <a href="https://en.wikipedia.org/wiki/XLIFF" target="_blank">_Locale ID_</a>
    (`es` or `en-US` for instance)
  
  _How_ you provide this information depends upon whether you compile with
  the JiT (_Just-in-Time_) compiler or the AoT (_Ahead-of-Time_) compiler. 
  
    * with [JiT](#jit), you provide the information at bootstrap time.
    * with [AoT](#aot), you pass the information as `ngc` options. 

a#jit
.l-main-section
:marked
  ### Merge with the JiT compiler
  
  The JiT (_Just-in-Time_) compiler compiles the application in the browser as the application loads.
  Translation with the JiT compiler is a dynamic process of ...

  1. determining the language version for the current user,
  2. importing the appropriate language translation file as a string constant,
  3. creating corresponding translation providers to guide the JiT compiler,
  4. bootstrapping the application with those providers.

  Open `index.html` and revise the launch script as shown here:
+makeExample('cb-i18n/ts/index.html', 'i18n', 'index.html (launch script)')(format='.')
:marked
  In this sample, the user's language is hardcoded as a global `document.locale` variable
  in the `index.html`.

a#text-plugin
:marked
  ### SystemJS Text plugin

  Notice the SystemJS mapping of `text` to a `systemjs-text-plugin.js`.
  With the help of a text pluglin, SystemJS can read any file as raw text and
  return the contents as a string.
  You'll need it to import the language translation file.

  SystemJS doesn't ship with a raw text plugin but it's easy to add.
  Create the following `systemjs-text-plugin.js` in the root folder:
+makeExample('cb-i18n/ts/systemjs-text-plugin.js', null, 'systemjs-text-plugin.js')(format='.')
:marked
  ### Create translation providers

  Three providers tell the JiT compiler how to translate the template texts for a particular language
  while compiling the application:

  * `TRANSLATIONS` is a string containing the content of the translation file.
  * `TRANSLATIONS_FORMAT` is the format of the file: `xlf`, `xlif` or `xtb`
  * `LOCALE_ID` is the locale of the target language.

  The `getTranslationProviders` function in the following `app/i18n-providers.ts` 
  creates those providers based on the user's _locale_
  and the corresponding translation file:
+makeExample('cb-i18n/ts/app/i18n-providers.ts', null, 'app/i18n-providers.ts')
:marked
  * It gets the locale from the global `document.locale` variable that was set in `index.html`.

  * If there is no locale or the language is U.S. English (`en-US`), there is no need to translate.
    The function returns an empty `noProviders` array as a `Promise`.
    It must return a `Promise` because this function could read a translation file asynchronously from the server.

  * It creates a transaction filename from the locale according to the name and location convention 
  [described earlier](#localization-folder).

  * The `getTranslationsWithSystemJs` method reads the translation and returns the contents as a string.
  Notice that it appends `!text` to the filename, telling SystemJS to use the [text plugin](#text-plugin). 

  * The callback composes a providers array with the three translation providers.

  * Finally, `getTranslationProviders` returns the entire effort as a promise.

  ### Bootstrap the app with translation providers

  The Angular `bootstrapModule` method has a second, _options_ parameter
  that can influence the behavior of the compiler.

  You'll create an _options_ object with the translation providers from `getTranslationProviders`
  and pass it to `bootstrapModule`.
  Open the `app/main.ts` and modify the bootstrap code as follows:
+makeExample('cb-i18n/ts/app/main.ts', null, 'app/main.ts')(format=".")
:marked
  Notice that it waits for the `getTranslationProviders` promise to resolve before
  bootstrapping the app.

  The app is now _internationalized_ for English and Spanish and there is a clear path for adding
  more languages.

a#aot
.l-main-section
:marked
  ### _Internationalize_ with the AoT compiler
  
  The JiT compiler translates the application into the target language while compiling dynamically in the browser.
  That's flexible but may not be fast enough for your users. 
  
  The AoT (_Ahead-of-Time_) compiler is part of a build process that produces a small, fast, ready-to-run application package.
  When you internationalize with the AoT compiler, you pre-build a separate application package for each
  language. Then in the host web page (`index.html`), you determine which language the user needs
  and serve the appropriate application package.

  This cookbook doesn't cover how to build multiple application packages and 
  serve them according to the user's language preference.
  It does explain the few steps necessary to tell the AoT to apply a translations file.

  Internationalization with the AoT compiler requires some setup specifically for AoT. 
  Start with application project as shown [just before merging the translation file](#app-pre-translationStart)
  and refer to the [AoT cookbook](aot-compiler.html) to make it _AoT-ready_.
  
  Next, issue an `ngc` compile command for each supported language (including English).
  The result is a separate version of the application for each language.
  
  Tell AoT how to translate by adding three options to the `ngc` command:
    * `--i18nFile`: the path to the translation file
    * `--locale`: the name of the locale
    * `--i18nFormat`: the format of the localization file
  
  For this sample, the Spanish language command would be
code-example(language="sh" class="code-shell").
  ./node_modules/.bin/ngc --i18nFile=./locale/messages.es.xlf --locale=es --i18nFormat=xlf

.l-sub-section
  :marked
    Windows users may have to quote the command:
  code-example(language="sh" class="code-shell").
    "./node_modules/.bin/ngc" --i18nFile=./locale/messages.es.xlf --locale=es --i18nFormat=xlf

a#maintenance
:marked
  ## Translation file maintenance and _id_ changes
    
  As the application evolves, you will change the _i18n_ markup and re-run the `ng-xi18n` extraction tool many times.
  The _new_ markup that you add is not a problem. 
  But _most_ changes to _existing_ markup will trigger generation of _new_ `id`s for the affected translation units.
  
  After an `id` changes, the translation files are no longer in-sync.
  **All translated versions of the application will fail** during re-compilation. 
  The error messages identify the old `id`s that are no longer valid but they don't tell you what the new `id`s should be.
  
  **Commit all translation message files to source control**, especially the English source `messages.xlf`.
  The difference between the old and the new `messages.xlf` file will help you find and update `id` changes across your translation files.