Compile time VS Runtime¶

Angular propose 2 possibilités : la gestion de la traduction à la compilation ou lors de l'exécution de l'application.

Nous avons fait le choix de la traduction runtime afin de s'éviter des contraintes d'infrastructure. En effet, la traduction à la compilation génère autant de builds que de langues traduites et nécessite une configuration Apache spécifique. La traduction runtime elle, n'impose que le chargement d'un fichier json contenant les textes traduits lors du chargement de l'application. À noter donc qu'un changement de langue nécessite dans ce cas-là aussi un rechargement de la page.

Implémentation dans le code Angular¶

La librairie installée et utilisée est @angular/localize.

La gestion du multilingue nécessite de taguer chaque libellé à traduire.

Aussi, dans le code Angular, il convient d'utiliser :

l'attribut i18n pour marquer le texte dans les templates de composant
l'attribut i18n- pour marquer les chaînes de texte d'attribut dans les templates de composant
$localize pour marquer les chaînes de texte dans le code

Nous avons fait le choix de spécifier un identifiant de traduction pour chaque tag.

Exemples généraux¶

<element i18n="@@{id}">{string_to_translate}</element>
<element i18n-{attribute_name}="@@{id}" {attribute_name}="{attribute_value}" />
$localize :@@{id}:string_to_translate

Exemples¶

<h1 i18n="@@bonjour-titre">Bonjour</h1>
<img alt="Illustration" i18n-alt="@@commun-illustration" src="../assets/img/image1.svg" />
const titrePage = $localize`:@@bonjour-titre:Bonjour`;

Nomenclature sur le nommage des identifiants¶

Séparateurs : Utilisation exclusive de tirets-du-6 :p
Pas d'accents
Pas de déterminants (ex : creer-bannette et pas creer-une-bannette)
Préfixes
- code-erreur : pour les retours api
  - commun : pour les éléments génériques (ex : vocabulaire métier comme bannette ou critère, ainsi que accueil, administration...)
  - action : pour les boutons (ex: créer, rechercher, annuler...)
  - info : pour les messages d'info (ex : La bannette a bien été créée) et tooltips des formulaires
  - erreur : pour les messages d'erreur (ex : Erreur lors de la création de la bannette) et erreurs des validateurs
  - nom-fichier : pour les fichiers générés par le code (ex : export des résultats de recherche dans un fichier csv)
  - Les éléments qui n'entrent pas dans les précédentes catégories seront préfixés par le chemin du composant dans lequel ils sont utilisés (ex: page-armoire-searchForm-titre pour le titre du formulaire de recherche de la page armoire)
Suffixes
- titre (ex : titre de page, de section)
  - description
  - lc (pour lower-case) : les textes traduits commencent tous par une majuscule, sauf ceux ayant le suffixe lc

Notes :

un terme peut par exemple être considéré comme "commun" même s'il n'est utilisé qu'une seule fois, à partir du moment où on le perçoit comme tel (de manière générale, le vocabulaire métier
un titre de page peut tout à fait ne pas être suffixé par "titre" si par exemple il fait partir des communs (ex: "Recherche")

Extraction des textes à traduire¶

En vagrant ssh, se placer dans le répertoire front puis exécuter la commande suivante : make extract-i18n

Un fichier messages.json dans le répertoire front/src/assets/locales est alors créé. Ce fichier contient tous les textes à traduire (ceux tagués comme expliqué dans le paragraphe "Implémentation dans le code Angular"). Le format est en json sous la forme "clé => valeur", la clé correspondant à l'id spécifié dans le tag i18n. Le fichier messages.json sert de base et est à dupliquer pour chaque langue à traduire.

Ajout de la gestion d'une langue¶

Pour ajouter la gestion d'une nouvelle langue, il suffit de dupliquer le fichier message.json dans le répertoire front/src/assets/locales puis de renommer la copie en message.xx.json, où xx correspond à la locale. Ensuite, remplacer les textes français correspondant aux valeurs du json par leur traduction.

Dans le code Angular, il convient d'ajouter la nouvelle langue comme suit : - dans le fichier front/src/app/main/auth/login/login.component.html, ajouter une option au select encadré par la div ayant la classe language : <mat-option value="xx">NouvelleLangue</mat-option> où xx correspond à la locale

TODO : lorsque la PR apportant le feature flag sera livrée, mettre à jour la doc ainsi => Mettre à jour le manifeste, afin d'activer la nouvelle langue en l'indiquant comme étant disponible.

Traduction française¶

Les textes d'origines sont en français dans le code, il n'y a donc pas de fichier de traduction correspondant à la traduction française.

Remarque : Actuellement, et en fonctionnant ainsi, les textes issus de Kendo ne sont pas traduits et restent en anglais. À noter que ceux-ci seront traduits dans les autres langues, car présents dans le fichier d'extraction de base.

Mise à jour des traductions d'une langue¶

Pour intégrer la traduction de nouveaux textes dans une langue déjà prise en charge, nous procédons actuellement comme suit :

extraction des textes via la commande (voir paragraphe "Extraction des textes à traduire") et création du fichier messages.json
transmission auprès de la société de traduction des fichiers messages.json et de tous les fichiers messages.xx.json présents dans le répertoire front/src/assets/locales
réintégration et écrasement des fichiers messages.xx.json dans l'application par ceux fournis par la société de traduction