[jboss-jira] [JBoss JIRA] Updated: (JBADMCON-154) (MISFILED) Internationalisation (i18n) patch for web- and jmx-console

(MISFILED) Internationalisation (i18n) patch for web- and jmx-console --------------------------------------------------------------------- Key: JBADMCON-154 URL: http://jira.jboss.com/jira/browse/JBADMCON-154 Project: JBoss Admin Console Issue Type: Patch Environment: Developed and tested under Red Hat Enterprise Linux 5.1 Reporter: Sean Flanigan Attachments: jboss_console_i18n.patch G'day all, I'm part of the Red Hat internationalisation team, and I've been working on internationalising the JBoss consoles (web and JMX, not the new admin-console). I was initially working against EAP 4.3, but we decided that we should be following the standard practice of starting with jboss.org, and later putting it into jboss.com releases (like the Fedora->Red Hat process). So I have ported my i18n work to the consoles in AS 5. Fortunately for me, these consoles haven't changed much in years. I am attaching a patch with my internationalisation changes. I'm still waiting on some actual translations from the localisation team, but in the meantime I have generated a simple pseudolocalisation for the locale 'xxx'. If you run the consoles and select the 'xxx' locale, any _static_ text which is still in English but doesn't have lots of "x"s is probably an internationalisation bug. (Dynamically generated text such as MBean information or System properties will not be translated, but labels and headers should be. Note also that the applet will appear in the default language of the server, not the locale of the browser-user. At least for now.) It's not included in this patch, but I have also written an Ant task (Regex2PotTask) which can extract English strings from JSPs which use the scheme described below, and an Ant build script which can run Regex2Pot to extract English, and later convert translated PO files into ResourceBundles (using the native GNU gettext utility "msgcat"). For now, internationalisation is a step which is separate from the build process, and my Ant script doesn't even live inside the jbossas directory tree. Perhaps internationalisation should be kept separate from development concerns. As I said above, "msgcat" is a native utility. I believe Cygwin has a version of msgcat, but I'm not sure how well it would fit into the JBoss build. So integrating string extraction and conversion might be a lot of work. I would appreciate any advice. Or even some help! Known issues: 1. String extraction and conversion is separate from the JBoss build process. This may or may not be a bad thing. 2. String conversion is not pure Java - it requires "msgcat" from the GNU gettext utilities. It should be possible to write a pure-Java replacement. This would probably be a requirement if we wanted to integrate i18n into the JBoss build. 3. The console applet is always in the server's default locale. At present, a lot of the strings shown in the applet are generated in the server, so the applet is forced to use the server's locale in all cases for consistency. I think the strings in question are transferred over JMX, so I'm a little afraid of breaking the JMX semantics. I could either add a Locale parameter to all of the affected JMX calls, assuming I can find them, or perhaps try to defer the ResourceBundle lookup until the last minute, on the client-side. It may not be worth it, since I suspect the average JBoss installation will only be administered in a single language. 4. JBoss AS's log messages and error messages are still in English. That's another project! Regards, Sean. Technical explanation follows: Technical details: The JSPs are internationalised with the help of an entity resolver for the unified expression language (EL). The approach was partially inspired by the Seam i18n mechanism, and looks like this: <title>JBoss Management Console - Server Information</title> becomes: <title>${messages["JBoss Management Console - Server Information"]}</title> The entity resolver also supports MessageFormat arguments: <h1><center>${messages["J2EE Application ''{0}''"][appName]}</center></h1> For plain-Java code called by the JSPs (or embedded in scriptlets), there are some facade classes in front of ResourceBundle, whose main purpose is to handle missing resources/bundles more appropriately. These facades are in the classes org.jboss.console.I18n and org.jboss.jmx.console.I18n, along with a servlet filter, the entity resolver and other helpers in the package org.jboss.varia.i18n. Technical rationale: I really, really tried to use a standard mechanism for internationalising plain-old-JSPs, particularly JSTL, but in the end I had to make something which was inspired by the Seam i18n mechanism: an EL entity resolver which looks up ResourceBundles and formats messages with dynamic values. I had a few main goals: 1. make things easy for programmers: don't make the code hard to read or maintain. 2. fit in with Red Hat's translation workflow: we need to be able to extract English text to GNU "gettext" POT files. 3. no cheating: don't add scriptlets to the JSPs 4. don't break JBoss! For point 1, I think it's very important to keep the English text in the source code, which is where developers are used to seeing it. Externalising the English text into ResourceBundles, with artificial keys like "label.OK" is definitely the default option in Java, encouraged by Sun's JavaDocs, but it is fairly unusual in open-source internationalisation outside Java-land. Managing artificial string keys (creating, purging, ...) is quite difficult in a closed corporate setting, and even harder in the case of distributed development. I know IDEs like Eclipse have tooltip support for looking up ResourceBundles, but only if you fit into the Eclipse i18n scheme. Unfortunately, the Eclipse i18n scheme is a little too closely-coupled to Eclipse's needs. (For instance, it doesn't really support the idea of a server whose clients are using different locales.) For point 2, Red Hat's translation team is used to working with "gettext" POT/PO files, with translation editors and other infrastructure which process them. Gettext also provides a number of command-line utilities which help with merging and cleaning translation/PO files. The approach I chose *does not* use gettext at runtime, nor depend on gettext jars, but it does allow for gettext POT files to be extracted from the source code, and to generate ordinary ResourceBundles (.properties) from the translated PO files. As for point 4, I mentioned that the i18n effort was initially intended for EAP 4.3. This is part of the reason I avoided adding runtime dependencies. Re: Testing - where possible, I have tested things myself, but I don't have the expertise to exercise the consoles fully. In particular, I couldn't get the JMS-related pages to work, even without i18n changes - they seem to depend on extra JMS jars being available; even then I would need to create JBoss MQ channels before the page will render without errors.