Author: jcouteau Date: 2010-04-09 11:20:35 +0200 (Fri, 09 Apr 2010) New Revision: 1739 Log: Add documentation and tutorials Added: trunk/src/site/apt/application.apt trunk/src/site/apt/bestPractices.apt trunk/src/site/apt/extendInitializer.apt trunk/src/site/apt/helloWorld.apt trunk/src/site/apt/library.apt trunk/src/site/apt/presentation.apt trunk/src/site/resources/ trunk/src/site/resources/application-i18n.zip trunk/src/site/resources/helloworld.zip trunk/src/site/resources/library-i18n.zip Modified: trunk/ trunk/src/site/apt/index.apt trunk/src/site/site_fr.xml Property changes on: trunk ___________________________________________________________________ Modified: svn:ignore - target *.iml + target *.iml *.ipr Added: trunk/src/site/apt/application.apt =================================================================== --- trunk/src/site/apt/application.apt (rev 0) +++ trunk/src/site/apt/application.apt 2010-04-09 09:20:35 UTC (rev 1739) @@ -0,0 +1,63 @@ +Tutoriel d'application utilisant Nuiton I18n et une librairie utilisant +Nuiton I18n (utilisation de Maven) + + + Dans ce tutoriel nous allons créer une application qui affichera un message + à l'utilisateur et appellera l'unique méthode de la librairie que nous avons + créé dans le tutoriel précédent. Nous supposons donc dans ce tutoriel que vous + avez suivi les deux précédents tutoriels afin de ne pas tout reprendre depuis + le début. + +* Configuration du plugin I18n + + Dans la configuration du plugin I18n, nous allons rajouter le goal bundle. Ce + goal récupère toutes les chaînes de charactère de l'application et de ses + librairies afin de créer un bundle unique. + +------------------- +<goal>bundle</goal> +------------------- + +* Le code de l'application + + Lors des précédents exemples, nous utilisions les valeurs par défaut de Nuiton + I18n, mais afin d'optimiser le chargement, dans une application finale, il est + nécéssaire de changer l'initialiseur. L'initialiseur par défaut, + ClassPathI18nInitializer, recherche dans le classpath tous les bundles I18n + afin de les charger, cependant, comme notre plugin crée un bundle regroupant + toutes les chaines i18n, nous pouvons utiliser un DefaultI18nInitializer, qui + prend en paramètre le nom du bundle créé par le plugin, ce dernier ne chargera + que le bundle en question, ce qui peut faire économiser jusqu'à une dizaine de + secondes au démarrage de l'application, suivant la taille du classpath. + +------------------------------------------------------------------------------- +package org.myOrganisation.myApplication; + +import org.myOrganisation.myLibrary.myLibrary; +import static org.nuiton.i18n.I18n._; +import static org.nuiton.i18n.I18n.init; +import static org.nuiton.i18n.I18n.setInitializer; +import org.nuiton.i18n.init.DefaultI18nInitializer; + +public class myApplication { + + public static void main(String[] args){ + + setInitializer(new DefaultI18nInitializer("myApplication-i18n")); + init("fr","FR"); + + System.out.println(_("String to translate in my application")); + myLibrary.myMethod(); + } +} +------------------------------------------------------------------------------- + +* Configuration + + Vous ne devrez pas oublier de préciser le classpath et la classe principale + dans la configuration des plugins Maven. + +* Sources du tutoriel + + {{{./application-i18n.zip}Sources du tutoriel}} + Added: trunk/src/site/apt/bestPractices.apt =================================================================== --- trunk/src/site/apt/bestPractices.apt (rev 0) +++ trunk/src/site/apt/bestPractices.apt 2010-04-09 09:20:35 UTC (rev 1739) @@ -0,0 +1,15 @@ +Nuiton I18n Best Practices + +* Choose a pattern and follow it + + In an application or a library, you should choose a pattern for the i18n keys. + You can either choose to use keys like myapplication.key1 or sentences like + 'My application string'. Once you made your choice, stick to it to keep a + consistency in your application. Note that in an application, you can choose a + different pattern than the one used in the dependencies. + +* Always use DefaultI18nInitializer in final applications + + This is not an obligation, but as it makes you gain time at your application + initialisation, it is really advised to use DefaultI18nInitializer for all + your final applications. Added: trunk/src/site/apt/extendInitializer.apt =================================================================== --- trunk/src/site/apt/extendInitializer.apt (rev 0) +++ trunk/src/site/apt/extendInitializer.apt 2010-04-09 09:20:35 UTC (rev 1739) @@ -0,0 +1,3 @@ +Extend Initializer to suit exactly your needs + + TODO Added: trunk/src/site/apt/helloWorld.apt =================================================================== --- trunk/src/site/apt/helloWorld.apt (rev 0) +++ trunk/src/site/apt/helloWorld.apt 2010-04-09 09:20:35 UTC (rev 1739) @@ -0,0 +1,94 @@ +Nuiton I18n Hello World + + Ce premier tutorial a pour objectif de vous montrer comment se servir de la + librairie Nuiton I18n de la manière la plus simple qui soit. Nous allons créer + une classe Main qui affiche le texte Hello World, puis nous allons traduire + ce texte en plusieures langues. + + La classe java correspondante ressemble à ça : + +---------------------------------------------------------------------------- +import static org.nuiton.i18n.I18n._; +import static org.nuiton.i18n.I18n.n_; + +class HelloWorld { + + public static void main (String[] args){ + System.out.println(_("Hello World")); + System.out.println(n_("Goodbye World")); + } +} +---------------------------------------------------------------------------- + + Si on compile et qu'on lance cette classe (attention a bien mettre les jar + de nuiton-i18n, commons-logging et commons-beanutils dans le classpath ou ça + ne fonctionnera pas), on obtiendra le résultat suivant : + +------------- +Hello World +Goodbye World +------------- + + Cherchons maintenant à traduire ces chaînes de charactères. Nous allons créer + un fichier de ressources nommé helloWorld_fr_FR.properties que nous mettrons + dans un dossier i18n et qui contient les chaînes + traduites dans la langue souhaitée. Par exemple ici en français (Attention, + tous les caractères spéciaux et espaces doivent être échappés par \ ). + +---------- +Hello\ World = Bonjour le monde +Goodbye\ World = Au revoir le monde +---------- + + On recompile et teste la classe (mettre le répertoire contenant i18n dans le + classpath ou Nuiton I18n ne récupèrera pas le fichier de propriété). On + s'aperçoit que rien n'a changé, mais cela est tout à fait normal, le système + n'a pas été initialisé. Nous allons donc modifier notre classe en rajoutant + la ligne + +---- +org.nuiton.i18n.I18n.init("fr","FR"); + +---- + + avant le premier appel à la librairie Nuiton I18n. Cela a pour effet de dire + à Nuiton I18n quelle langue utiliser (en l'occurence le français). Il + recherche donc dans le classpath tous les fichiers i18n/????fr_FR et les + charge. + + Pour tester il suffit de recompiler et de relancer l'application, vous devriez + obtenir : + +---- +2 avr. 2010 16:13:29 org.nuiton.i18n.init.I18nInitializer resolvBundles +INFO: 1 bundle(s) found, in 1 file(s). +2 avr. 2010 16:13:29 org.nuiton.i18n.I18nStore init +INFO: 1 bundle(s) found, [1 file(s)]. +2 avr. 2010 16:13:29 org.nuiton.i18n.I18nStore addLanguage +INFO: I18nLanguage <locale: fr_FR, nbStences:2>, nbEntries: 1, nbSentences: 2. +Bonjour le monde +Goodbye World +---- + + Cela peut parraitre étrange mais c'est tout à fait normal. Les premières + lignes vous renseignent de l'évolution de l'initialisation. Ce sont des logs + qui proviennent de Nuiton I18n. On peut y voir le nombre de Bundles trouvés. + Dans notre cas 1. Et au moment du choix de langue, la locale chargée et le + nombre de chaînes trouvées. Dans notre cas : 2. Ensuite apparait notre + application traduite. Oui, mais la dernière ligne n'est pas traduite me + direz-vous. Et bien si vous reprenez la classe que nous avons écrite, la + chaîne Goodbye World est passée en paramètre de la méthode n_() et non de la + méthode _(). La méthode n_() indique une chaîne qui est traduite à d'autres + endroits de l'application mais qui ne doit pas être traduite ici. Elle est + donc remplacée par la chaîne non traduite. + +Félicitation, vous venez de traduire votre première application avec Nuiton I18n + + Les sources de ce tutoriel sont téléchargeables + {{{./helloworld.zip}ici}}. Elles sont packagées + avec les librairies nécessaires à la compilation et l'exécution de cet + exemple. + +Sources du tutoriel + + {{{./helloworld.zip}Sources du tutoriel}} Modified: trunk/src/site/apt/index.apt =================================================================== --- trunk/src/site/apt/index.apt 2010-04-04 09:52:09 UTC (rev 1738) +++ trunk/src/site/apt/index.apt 2010-04-09 09:20:35 UTC (rev 1739) @@ -1,14 +1,33 @@ ----- + Nuiton I18n + ---- +2010-04-02 ---- -2009-11-02 ----- -Présentation + Le projet Nuiton I18n fournit des classes Java pour l'internationalisation + (i18n) des applications. - Projet I18n de traduction composé de trois modules : + Cette librairie très légère combine les très utilisés ResourceBundles Java, une + API simple d'utilisation et très puissante ainsi qu'un procédé d'extension très + utile. De nombreux autre avantages existent à utiliser Nuiton I18n : + - Extraction des clés de traduction + + - Integration au process de build au travers de Maven ou Ant + + Petit exemple qui démontre la simplicité d'utilisation de Nuiton I18n : + +----------------------------------------------------------------------------- +I18n.init(Locale.FR); +System.out.println(I18n._("This text will be translated")); +----------------------------------------------------------------------------- + + Jettez un oeil aux tutoriaux pour voir comment enrichir votre application + avec Nuiton I18n. + + Les trois modules du projet Nuiton I18n : + - {{{./nuiton-i18n/index.html}I18n Api}} - {{{./maven-i18n-plugin/index.html}I18n Maven Plugin}} Added: trunk/src/site/apt/library.apt =================================================================== --- trunk/src/site/apt/library.apt (rev 0) +++ trunk/src/site/apt/library.apt 2010-04-09 09:20:35 UTC (rev 1739) @@ -0,0 +1,182 @@ +Tutoriel de librairie utilisant Nuiton I18n (utilisation de Maven) + +* Pourquoi un tutoriel différent pour une librairie et pour une application +finale ? + + Lorsque l'on crée une application finale, au moment du build, on crée un + bundle regroupant les chaînes de l'application et de ses dépendances afin + d'optimiser le chargement de l'application (on peut ainsi économiser jusqu'à + plusieurs secondes au démarrage). Lorsque l'on crée une librairie, aucun + bundle n'est réalisé, l'utilisation et la configuration de la librairie est + donc plus simple. + +* Le tutoriel + + Dans ce tutoriel nous allons créer une librairie avec une classe unique qui va + juste afficher un message dans les logs. C'est ce message qui sera traduit. + +* Créons le projet Maven et configurons le plugin Nuiton I18n + + Créons un projet Maven standard. Dans le pom.xml, nous allons configurer le + plugin Maven Nuiton I18n. + +------------------------------------------------------------------------------- +<plugin> + <groupId>org.nuiton.i18n</groupId> + <artifactId>maven-i18n-plugin</artifactId> + <version>1.2.1</version> + <executions> + <execution> + <goals> + <goal>parserJava</goal> + <goal>gen</goal> + </goals> + </execution> + </executions> +</plugin> +------------------------------------------------------------------------------- + + Dans la configuration du plugin, nous spécifions les goals à effectuer. Le + goal parserJava extrait toutes les chaînes de charactère à traduire du code + java. Le goal gen récupère le fichier de resource contenant les chaînes déjà + traduites et y ajoute les chaînes extraites par le goal parserJava qui ne sont + pas déjà présentes. Vous pouvez ensuite traduire les chaînes. + + Afin que le plugin fonctionne, il ne faut pas oublier d'ajouter la librairie + Nuiton I18n dans les dépendances. + +------------------------------------------------------------------------------- +<dependency> + <groupId>org.nuiton.i18n</groupId> + <artifactId>nuiton-i18n-api</artifactId> + <version>1.2.1</version> + <scope>compile</scope> +</dependency> +------------------------------------------------------------------------------- + + Comme nous réalisons un import static, il faut configurer le plugin maven de + compilation + +------------------------------------------------------------------------------- +<plugin> + <artifactId>maven-compiler-plugin</artifactId> + <version>2.1</version> + <configuration> + <source>1.6</source> + <target>1.6</target> + <encoding>UTF-8</encoding> + <showDeprecation>true</showDeprecation> + <showWarnings>true</showWarnings> + </configuration> +</plugin> +------------------------------------------------------------------------------- + + Et pour récupérer le plugin et la librairie Nuiton I18n, il ne faut pas + oublier d'ajouter les dépots nuiton. + +------------------------------------------------------------------------------- +<repositories> + + <!-- depot des releases nuiton --> + + <repository> + <id>nuiton.release</id> + <name>NuitonReleaseRepository</name> + <url>http://maven.nuiton.org/release</url> + <snapshots> + <enabled>false</enabled> + </snapshots> + <releases> + <enabled>true</enabled> + <checksumPolicy>warn</checksumPolicy> + </releases> + </repository> + + <!-- depot des snapshots nuiton --> + + <repository> + <id>nuiton.snapshot</id> + <name>NuitonSnapshotRepository</name> + <url>http://maven.nuiton.org/snapshot</url> + <snapshots> + <enabled>true</enabled> + <checksumPolicy>fail</checksumPolicy> + </snapshots> + <releases> + <enabled>false</enabled> + </releases> + </repository> + +</repositories> + +<pluginRepositories> + + <!-- depot des releases nuiton --> + + <pluginRepository> + + <id>nuiton.release</id> + <name>NuitonReleaseRepository</name> + <url>http://maven.nuiton.org/release</url> + <snapshots> + <enabled>false</enabled> + </snapshots> + <releases> + <enabled>true</enabled> + <checksumPolicy>warn</checksumPolicy> + </releases> + </pluginRepository> + + <!-- depot des snapshots nuiton --> + + <pluginRepository> + <id>nuiton.snapshot</id> + <name>NuitonSnapshotRepository</name> + <url>http://maven.nuiton.org/snapshot</url> + <snapshots> + <enabled>true</enabled> + <checksumPolicy>fail</checksumPolicy> + </snapshots> + <releases> + <enabled>false</enabled> + </releases> + </pluginRepository> + +</pluginRepositories> +------------------------------------------------------------------------------- + +* Créons notre librairie + + Notre librairie, pour faire simple, ne contiendra qu'une classe et une + méthode statique + +------------------------------------------------------------------------------- +package org.myOrganisation.myLibrary; + +import static org.nuiton.i18n.I18n._; + +public class myLibrary { + + static public void myMethod(){ + System.out.println(_("My message to translate")); + } +} +------------------------------------------------------------------------------- + +* Premier build + + Lorsque vous buildez votre librairie pour la première fois avec la commande + mvn compile, vous devez obtenir la création de deux nouveaux fichiers de + ressource contenant chacun la chaîne à traduire sans traduction. + + Vous pouvez traduire la chaîne de charactère dans les deux langues, vous aurez + alors la traduction disponibles dans vos prochains builds. + +* Second build + + Si vous buildez de nouveau la librairie, puis l'intégrez dans une application + finale utilisant Nuiton I18n, le message sera affiché traduit. + +* Sources du tutoriel + + {{{./library-i18n.zip}Sources du tutoriel}} Added: trunk/src/site/apt/presentation.apt =================================================================== --- trunk/src/site/apt/presentation.apt (rev 0) +++ trunk/src/site/apt/presentation.apt 2010-04-09 09:20:35 UTC (rev 1739) @@ -0,0 +1,29 @@ +Présentation + + La librairie Nuiton I18n a un fonctionnement relativement simple. Les chaînes + à traduire sont simplement marquées par la méthode I18n._("Chaîne à traduire"). + Il est possible de marquer des chaînes à ne pas traduire par la méthode + I18n.n_("Chaîne à ne pas traduire"). + + La librairie doit être initialisée au lancement de votre application par une + des méthodes I18n.init() qui peuvent prendre en paramètre, une locale, une + chaîne décrivant la langue,... + + Les chaînes à traduire doivent être rentrées dans un fichier de propriétés + situé dans le classpath de votre application, dans un dossier i18n, et nommé + de la manière suivante : xxx-fr_FR.properties par exemple. + + A l'initialisation, la librairie recherche dans le classpath tous les fichiers + de traduction correspondant à la langue définie (dans les dossiers i18n du + classpath à proprement parler) et charge toutes les traductions correspondant + à la langue affichée. Ensuite, à l'affichage, à chaque fois qu'une chaîne est + demandée, I18n retourne la chaîne traduite dans la langue souhaitée. + + Le plugin Maven permet de rechercher automatiquement les chaînes non traduites + dans le code source de l'application, de les rajouter dans les fichiers de + ressources et de créer un bundle regroupant toutes les chaînes et traductions + de l'application et de ses dépendances. + + Pour comprendre comment bien utiliser la librairie Nuiton I18n, il est + fortement conseillé de suivre les tutoriaux, et de préférence dans l'ordre, + ces derniers étant de complexité croissante. Added: trunk/src/site/resources/application-i18n.zip =================================================================== (Binary files differ) Property changes on: trunk/src/site/resources/application-i18n.zip ___________________________________________________________________ Added: svn:mime-type + application/octet-stream Added: trunk/src/site/resources/helloworld.zip =================================================================== (Binary files differ) Property changes on: trunk/src/site/resources/helloworld.zip ___________________________________________________________________ Added: svn:mime-type + application/octet-stream Added: trunk/src/site/resources/library-i18n.zip =================================================================== (Binary files differ) Property changes on: trunk/src/site/resources/library-i18n.zip ___________________________________________________________________ Added: svn:mime-type + application/octet-stream Modified: trunk/src/site/site_fr.xml =================================================================== --- trunk/src/site/site_fr.xml 2010-04-04 09:52:09 UTC (rev 1738) +++ trunk/src/site/site_fr.xml 2010-04-09 09:20:35 UTC (rev 1739) @@ -18,8 +18,20 @@ <menu name="Utilisateur"> <item name="Accueil" href="index.html"/> + <item name="Présentation" href="presentation.html"/> + <item name="Best Practices" href="bestPractices.html"/> </menu> + <menu name="Tutoriaux"> + <item name="Hello World" href="helloWorld.html"/> + <item name="Librairie" href="library.html"/> + <item name="Application finale" href="application.html"/> + </menu> + + <menu name="Développeur"> + <item name="Etendre Initializer" href="extendInitializer.html"/> + </menu> + <menu ref="modules"/> <menu ref="reports"/>