Traductions - TecostNetwork/Network GitHub Wiki

De manière générale

Lorsqu'on définit une clé de traduction, il y a deux possibilités : 

• Soit on utilise le préfixe "/". Par exemple "/My text" génère une traduction "/My text"
• Soit on ne l'utilise pas. Par exemple "My text" génère une traduction selon la page affichée "/path/to/page/x/My text" ou "/path/to/page/y/My text"

L'inconvénient de la seconde méthode est qu'une même traduction n'est pas réutilisée, et demande du travail lors du développement car il faut traduire des clés existantes (en les faisant hériter). Elle est justifiée pour les éléments propres à un écran, mais pas pour les popups, composants ou fragments qui peuvent être inclus dans de nouvelles pages. Aussi, pour un mot couramment utilisé (chercher, éditer...) ou pour des mots récurrents dans certains thèmes et utilisés dans plusieurs pages et popups (unité de concentration, forme galénique) il est intéressant de les préfixer. 

Ce n'est pas toujours facile de distinguer quand il faut ou non préfixer une clé de traduction. Le tableau ci-dessous tente de répondre aux cas principaux : 

Cas	Exemple	Clé à utiliser
Pour les mots génériques	"Save", "Edit", "Search"...	"/Save"
Pour les mots propres à une popup, composant ou fragment	"Create new applicant"	"/MyPopupName/Create new applicant"
Pour les mots propres à un thème spécifique	"Concentration unit", "Galenic form"...	"/Drugs/Concentration unit"
Pour les mots propres à un écran	"List of all requests"	"List of all requests"

Pour les enums

Les Enums doivent implémenter l'interface IRootTranslationOnly. 

Ceci permet de générer une clé de traduction "root" avec la valeur d'enum, commune à toutes les pages où les valeurs seraient traduites. Par exemple RequestStatusType.PENDING génère la clé "/RequestStatusType.PENDING". Si on ne l'utilise pas, on obtient des clés préfixées par le nom de la page où l'enum est utilisée, et il faut traduire à chaque fois pour toutes les pages possibles (et futures).

Dans un code java on peut utiliser : 

Translator.$(myEnumValue)
Translator.$(RequestStatusType.PENDING)
myEnumValue.getTranslation()
RequestStatusType.PENDING.getTranslation()

Dans un code xhtml on peut utiliser : 

<t:out value="#{request.status.translation}"/>

Dans un test unitaire, il faut utiliser les valeurs traduites lorsqu'on veut faire des comparaisons ou assertions. Il ne faut JAMAIS comparer une valeur d'enum avec un texte fabriqué. La raison est simple : le texte produit sur la page html est la valeur traduite de l'enum, qu'elle ait été traduite ou non en anglais (langue des tests). Il est donc beaucoup plus sûr et moins casse-tête de comparer la valeur traduite de l'enum avec le texte produit à l'écran.

//Bons exemples
Assert.assertEquals(Translator.$(myExpectedEnumValue), getText("id:to:enum:text"));
Assert.assertEquals(myExpectedEnumValue.getTranslation(), getText("id:to:enum:text"));

//Mauvais exemples
Assert.assertEquals("RequestStatusType.PENDING", getText("id:to:enum:text"));
Assert.assertEquals("PENDING", getText("id:to:enum:text"));
Assert.assertEquals("En traitement", getText("id:to:enum:text"));

Transférer les traductions d'un projet à l'autre

Lorsqu'on veut récupérer des traductions pour les mettre dans un autre projet (après avoir frameworkisé une fonctionnalité par ex.), il faut passer par la fonctionnalité des traductions et ne pas essayer de copier les traductions depuis les fichiers XML directement (au cas où la structure a changé depuis la création de la traduction).