Author: Bob Jacobsen
Keywords: JMRI technical code I8N internationalization

# 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:

- faire un fichier patch contenant vos modifications. Sur MacOS X ou Linux, cela se fait avec la commande `svn diff java/src> patch.txt` et les utilisateurs de Windows peuvent faire la même chose avec leur application SVN.
- Téléchargez ce fichier sur le tracker "Patches" sur sourceforge:
  http://sourceforge.net/tracker/?group_id=26788&atid=388315.
  Sur cette page:
  - Cliquez sur "New issue" sur le côté gauche
  - Remplissez le "Title" et le "Comment" sur la nouvelle page qui apparaît (vous pouvez Lead Etat, propriétaire, le type et la priorité qu'ils ont),
  - Cliquez sur le boite "I would like to add an attachment" (je voudrais ajouter une pièce jointe) proximité du bas,
  - Puis sélectionnez votre fichier patch en utilisant le bouton "Choisir le fichier".
  - Cliquez sur "Enregistrer" pour télécharger le fichier et informer les gens que vous avez fait cela.

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:

- Créez une copie des fichiers existants depuis le répertoire help/en dans une nouveau répertoire d'help/LL, où LL est la langue code de votre langue, par exemple help/fr. (S'il vous plaît soyez prudent pour faire ceci dans SVN, et demandez à un développeur de l'aide si nécessaire)
- Renommer le fichier help/fr/JmriHelp_en.hs que vous venez de créer pour help/fr/JmriHelp_fr.hs
- Modifier l'help/fr/format.xsl pour créer un`<html lang="fr">` .
- Traduire les fichiers .shtml ci-dessous dans le répertoire help/fr. Ne traduire aucun fichiers .xml, .JHM ou le web*.shtml dans le répertoire racine, car ils sont produit automatiquement.

>

## 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:

- tutoriel Sun internationalisation (fortement recommandé)
- page principale Java Internationalisation

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 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:

- Copiez la classe Bundle `java/src/jmri/jmrit/Bundle.java` dans votre paquet comme: `java/src/jmri/mypackage/Bundle.java`
- Modifier ce nouveau fichier dans trois endroits:
  1. La déclaration "package" en haut devrait inscrire votre paquet
  2. La "class ... extends "devrait se référer à la classe Bundle directement au-dessus de votre paquet
  3. L'affectation de la variable "name" doit être le nom de votre bundle locale, par convention "jmri/mypackage.Bundle".
- Créer un nouveau fichier `Bundle.properties` dans votre répertoire package pour contenir vos propriétés de chaînes de caractères.
- Idéalement, vous allez ajouter une copie de `java/test/jmri/jmrit/BundleTest.java` à votre Répertoire de test JUnit pour vérifier que vos chaînes fonctionnent:
  Copiez `java/test/jmri/jmrit/BundleTest.java` dans `java/test/jmri/mypackage/BundleTest.java` suivie de la modification de la déclaration de votre paquet dans ce fichier pour pointer vers votre paquet, en ajoutant un peu de vos chaînes pour les tests (y compris ceux que vous référencez à partir des bundles parents, le cas échéant), et incluant une référence dans votre classe PackageTest.

#### 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:

- Assurez-vous que votre code se compile et se construit bien dans votre IDE. Nous modifierons la version compilée.
- Exécuter le script "translate.sh" dans votre répertoire de construction java/. Cela crée de nouveaux fichiers properties, temporaires dans l'arbre répertoire classes/. Vous devrez refaire ceci chaque fois que l'arbre classes/ est enlevé par exemple par "ant clean" ou une constructionIDE .
- Effacez le fichier Preferences, ou modifiez le pour enlever la ligne de définition GUI
- Exécutez DecoderPro via "Ant locale", qui démarre le programme DecoderPro en utilisant les nouveaux fichiers de propriétés.

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