i18n - Impac / Impac Angular

Goals: Allowing multiple languages to be incorporated to the impac dashboard project (currently exclusively english).

Tools: angular translate (An angular library used to translate)
Challenges: In order to internationalize the library we need to go through every layer of the code to check that all the sentences displayed are being translated.

Problems encountered:
- Internationalization can become challenging when you get code behaviours depending on the words that should be translated.
An example would be the date of a widget that gets updated when the user selects a different period (day, week, month, year).
If the code is using the words: day, week,... then there will be a problem when it get translated to another language.

E.g: The program will expect to receive "day" normally but if we switch to another language such as chinese, it will get 天 which does not correspond to any of the period defined.
A solution is to keep the english terms as values and create labels that can be translated in several languages.

Impac Angular (frontend):

You will need to translate values within the HTML code sometimes, as well as in the directives (java script files).

HTML code

Default

In order to translate terms within the HTML code, angular translate gives you several ways:

src/locales/en-gb.json

{
	"my.awesome.translation.of.hello_world": "Hello World"
}

- filter:

src/views/**/some-views.html

<p>{{'my.awesome.translation.of.hello_world' | translate}}</p>

-> This solution looks more elegant but adds unnecessary watchers (to avoid as much as possible)

- directive:
e.g:

<p translate>my.awesome.translation.of.hello_world</p>
    <!-- OR -->
<p translate>{{my.awesome.translation.of.hello_world}}</p>
    <!-- OR -->
<p translate="my.awesome.translation.of.hello_world"></p>
    <!-- OR -->
<p translate="{{my.awesome.translation.of.hello_world}}"></p>

-> Better approach

Advanced (translations with variables)

You can create more complex structure then a simple string translation. You can add variables.

src/locales/en-gb.json

{
	"my.value.to.translate.hello_x": "Hello {name}"
}

- directive:
e.g:

src/views/**/some-views.html

<p translate="my.value.to.translate.hello_x" translate-values="{name: "John"}"></p>

Directive code

Default

To translate an expression in a controller you need to use angular translate service: $translate
Since Angular translate is asynchronous, it will return a promise.
Once you've imported it in your controller you can simply use it like this:

src/views/**/some-views.directive.coffee

module.controller('...', ($translate) ->
	[...]
	$translate('my.awesome.translation.of.hello_world').then(
		(translation) ->
			scope.yourVariable = translation
	)


	// OR (if you have many values to translate)
	$translate(['my.awesome.translation.of.hello_world', 'another.value.cat']).then(
		(translation) ->
			scope.yourVariable = translation["my.awesome.translation.of.hello_world"]
			scope.anotherVariable = translation["another.value.cat"]
	)
)

Advanced

src/views/**/some-views.directive.coffee

$translate('my.value.to.translate.hello_x', {name: "John"}).then(
	(translation) ->
		scope.yourVariable = translation
)

Any question, look at the well made documentation, https://angular-translate.github.io/docs/#/guide/ or contact Clement Berti (clemthenem)

Impac (Backend):

Sometimes the expressions to translate are set and sent from the backend.
As we need the translation to be simple and easy to manage we want to keep it in the frontend.
In order to be retro-compatible we will need to keep the current data sent by the API and add extra fields called keys.

E.g: the accounts-accounting-values widget

[...]
legend: "Revenue / Asset",
type: 'Overall Turnover',

We add these two keys to be translated in the frontend

legend_key: "impac.widget.accounting_values.turnover.legend",
type_key: "impac.widget.accounting_values.turnover.type",

The backend will then take care of the translation of these keys and falls back into the 'normal' field if no translation exist.