Translation Methods

1. Overview

Averos translation could happen either in typescript components or in templates.
Translation could be achieved in three ways:

  • Static Template Translation (i18n / i18n-placeholder attributes)
  • Dynamic Template Translation (translate pipe)
  • Dynamic Translation ($localize)

đźš© A json translation file should be available for the target locale so that the locale ids could be available to the framework. If not, a default value will be used for translation instead.

2. Static Template Translation - i18n / i18n-placeholder attributes

Static Template Translation happens in templates and occurs when either i18n or i18n-placeholder angular/locale related attributes are used in the component’s templates.
A locale identifier referring to a record in the json translation configuration file will be used in order to bring the right translation property.

Below is an example of i18n usage:

json translation configuration:

{
"user.userName": "nom d'utilisateur"
}

Static Template Translation usage:

<mat-label i18n="@@user.userName">UserName</mat-label>

đźš© Notice the use of i18n attribute along with the locale id user.userName.

Component’s placeholders could also be translated using the attribute i18n-placeholder along with a translation id referring to a json translation configuration record.

🚩 The component’s placeholder attribute, though, should be present along with the i18n-placeholder attribute for the translation to be performed. Otherwise, in case one of the two attributes is missing, no translation will be performed.

usage example:

<input matInput i18n-placeholder="@@user.userName" placeholder="UserName" formControlName="userName" required>

<textarea i18n-placeholder="@@user.address.placeholder" placeholder="Your Address" matInput  formControlName="address" maxlength="100" required></textarea>

đźš© In the examples above, notice how i18n-placeholder and placeholder are both included.

3. Dynamic Template Translation - averos translate pipe

Averos framework have included a new pipe called translate which could be used in templates in order to translate dynamic variables.

The translate pipe accepts two inputs, a key_TobeTranslated and a translationID, and returns a localized string.

Note that translationID is optional and could be therefore undefined.

Avers translate pipe could be applied to both template values and attributes. Below are example of usages for both types:

translate applied to template values:

<mat-label>
 	
</mat-label>

<mat-option *ngFor="let gender of genders" [value]="gender.name">
    
</mat-option>


translate applied to template attributes:

placeholder attribute:

<textarea matInput [placeholder]="placeholderTranslationID | translate: placeholderTranslationID" </textarea>

tooltip attribute:

 <button mat-icon-button [matTooltip]="'search'| translate: 'app.search'"> </button>

3. Component’s Dynamic Translation - $localize / translate()

This type of translation is used only in typescript components.
It uses either the angular $localize tag, available in the @angular/localize package, or the translate() utility introduced by averos.

Angular $localize tag supports only fixed locale ids (translationIDs).

If you would like to apply translations to dynamic locale ids then you need to use the averos translate() utility.

3.1. Fixed Locale IDs - Locale Parameters

$localize could only be used with fixed translation IDs.
It is also possible to include translation parameters for further customizations.

Let’s assume that we have the following translationID configuration:

{
"user.logged.message": "Welcome {$userName} !",
}

The translationID refers to a user welcome message.
$userName is a translation parameter that is equal to whatever userName value.

The translation occurs in the component as described below:

let welcomeMessage = $localize`:@@user.logged.message:Welcome ${this.authenticationService.getCurrentloggedUser()}:userName:!`

3.1. Dynamic Locale IDs

Since $localize does not support dynamic translation IDs, averos has introduced an utility, located in @averos-shared/utils/translate, that enhance $localize tag capabilities by adding dynamic translation ID support.

When you don’t know the value of a translationID, it is absolutely fine to use @averos-shared/utils/translate on its translationID references.

usage example:

const validationMessage = translate(validatorMetaData.validationDefaultMessage, validatorMetaData.validationMessageTranslationID);