JMRI: Internationalisation

Les bibliothèques JMRI sont destinées à être utilisables dans le monde entier. Pour ce faire, ils font usage des fonctionnalités "internationalisation" intégrées dans le langage Java et les bibliothèques.

Utilisation des Locales

JMRI utilise les paramètres locaux par défaut pour localiser l'information d'internationalisation. Cela signifie que JMRI présentera son interface utilisateur dans le langage Java défini comme la valeur par défaut pour cet ordinateur.

Les locales sont spécifiées par une Langue, et éventuellement un Pays. La langue est un code à deux lettres minuscules; le pays est une code de deux lettre majuscules. "en" est l'anglais, "fr" est le français , "de" est l'allemand, et "de_CH" est l'allemand parlé en Suisse.

Lorsque Java cherche des ressources ( voir ), il recherche d'abord un fichier avec la Locale complète en cours à la fin de son nom (foo_de_CH.properties, par exemple). Si cela échoue, il tente un fichier se terminant seulement par la localisation de la langue en cours : foo_de.properties. Et si cela échoue, il va à la valeur par défaut sans suffixe: foo.properties. Un mécanisme similaire est utilisé au sein des fichiers XML.

En installant les fichiers appropriés et en permettant à l'utilisateur de sélectionner la locale par défaut (dans le cadre des préférences avancées), nous pouvons adapter le programme aux différents pays et langues.

Utilisation des Groupement de Ressources

Le texte pour les menus, boutons et les commandes similaires est contenu dans les fichiers propriétés, qui sont accessibles via le mécanisme de groupement* de ressources de java.util.

Par exemple, le fichier de propriétés qui est utilisé pour configurer le fichier panneau contient des lignes telles que: FieldRoadName = Nom de Route: A la gauche du signe égal est le nom de la ressource que le programme utilise pour se référer à la chaîne, à droite du signe égal est la chaîne qui sera affichée.

Par convention, les noms des éléments de ressource de l'interface graphique commence par l'un des termes

  1. Field - pour un champ visible, par exemple, libellé, sur l'interface
  2. Button - pour un bouton de l'interface
  3. Menu - le nom en haut du menu
  4. MenuItem - un élément du menu(peut être un élément imbriqué)
  5. ToolTip - contenu d'une info-bulle
  6. Error - pour un message d'erreur affiché dans le cadre de l'interface graphique
D'autres ressources sont nommées afin de ne pas entrer en conflit avec celles-ci.

S'adapter à un nouvelle langue

Les principales étapes pour adapter JMRI à une nouvelle langue sont les suivantes:
  1. Créer de nouvelles versions des fichier .properties pour changer la langue des contrôles d'interface graphique.
  2. Traduire les fichiers XML pour les décodeurs, programmateurs et configuration.
  3. Traduire les fichiers d'aide et autres pages web.

Obtenir une copie propre du code source depuis le référentiel source JMRI. (Pour plus d'informations pour le faire , Svp voir la page sur l'obtention d'une copie du code.)

Traduction des Fichiers properties

Si elles n'existent pas déjà, commencer par faire des copies des fichiers properties avec un suffixe pour votre nouvelle langue. Sur un Mac OS X ou une machine Unix, ce sera: 
   cd java/src/apps
   cp AppsBundle.properties AppsBundle_xy.properties
et ainsi de suite. La meilleure façon de trouver les suffixes appropriés consiste à définir le programme de votre Langue particulière via les préférences avancées , -->Affichage --> et onglet Langue, quitter et redémarrer le programme, et puis regarder le suffixe que le module JMRI affiche adans l'écran de démarrage/fenêtre principale ( ligne du bas, entre les crochets après la version Java ).. Vous pouvez également consulter la liste officielle des langues (première partie du suffixe) et liste des pays/régions (deuxième partie optionnelle du suffixe).

Vous pouvez ensuite modifier les fichiers dans une langue spécifique pour saisir du texte dans dans votre propre langue.

Les lignes dans le fichier qui contiennent quelque chose comme $Release: $; sont des vestiges des vieux systèmes de contrôle de version; elles peuvent être ignorées ou effacées.

Ils y a plusieurs fichiers .properties* qui sont utilisés qui sont utilisés pour des contrôles internes, et ne doivent pas être traduit. Ils sont marqués par un commentaire en haut du fichier. Les exemples sont les fichiers apps/AppsStructureBundle.properties jmri/web/server/Services.properties et jmri/web/server/FilePaths.properties.

Traduction des Fichiers XML

Le dossier xml/config/parts/jmri/ contient des chaines de texte supplémentaires pour traduire pour les programmeurs etc. Juste comme dans fichier décodeur XML, les chaines traduites sont insérées comme des éléments <name xml:lang="da">Votre Traduction</name> dans chaque nœud. Nous fournissons une liste d'éditeurs pour travailler efficacement sur ces fichiers

vérifier votre travail

  1. Reconstruire votre copie du programme.
  2. Lancez le programme et sélectionnez "Préférences" dans le menu Edition
  3. Cliquez sur la case "Montrer Préférences Avancées"
  4. Choisissez votre langue dans la zone "Locale" de la liste déroulante,
  5. Cliquez sur "Enregistrer", quitter et redémarrer
  6. Vous devez immédiatement voir les articles que vous avez traduit.

S'il ya un problème à ce stade, vérifier pour voir quel est le langage figurant sur l'écran de démarrage de l'application. Montre-t-il le même suffixe (par exemple _fr ou _cs_CZ) que celui donné donné à vos fichiers? Le suffixe que le programme utilise est déterminé par la locale sélectionné dans les préférences ci-dessus.

Pour rendre votre travail disponible aux autres utilisateurs JMRI, s'il vous plaît partager avec nous. Pour ce faire:

En utilisant cet outil de suivi et en fournissant le fichier patch, il est facile pour nous de fusionner vos nouveaux fichiers et/ou fichiers modifiés dans le reférentiel du code. Si quelque chose va mal, s'il vous plaît n'hésitez pas à demander de l'aide à cet égard. >

Traduction Fichiers XML

Les fichiers XML peuvent également être internationalisés. Il y a des exemples dans le répertoire des définitions de décodeurs . Regardez les éléments avec un attribut xml: lang = "fr" attribut. Fondamentalement, vous créez des éléments supplémentaires à cet attribut pour spécifier la langue utilisée: 
<variable label="Vmid" CV="6" default="22" item="Vmid">
  <decVal max="64"/>
  <label> Vmid </label>
  <label xml:lang="fr"> Vmoy </label>
</variables>

Dans les fichiers XML, les attributs de "l'élément" doivent rester non traduit, comme le fait la totalité du fichier xml/names.xml.

Traduire les fichiers d'aide

(Cela n'a été fait qu'une fois, aussi ces instructions peuvent ne pas être complètes)

Les fichiers d'aide en anglais se trouvent dans le répertoire help/en. Si vous voulez créer un ensemble complet de fichiers:

Internationalisation pour les Développeurs

Pour que l'internationalisation fonctionne, vous devez faire quelques choses dans le code que vous écrivez. Quelques références Web sur la façon de le faire: Note: Ce sont 6 liens Java. Il y a des fonctionnalités avancées utiles dans Java 7 et Java 8.

JMRI se dirige vers un ensemble de conventions sur la façon de structurer et utiliser la grande quantité d'informations I18N nécessaire. Vous pourrez toujours trouver le code avec des approches plus anciennes, mais vous devrez écrire un nouveau code à l'aide des nouvelles conventions décrites ci-dessous

Les groupements des ressources JMRI sont organisées dans un arbre hiérarchisé. Par exemple, le code dans le paquet jmri.jmrit.display peut trouver une ressource dans un groupement dans le paquet jmri.jmrit.display, le paquet jmri.jmrit ou enfin le paquet jmri. Comme un cas particulier dans ce domaine, le paquet apps* est considéré comme étant en dessous du paquet jmri lui-même, de sorte que le code dans l'arborescence des apps* peut aussi référencer le paquet jmri.

Les références croisées-paquet, par exemple entre jmri.jmrit et jmri.jmrix, sont découragées et celles qui existent sont supprimées.

L'accès se fait via une classe groupement locale pour chaque paquet. Une caractéristique est une jmri.jmrit.Bundle. Il propose deux méthodes clés á utiliser pour accéder (traduit) à la chaine ressource:

static String getMessage(String key)
static String getMessage(String key, Object ...  subs)

La première offre un accès direct à une chaîne via
String msg = Bundle.getMessage("Titre")

La seconde permet d'insérer des informations spécifiques dans un message du genre
Nom Système LT1 est déjà utilisé

Ici "LT1" ne peut pas être dans le fichier .properties, car il n'est connu seulement que lorsque le programme est exécuté. Différentes langues peuvent mettre cette partie du message dans différents endroits, et accepter que se soit important. Cela a abouti à mettre un espace réservé dans la définition du message: 

Error123 = Nom système {0} est déjà en cours d'utilisation
(Vous pouvez avoir plus d'une insertion, appelée {1}, {2}, etc)

Ensuite, formater le message final en insérant le contenu en elle:
String msg = Bundle.getMessage("Erreur123", badname);

Le premier argument est la clé du message suivie par une ou plusieurs chaînes de caractères à insérer dans le message. (C'est mieux que de créer votre propre chaîne de sortie en utilisant par exemple String.format () car elle permet aux termes insérés d'apparaître dans des ordres différents dans différentes langues.)

Différentes langues peuvent avoir besoin d'un nombre différent de lignes pour exprimer un message, ou peut-être besoin de le casser avant ou après qu'une valeur particulière ait été insérée. Il est donc préférable d'utiliser "\n" dans un un message unique pour créer des sauts de ligne, plutôt que de fournir plusieurs lignes dans le code lui-même.

Certaines parties de JMRI restent en Anglais en raison de notre population de développeurs. En particulier, des commentaires et des noms de variables dans le code doivent rester en Anglais, comme les messages envoyés sur le système de rapport. Dans le code Java, ces chaînes peuvent être marqués avec un commentaire "// NOI18N" ajouté à la fin de la ligne. Si nécessaire, mettre ceci après un autre commentaire:

firePropertyChange("size", oldSize, newSize); // promptly! // NOI18N

Ajout d'un nouveau Bundle*

Si votre paquet ne possède pas déjà une classe Bundle*, vous pouvez l'ajouter par:

Ancien code

L'ancien code référence directement les Bundles: 

   java.util.ResourceBundle.getBundle ("jmri.jmrit.beantable.LogixTableBundle");

L'argument getBundle est le nom du paquet complet (non pas le fichier) pour le fichier propriété de cette classe qui sera utilisé. Vous pouvez avoir à référencer plus d'un de ces objets si vous voulez regarder les chaînes dans plus d'un fichier properties.

Vous pouvez ensuite récupérer des chaînes particulières comme ceci: 

 
java.util.ResourceBundle.getBundle ("jmri.jmrit.beantable.LogixTableBundle") getString ("ButtonNew").;

Nous vous recommandons de ne définir qu'une variable de classe statique pour maintenir la référence à l'objet Bundle, cela finit par consommer beaucoup de mémoire permanente dans un programme de la taille de JMRI. Allez-y et appeler le getBundle () à chaque fois, c'est rapide, car il fonctionne à travers un cache faiblement référencé et nettoyeur de la mémoire.

Accès XML

Deuxièmement, vous devez récupérer correctement des éléments et attributs XML . Le jmri.util.jdom.LocaleSelector fournit une méthode getAttribute (...) qui remplace l'élément de getAttribute JDOM lorsque le contenu de l' attribut aurait pu être internationalisé. Vous pouvez l'utiliser comme ceci: String choice = LocaleSelector.getAttribute (choiceElement, "choice") où "choiceElement" est un objet Element JDOM contenant un (Traduction possible) attribut "choix". "Null" sera retourné si rien n'est trouvé.

Nombres

Les nombres "10*10*10+2+3/10" est écrit dedifférentes manières en des emplacements différents: "1002,3", "1,002.3", "1.002,3" et peut-être d'autres choses.

JMRI fournit un utilitaire utile pour manipuler ceux-ci sur l'entrée:

double d = jmri.util.IntlUtilities.doubleValue("1,002.3");
float  f = jmri.util.IntlUtilities.floatValue("1,002.3");

Notez que cela peut lancer une java.text.ParseException, si l'entrée est non analysable.

Test

Vous devez vérifier que vous avez correctement internationalisé votre code. Nous fournissons un outil pour le faire ce qui crée et traduit automatiquement la version de vos fichiers properties, suivant les idées de Harry Robinson et Arne Thormodsen. (Leur papier sur ceci est une lecture recommandée!) Pour l'utiliser:

Si tout va bien, tout le texte du message aura été traduit en MAJUSCULES. Tout ce que vous avez écrit et qui reste en minuscules n'a pas été complètement internationalisé.

*Apps = Application
*Bundle = Groupement
*Properties = Propriétés
*GUI = Interface Graphique Utilisateur