Author: tchemit Date: 2009-08-26 00:26:47 +0200 (Wed, 26 Aug 2009) New Revision: 1663 Modified: trunk/maven-i18n-plugin/changelog.txt trunk/maven-i18n-plugin/src/site/apt/usages.apt Log: - improve docs - update changelog Modified: trunk/maven-i18n-plugin/changelog.txt =================================================================== --- trunk/maven-i18n-plugin/changelog.txt 2009-08-25 22:26:12 UTC (rev 1662) +++ trunk/maven-i18n-plugin/changelog.txt 2009-08-25 22:26:47 UTC (rev 1663) @@ -1,4 +1,9 @@ -1.0.0 ? +1.0.1 chemit 20090825 + * [FIX] #27 : regex no more compatible with plexus-utils + * [FIX] #29 : urls of plugin download are wrong + * [FEATURE] : improve the documentation of the plugin + +1.0.0 chemit 20090823 * migrate to groupId org.nuiton 0.12 chemit 20090511 Modified: trunk/maven-i18n-plugin/src/site/apt/usages.apt =================================================================== --- trunk/maven-i18n-plugin/src/site/apt/usages.apt 2009-08-25 22:26:12 UTC (rev 1662) +++ trunk/maven-i18n-plugin/src/site/apt/usages.apt 2009-08-25 22:26:47 UTC (rev 1663) @@ -5,4 +5,229 @@ 2009-08-22 ---- - <To be done...> \ No newline at end of file +How it works + + The i18n plugin works in at least two phases : + + * first, it parses some sources to build for each bundle a called <getter> file + which contains all keys found in sources. + + * in a second time, the <getter> files are merged with the existing translations + files. + + * at last, we can make a optimized bundle which merge the module i18n with all + his dependencies (this is good idea when the module is a final application... + see below section) + +* directory layout + + Here is the directory layout convention used by the plugin + +----------------------------------------------------------------------------- + + mymodule + | + +- src + | | + | +- main + | | + | +- resources + | | + | +- i18n + | | + | +- mymodule-fr_FR.properties + | +- mymodule-en_UK.properties + | + +- target + | + +- classes + | | + | +- META-INF + | | + | +- mymodule-i18n-definition.properties + | +- mymodule-i18n-fr_FR.properties + | +- mymodule-i18n-en_UK.properties + | + +- generated-sources + | + +- i18n + | + +- mymodule-fr_FR.properties + +- mymodule-en_UK.properties + + +----------------------------------------------------------------------------- + +* Parse files + + The plugin offers some build-in parsers, each parser has his goal prefix by <parser> : + + * parserJava : parse some java source files to detect <I18n._> and <I18n.n_> invocations in code + + * parserJaxx : parse some {{{http://maven-site.nuiton.org/jaxx}jaxx}} files. This goal is deprecated + + * parserSwixat : parse some swixat files + + * parserValidation : parse some xWorks validation files + + Each parser goal has some default values, if you respect the plugin conventions, + you should have nothing to configure. + +----------------------------------------------------------------------------- +<plugin> + <groupId>org.nuiton.i18n</groupId> + <artifactId>maven-i18n-plugin</artifactId> + <executions> + <execution> + <goals> + <goal>parserJava</goal> + </goals> + </execution> + </executions> +</plugin> +----------------------------------------------------------------------------- + + will parse all java files in <src/main/java> and will generate the <getter> files + in <target/generated-sources/i18n>. + + Moreover, it is possible to defined more directories to be scanned, like in next + example, where we also scan the <src/main/java2> : + +----------------------------------------------------------------------------- +<plugin> + <groupId>org.nuiton.i18n</groupId> + <artifactId>maven-i18n-plugin</artifactId> + <configuration> + <entries> + <entry> + <basedir>src/main/java2/</basedir> + </entry> + </entries> + </configuration> + <executions> + <execution> + <goals> + <goal>parserJava</goal> + </goals> + </execution> + </executions> +</plugin> +----------------------------------------------------------------------------- + + The entries can be more complex. + + For example, it is possible to filter via some includes/excludes, or + attach the entry only for a specific parser via the <specificGoal> property. + + When using an entry, the default entry for the parser is not used, but it can + be activated via the <treateDefaultEntry> property. + +----------------------------------------------------------------------------- +<plugin> + <groupId>org.nuiton.i18n</groupId> + <artifactId>maven-i18n-plugin</artifactId> + <configuration> + <treateDefaultEntry>true</treateDefaultEntry> + <entries> + <entry> + <basedir>src/main/java2/</basedir> + <includes> + <include>**/*.guix</include> + </includes> + <specificGoal>parserJaxx</specificGoal> + </entry> + </entries> + </configuration> + <executions> + <execution> + <goals> + <goal>parserJava</goal> + <goal>parserJaxx</goal> + </goals> + </execution> + </executions> +</plugin> +----------------------------------------------------------------------------- + + + Consult the javadoc of the <org.nuiton.util.SourceEntry> class in + {{{http://maven-site.nuiton.org/maven-helper-plugin/apidocs/index.html}maven-helper-plugin}} + library. + +* Build bundles + + After the files were parsed, it is time to build the i18n bundles of the module. + + * The default location of those files are in <src/main/resources/i18n>. + + * The default file names of the bundles are <artifactId-bundle.properties> + +** The gen goal + + the <gen> goal rebuild those files, using the getter files previously builded. + +----------------------------------------------------------------------------- +<plugin> + <groupId>org.nuiton.i18n</groupId> + <artifactId>maven-i18n-plugin</artifactId> + <executions> + <execution> + <goals> + <goal>gen</goal> + </goals> + </execution> + </executions> +</plugin> +----------------------------------------------------------------------------- + +** The bundle goal + + The <bundle> goal build the bundles for a final application which aggregate + all i18n bundles of all dependencies of the module. + + This is a good idea to do it, since the loading of the runtime <i18n> system + is much more faster with only one file to deal with. + + The final bundles builded will be placed directly in <target/classes/META-INF> since + this is an only runtime bundle and it should never to add in module's sources. + +----------------------------------------------------------------------------- +<plugin> + <groupId>org.nuiton.i18n</groupId> + <artifactId>maven-i18n-plugin</artifactId> + <executions> + <execution> + <goals> + <goal>bundle</goal> + </goals> + </execution> + </executions> +</plugin> +----------------------------------------------------------------------------- + +* All in one + + +----------------------------------------------------------------------------- +<plugin> + <groupId>org.nuiton.i18n</groupId> + <artifactId>maven-i18n-plugin</artifactId> + <executions> + <execution> + <goals> + <goal>parserJava</goal> + <goal>gen</goal> + <goal>bundle</goal> + </goals> + </execution> + </executions> +</plugin> +----------------------------------------------------------------------------- + +And there is more for you! + + There is some other interesting properties in the plugin, for example it is + possible to translate the new i18n key detected while parsing via a swing ui. + + To see all the features of the plugin, consult the + {{{plugin-info.html}goals details}} page.