matheo / ngx-i18nsupport

Some tooling to be used for Angular 2 i18n workflows

ngx-i18nsupport

Some tooling to be used for Angular i18n workflows.

This page contains just a very short description about the installation process and usage. For details have a look at the Tutorial for using xliffmerge contained in the Wiki pages.

There is also some support to use dynamic translations based on ngx-translate in parallel. See details at the Wiki page ngx translate usage

Table of Contents

• Introduction
• Installation
• Usage
• Tests
• Contributing
• References

Introduction

Angular has a specific way of dealing with internationalization (i18n). It is described in the official documentation Angular Cookbook Internationalization (i18n).

Said in one sentence,

• markup your strings to translate in your templates with an attribute i18n
• run the Amgular extraction tool (ng-xi18n) to extract the strings in an XML Format called [XLIFF]
• copy and then translate the extracted file for every language you plan to support
• run the ng compiler to generate a special version of your app for the different languages

There is an excellent Blog Article by Phillippe Martin Deploying an i18n Angular app with angular-cli , which describes it in detail.

But there are some maior gaps in the workflow. That´s where this tool comes into play.

First, you have to create a complete translation, otherwise, the ng compiler will not generate a version. It is not possible to run with partial translation.

Second, whenever you change something in your app, you have to regenerate the xliff, but there is no documented way how to merge this with the already existing translated files. There are new translation unit, that you have to merge in, and there are translation units, that do not exist any more.

Installation

npm install -g ngx-i18nsupport

This will install a script called xliffmerge.

You can then integrate the script in your angular i18n workflow, typically in the package.json script section:

"scripts": [
  ...
  "extract-i18n": "ng xi18n --output-path src/i18n && xliffmerge --profile xliffmerge.json en de"
 ]

Usage

xliffmerge [options] [language*]

Merge translations from a generated master to language specific files

Options:

-p, --profile        <json-configurationfile> read confguration data from profile (see below).
-v, --verbose        activate debug mode (produce more output)
-q, --quiet          quiet mode, only errors and warnings are show
-h, --help           output usage information
-V, --version        output the version number

language is an ISO shortcut for the language(s) you use, e.g. "en", "de", "de-ch", ...

json-configurationfile is a json file with the following allowed content (every value is optional):

{
  "xliffmergeOptions": {
    "srcDir": "i18n",
    "genDir": "i18n",
    "i18nFile": "messages.xlf",
    "i18nFormat": "xlf",
    "encoding": "UTF-8",
    "defaultLanguage": "en",
    "languages": ["en", "de"],
    "removeUnusedIds": true,
    "supportNgxTranslate": true,
    "verbose": false,
    "quiet": false,
  }
}

The options are:

• srcDir (string, default "."): directory, where the master file is expected
• genDir (string, default "."): directory, where files are written to (normally identical with srcDir)
• i18nFile (string, default "messages.xlf"): master file (relativ to srcDir)
• i18nFormat (string, default "xlf"): "xlf" for XLIFF or "xmb" for XML Message Bundles
• encoding (string, default "UTF-8"): expected encoding of xlf or xmb files
• defaultLanguage (string, default "en"): the native language used in your templates
• languages (array of strings): list of languages (if not spefified at command line)
• removeUnusedIds (boolean, default true): flag, if unused IDs should be removed during merge
• supportNgxTranslate (boolean, default false): flag to active json translation files for ngx-translate
• verbose (boolean, default false): controls output
• quiet (boolean, default false): controls output

Generate (untranslated) language files, if not already there

When you run xliffmerge, it will read the master xliff file messages.xlf. This is the file generated by the Angular extraction tool ng-xi18n.

Then for every language you specified, it will create a new language specific file, e.g messages.en.xlf or messages.en.xlf.

These files are mainly copies of the master, but they contain the target translations for all translation units of the master.

If the master contains

  <trans-unit id="xy...">
    <source>Hello, world</source>
    <target/>
  </trans-unit>

then the generated file for English (messages.en.xlf) will contain

  <trans-unit id="xy...">
    <source>Hello, world</source>
    <target state="final">Hello, world</target>
  </trans-unit>

and the generated file for German (messages.de.xlf) will contain

  <translation-unit>
    <source id="kfmlkfml">Hello, world</source>
    <target state="new">Hello, world</target>
  </translation-unit>

Obviously this is not the correct translation, it is just no translation. This is shown by the state new. The next step you have to do is to translate the file (or to let it translate). Depending on the software you use for translation you can filter for that state new.

Have a look at my sister project TinyTranslator. It can filter for new untranslated entries and allows to edit xlf file very easily.

The file for English on the other hand is correct. So, due to the fact, that English is the default language here, the state is translated.

The Angular compiler can now use both files to generate language specific versions.

Merge new translation units into the existing language files

Generating translation files for each language and translating them is just the beginning.

When you continue developing your app, you will make changes on the existing templates, add new one, etc.

Now, when you are ready to publish a new release, you will run the ng-xi18n tool again and it will create a new messages.xlf for you. There will be new trans-units in it, and there will be trans-units, that are now removed from the file.

But what do you do with your existing translation for the old version of your app? You don`t want to restart translating the whole stuff.

xliffmerge can do it for you. It will merge the newly created messages.xlf into your existing language specific files.

Whenever it finds an ID in messages.xlf, that does not exist in the language file, it will create it with a dummy translation and mark it as new, just the same way, that happens when creating a new language file.

Whenever it finds the ID in the language file, it will not touch it, so you will not lose the translation.

And whenever it finds an ID in the language file, that does not exist in the messages.xlf anymore, it will remove it from the language file (you can prevent that by setting removeUnusedIds to falsein the profile).

So after running it, you just have to translate the new parts.

Once again: TinyTranslator might help you to do that.

Tests

npm test

This will run a testsuite that checks all relevant aspects of xliffmerge.

Contributing

I did not really think about contributions, because it is just a small experimental project.

But if you are interesting, send me an email, so that we can discuss it.

References

• Angular Cookbook Internationalization (i18n)
• Phillippe Martin Deploying an i18n Angular app with angular-cli
• Roland Oldengarm: Angular 2: Automated i18n workflow using gulp
• XLIFF Specification: XLIFF Spec
• My Tiny Translator Tool: TinyTranslator