ngx translate usage

xliffmerge has some tooling for ngx-translate (starting with version 0.2.0).

It supports extraction of translation files for ngx-translate (json-files) from the translated xlf or xmb-files.

How to use it

The general idea is

• put the texts, that you want to use with ngx-translate, into a template of a component of your app.
• translate it together with all other messages in the normal way.
• let xliffmerge generate a translation file to be used with ngx-translate

Create a component containing the ngx-translate relevant texts

This component will never be shown in your application. It is only used to get the messages extracted.

# create a component using angular-cli
cd myapp/src/app
ng g c NgxTranslateData

Mark the messages with i18n="my.app.key|ngx-translate" or even simpler (starting with Angular 4.0 and xliffmerge 0.4.0) set the message id with i18n="@@my.app.key.

<!-- ngx-translate-data.component.html -->
<h1>Data used with ngx-translate</h1>
<p>This component will never be shown in the app</p>
<ul>
  <li i18n="appTitle|ngx-translate">Sample App Title</li>
  <li i18n="messages.example|ngx-translate">{{priority}}: A message from a service</li>
  <li i18n="@@messages.example2">{{priority}}: Another message from a service</li>
</ul>

Extract the data

You have to activate the translate feature by adding the following line to your profile xliffmergeconfig.ts:

{
  "xliffmergeOptions": {
    ...,
    "supportNgxTranslate": true
  }
}

Note: Startin with version 0.10.0 (January 2018) you can specify what description are used for export and wether you want to export entries with explicit IDs at all. You can do that by setting the following option in your profile:

{
  "xliffmergeOptions": {
    ...,
    "supportNgxTranslate": true,
    "ngxTranslateExtractionPattern": "@@|ngx-translate",
  }
}

The syntax is a | separated list of strings. Every string specifies a description that will be used for export. The special string @@ stand for "export messages with explicitly set IDs". So if you do not want to have this values, just use "ngxTranslateExtractionPattern": "ngx-translate"

Then you can just run the normal extraction (described in the tutorial):

npm start extract-i18n

and finally you should find a json file for every language (in genDir, which is typically src\i18n):

// src/i18n/messages.en.json
{
    "appTitle": "Sample App Title",
    "messages": {
        "example": "{{0}}: A message from a service",
        "example2": "{{0}}: Another message from a service"
    }
}

To get translated versions, just follow the normal workflow. Send the xliff to a translator, get back the translated version, check in, rerun extraction.

Use the translation data in your code

Now you have a quite normal translation file and you can just follow the usage instructions given by ngx-translate.

Placeholder names

There is one limitation concerning placeholders. If you have a look at the original template text <li i18n="messages.example|ngx-translate">{{priority}}: A message from a service</li>, this is transformed to "{{0}}: A message from a service".

The name of the placeholder (priority) is converted to {{0}}. This is due to the fact, that the names are not contained in the original extracted messages, so there is no change to get them.

All Placeholder are simple numbered beginning with 0.

But is is allowed to use the same placeholder serveral times, e.g. My name is {{givenname}} {{surname}}, just call me {{givenname}} transforms to My name is {{0}} {{1}}, just call me {{0}}.