Page Comparison

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:

- Internationalisation 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 different languages.

Impac Angular (frontend):

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

JSON file

All the translations are kept in data-interchange formats (json, yaml, ...) that are then compiled as an angularjs module.

{
	"my.awesome.translation.of.hello_world": "Hello World",
	"namespace.to.avoid.confusion.or.conflicts": "Each variable has a unique name to avoid conflicts"
}

Each variable is using a common namespace (in this case impac) to avoid potential clashes.

HTML code

Default

In order to translate terms within the HTML code, angular translate gives you several ways (filters or directive):

...

<!-- Favourite syntax -->
<p translate>my.awesome.translation.of.hello_world</p>
<!-- To avoid if possible, but exists  -->
<p>{{'my.awesome.translation.of.hello_world' | translate}}</p>

    -> Better approach

Advanced (translations with variables)

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

...

<!-- Favourite syntax -->
<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:

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

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

Pluralization

You might need to add pluralization to your translations. In order to do that we use an additional module called messageformat.

...

https://angular-translate.github.io/docs/#/guide/

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.

...

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

What you should remember

• NEVER hardcode text in a template or in a directive: use a key that has a translation in the json file

  Code Block
  language xml theme RDark title src/views/**/some-views.html linenumbers true
  <!-- Wrong --> <p>This is wrong</p> <!-- Correct --> <p translate>impac.name.path.this_is_better</p>

  
  

  
  

  
  

  Code Block
  language xml theme RDark title src/locales/en-gb.json linenumbers true
  { "impac.name.path.this_is_better": "This is better" }

  
  

  
  

  
  

...