Outils pour utilisateurs

Outils du site


public:gestion_messages

Gestion des messages de TXM

Objectifs

Les messages affichées dans l'UI de TXM (widgets, console…) doivent être :

  1. externalisés dans un fichier messages.properties
  2. vérifiés :
    1. vérification des nouveaux messages créés (par défaut - en)
    2. vérification des anciens messages modifiés (par défaut - en)
  3. traduits dans des fichiers messages_<code de langue>.properties
    • en
    • fr
    • ru

La première étape doit être fait par les développeurs directement dans le code, les suivantes pas forcément par les développeurs (il reste une dernière étape de ré-intégration des vérifications et traductions).

Solutions

Niveaux d'affichage des messages

TXM 0.8.0

Niveaux de gravité de situations dans TXM

Une situation est :

  • SEVERE : elle a un impact potentiel sur la cohérence du logiciel. On peut afficher des informations sur le logiciel (eg fichier et ligne de code) pour aider le debug
  • WARNING : il y a un impact sur la conformité d'un calcul. Exemple ereur de syntaxe CQL. On peut afficher des informations locales sur le problème (par exemple le caractère dans la CQL où ça commence à poser problème)
  • EN COURS : on peut afficher des indices de progression
  • TERMINÉ : on peut afficher des résultats
Niveaux de logs

Les niveaux de messages de TXM s'appuient sur la classe Level de l'API des logs Java avec l'interprétation suivante :

  • OFF : aucun message n'est affiché (sauf les println - code ancien à faire migrer et macros Groovy)
  • SEVERE : affiche les erreurs destinées à l'utilisateur
  • WARNING : affiche les avertissements destinés à l'utilisateur
  • INFO : affiche les messages réguliers destinés à l'utilisateur
  • FINE : affiche des messages de debug destinés aux debuggeurs et développeurs
  • FINER : affiche des messages de debug plus précis
  • FINEST : affiche des messages de debug avec le maximum de détails
  • ALL : affiche tous les messages

Tous les logs d'un niveau supérieur au niveau courant sont affichés.

TXM se place par défaut au niveau INFO pour afficher les messages réguliers (par exemple, les messages de début et de fin de calcul).

Seuls les messages de niveau supérieur ou égal à INFO doivent être vérifiés et traduits.

Code d'affichage des messages

import org.txm.utils.logger.Log;

...
Log.severe("something went terribly wrong and TXM stop the task! (ಥ﹏ಥ)");
Log.warning("something went wrong but lets go forward... ᕙ(⇀‸↼‶)ᕗ");
Log.info("No problem here! (ノ◕ヮ◕)ノ*:・゚✧");
Log.fine("some high level debug messages ლ(ಠ益ಠლ)");
Log.finer("some moderate debug messages for bugs (╯°□°)╯︵ ┻━┻");
Log.finest("some desperate messages when there is no hope ┻━┻ ︵ヽ(`Д´)ノ︵ ┻━┻");

System.out.println("my debug messages"); // personal debug messages, must be converted to Log.info if destined to user

Traduction&Vérification messages

TXM 0.8.0

Depuis TXM 0.7.9, de nombreux plugins d'extensions ont été créés, à cela s'ajoute les plugins créés pour la modularisation du code de TXM → environ 100 projets

Conventions de création de chaînes à partir de TXM 0.8.0

Méthode

Intervenants :

  • développeurs
  • vérifieurs
  • traducteurs

= Cycle de vie du développement de TXM =

  • passage des pratiques et format des messages 0.7.9 à 0.8.0 beta avec des scripts ordonnés par priorité :
    1. supprimer les messages non-utilisés
    2. renommage automatique des clés
    3. fusion des messages doublons (nécessite le renommage poru avoir un nom de clé intelligible)
    4. transformer les concaténations en bind
  • codage (création et modification des messages)
  • vérification
  • traduction

= Développer des scripts de gestion des chaînes =

  • supprimer les messages non-utilisés
  • transformer les concaténations en bind
  • fusionner les messages doublons
  • renommage/uniformisation des clés (rediscuter du pattern de nommage, voir nommage_symboles_externalisation)
    • renommage explicite des clés en nom de variable Java sous la forme CamelBack d'après le contenu de la chaîne
  • Export/Import des chaînes à vérifier et à traduire
    • Export : créer un fichier unique des chaînes de TXM
    • Import : modification et ajout de
      • fichiers messages_xx.properties dans les sources
      • chaînes dans les sources messages_xx.properties

= Mettre en place des pratiques de création et messages =

  • utiliser systématiquement NLS.bind(“blah blah {0}.”, param)
  • utiliser le nommage des clés choisi

Rq : Quand on utilise “NLS.bind(Messages.BlahBlah, param)” dans le code :

  • si existe pas : ajouter “BlahBlah” Messages.java + ajouter “blah blah {0}.” messages.properties
  • si existe : vérifier le message et si il est paramétré (contient {0})
Externalisation des chaînes

Avant toute traduction, il faut en amont que le code source de TXM soit préparé pour 1) rendre possible une traduction 2) rendre intelligible les chaînes à traduire :

  • les fichiers de configuration : plugin.xml → fichiers OSGI-INF/bundle.properties, contiennent les messages des interfaces RCP
    • titres et tooltips d'éditeurs
    • titres et tooltips des vues
    • titres et tooltips de boutons de toolbar
    • titres des pages de préférences
  • des sources Java des plugins RCP → fichiers messages.properties
    • des widgets SWT
    • des messages de la console
    • ne pas externaliser les messages de log de type dev/debug et utiliser le niveau “finest” pour les messages de log de type dev/debug
    • ajouter des NON-NLS avant et lors de l'externalisation
  • Produire les fichiers “vides” des autres langues “fr”, “ru”

DOC sur les Choice (gestion singulier/pluriel, etc.) : https://docs.oracle.com/javase/tutorial/i18n/format/choiceFormat.html

TXM 0.7.9

Traduction d'un plugin - WordCloud

Ce tutoriel propose un exemple d'une traduction d'extension de TXM, ici l'extension 'WordCloud'.

Dans un plugin, il y a toujours 2 types de fichiers de traduction :

  • Les chaînes des menus (menu principale, barre d'outils, menu contextuels) : dans le dossier OSGI-INF/l10n
  • Les chaînes des messages de la console et des composants graphique de l'éditeur de la fonctionnalité (quand il y en a un associé à la fonctionnalité) : dans le package racine du plugin

Procédure : 1)

  1. Récupérer les fichier sources de l'extension :
    svn checkout https://svn.code.sf.net/p/txm/code/trunk/plugins/WordCloud/WordCloudRCP
  2. Si besoin créer le fichier WordCloudRCP/OSGI-INF/l10n/bundle_lang.properties en copiant le fichier WordCloudRCP/OSGI-INF/l10n/bundle.properties (fichier de langue par défaut en anglais)
  3. Sélectionner les fichiers bundle_lang.properties et bundle.properties
  4. Ouvrir le comparateur de fichier (menu contextuel : Compare With > Each Other
  5. Traduire les messages
  6. Si besoin créer le fichier WordCloudRCP/src/wordcloud/messages_lang.properties en copiant le fichier WordCloudRCP/src/wordcloud/messages.properties (fichier de langue par défaut en anglais)
  7. Sélectionner les fichiers messages_lang.properties et messages.properties
  8. Ouvrir le comparateur de fichier (menu contextuel : Compare With > Each Other
  9. Traduire les messages
Traduire d'autres extensions

Le code source des autres extensions de TXM se trouvent à l'adresse

https://svn.code.sf.net/p/txm/code/trunk/plugins/

. Chaque sous dossier contient 2 projets, il faut prendre celui dont le nom fini par “RCP”

Extension de traduction

Objectif

développement d'une extension “Traduire TXM” pour que les traducteurs est accès à tous les fichiers de trads dans le RessourceBundle editor installé dans TXM

  • ajouter des outils pour supprimer les chaînes non utilisées, pouvoir sélectionner plusieurs clés en même temps, voir la valeur par défaut à coté de la clé
  • ajouter une commande pour partager les modifications
  • l'extension nécessite le redémarrage de TXM pour voir les changements faits dans l'UI
    • ce problème est liée au fonctionnement de la RCP, les chaînes de localization ne sont par défaut pas modifiables/rechargées à la volée, c'est d'ailleurs pour cela que le changement de langue nécessite un redémarrage

Tutoriel

Procédure de traduction dans TXM :

  • Installer TXM 0.8.0
  • Installer l'extension de traduction de TXM : (menu > Installer extension et sélectionner “TXM interface translation toolkit”/“boîte à outils de traduction de l'interface de TXM”
  • Ouvrir l'outil d'aide à la traduction avec le menu principal “Traduire > Ouvrir les outils de traduction”
    • Une vue “Navigator” s'ouvre et affiche tous les modules (plugins .rcp) à traduire et affiche les fichiers “*.properties” qui contiennent les chaînes à traduire.
  • Associer l'éditeur de ressources bundle aux fichiers “*.properties” dans les préférences “Générales > Éditeurs > Association de fichier”
  • Parcourir les messages des modules à traduire :
    • chercher la chaînes “NA_” dans “*.properties” : menu “Traduire > Rechercher des chaînes à traduire”
      • remarque :
        • les fichiers “OSGI-INF/*.properties” traduisent les menu, toolbar, noms d'éditeur, noms de vue
        • les fichiers “src/org/txm/x/y/z/messages/messages.properties” traduisent les éléments de l'interface qui sont affichés à l'intérieur des éditeurs, des vues et de la console
    • double-cliquer sur la première chaîne de la liste à traduire → l'éditeur de ressources bundle s'ouvre
      • ajouter la nouvelle langue (à faire pour la première chaîne seulement)
      • corriger ou ajouter une traduction
      • sauver (avec Ctrl-S)
    • double-cliquer sur la chaînes suivante, etc.
  • Redémarrer TXM pour voir les effets sur les widgets
  • Créer une archive des fichiers “*.properties” : menu “Traduire > Exporter les chaînes traduites”
  • Envoyer l'archive à l'équipe TXM à l'adresse textometrie à ens-lyon.fr
Format d'un fichier de traduction :
  • Chaque message de traduction est associé d'une clé “XXX=” qui peut aider à comprendre où le message sera affiché
  • les signes {0}, {1} représente le 1er argument et le 2e argument qui seront insérés dans la chaine.
  • certains caractères doivent être doublés pour ne pas être interprétés par le format “properties” :
    • ' doivent devenir ''. Par exemple :
      ApplicationWorkbenchAdvisor_16=Nettoyage de l'ancien dossier de sauvegarde des corpus ''{0}''. 
1)
Pour la suite de la procédure, il faut remplacer dans les noms de fichier 'lang' par la langue des messages que l'on souhaite corriger ou ajouter
public/gestion_messages.txt · Dernière modification: 2019/01/10 10:47 par slh@ens-lyon.fr