[jbosstools-dev] Internationalising JBoss Tools

Tue Oct 21 00:00:18 EDT 2008

Max Rydahl Andersen wrote:
>> I've been working on a solution that would make it easy for the Red Hat
>> L10n team to translate JBoss Tools and then include the translations in
>> JBoss Tools.
> 
> Glad to hear it is still moving forward!
> 
>> I now think that we do need file conversion as part of the build.  To
>> avoid the problem of conflicting translations, I would recommend that
>> all translations apart from English live as PO files in the source tree,
>> and their .properties will only be generated as build/runtime artifacts.
> 
> Okey - if that could be done making the "main" builds more or less  
> unaffected
> of the translations that would be great.

I think we might want to add POT-generation (prop2pot) to the nightly
builds, but every time you do a build, you would only enable the i18n
Ant targets if they're needed.  If you disable them, you just end up
with the English-only version.

> Let me see if we can translate this into operational terms ;)
> 
> Got any suggestions on how we structure this and get implemented ?

Well, if we use the Eclipse/Babel approach, we would generate language
packs which can be installed together with the basic JBDS/Tools to
provide translations.

The other option, similar to what Sun does with internationalised
versions of the JRE, is to integrate L10n resources with the main build.
 That way, if you install the internationalised version of Java, you get
one that can run in English or any other supported version.  The problem
with that is that the internationalised version ends up being huge,
because it includes every language.  It's probably more intrusive too,
because I think you would have to modify the build scripts for all the
subcomponents, so as to include L10n resources.  In Sun's case, they
must be running their builds twice, once for English-only, and once for
i18n, presumably because English-speakers don't like downloading the
huge i18n version.

In case you can't tell, I favour the lang-pack approach.  Even with
lang-packs, there's nothing to stop you from packaging the base English
version together with one or all lang-packs, so you can make the user
experience identical if you so choose.

It may depend on what's the best way to generate the lang-pack plugins,
and make them available at runtime, but this is what I was thinking:

I thought we might create a new project, say
http://anonsvn.jboss.org/repos/jbosstools/trunk/org.jboss.tools.translations

(The name can certainly be changed.  And you might want to move it to a
higher directory, to reduce checkout sizes a bit...)

It won't contain any code, just build scripts and PO files

org.jboss.tools.translations/build.xml
org.jboss.tools.translations/pot [not in SVN, generated during i18n builds]
org.jboss.tools.translations/po/ja
org.jboss.tools.translations/po/zh_CN
org.jboss.tools.translations/po/pt_BR
org.jboss.tools.translations/po/es_ES
org.jboss.tools.translations/po/fr_FR
org.jboss.tools.translations/po/de_DE
and perhaps:
org.jboss.tools.translations/po/qps [a pseudo-locale, containg
auto-generated translations, used in testing]

When generated, the pot directory would contain a directory tree which
mirrors http://anonsvn.jboss.org/repos/jbosstools/trunk [specifically,
just the directories which contain .properties files, but translated
into .pot files].  This tarball
<http://seanf.fedorapeople.org/jbosstools/jbosstools-pot.tar.bz2> should
show what I mean.

Each of the po/[locale] directories would contain a similar subtree, but
with PO files rather than POT templates, and hopefully containing some
translated text!

The Ant task po2frag will be responsible for converting
po/[locale]/**/*.po into a language-pack (a collection of plugin
fragments containing .properties files, converted from the .po files)

> Do we for example add a i18n subfolder in each module that needs  
> translation (today we have docs, tests, plugins, features)
> i.e. /trunk/hibernatetools/i18n

Well, as described above, I would recommend keeping the i18n stuff in a
separate subtree, if we can.  That way, it's possible to grant
read-write SVN access to the i18n subtree separately.

Whether that's practical probably depends on how similar the different
projects within jbosstools are.  If each project is built differently,
the fragment generation might have to be done by the individual build
scripts.

> In here will be a .po file for each plugins "Messages" properties file we  
> have.

Almost.  At the moment, it's one .pot (not po, although they're
extremely similar) for virtually every .properties file in the source
tree, because the filenames vary too much.  But if they can be
refactored so that they're always called Messages.properties, that would
be great!

> There will also be a build that generates a fragment (or is it  
> fragement*s*, one for each plugin ?)

As I understand OSGi, every fragment has to have exactly one host
plugin.  So if JBoss Tools has 200 plugins with translatable text, there
will be 200 fragments per language.

> Then if that generates into /trunk/hibernatetools/i18n/build/fragments  
> users who want to see the translations
> just need to run the generation and import the fragments from there ?

This is where my OSGi knowledge really fails me.  In my kludgy testing,
I created a collection of fragment plugin jars
<http://seanf.fedorapeople.org/jbosstools/jbosstools_nl_xxx.tar> and
dumped them under eclipse/plugins.  If it had been Eclipse 3.4, I would
have used eclipse/dropins.

I haven't tried it in a couple of months, but if anyone wants to try,
you need to pass "-nl xxx" to the eclipse command-line, to tell it to
use the xxx pseudo-locale.  If it still works, some of the JBoss-related
strings under Tools/Preferences should have [xxx] prepended, which shows
that the translation fragments have been picked up.

For QA and end-user deployment, you would probably want to create a
feature for each locale, which contains all the fragments for that
locale, and make feature/plugins available from the update site, to be
managed by the Eclipse update manager.  I don't really know how to do
any of that.

For developers, I suspect the dropins approach makes more sense than
generating a feature and using an update manager.  But how do you
normally test changes to JBoss Tools plugins?

Basically, yes, you have to make the fragments available to the Eclipse
runtime, by whatever method makes sense.

For developers testing L10n, perhaps the fragment generation should
target the individual projects (such as
trunk/hibernatetools/i18n/build/fragments) in such a way that they can
be picked up on the Eclipse classpath.  That should be possible, even if
the PO files are kept separately in trunk/org.jboss.tools.translations.

> Or do you see us create the fragments explicitly in e.g.  
> /trunk/hibernatetools/i18n and have a build for each of these
> that goes from .pto to the properties files ? (the property files will not  
> be committed, only be generated) ?

I'm sorry, I'm not sure I understand the distinction from the other
alternative.  (I may have some of the terminology wrong.)  Are you
perhaps talking about creating/managing the fragments' metadata
(MANIFEST.MF) in SVN, rather than generating them?

At present, my kludgy shell script generates fragments which are jar
files comprised of a manifest file (generated by the shell script) and
.properties files (converted from .po files).  And yes, I would avoid
checking in the generated files if possible.

But there may be some good reasons for managing the manifests in SVN
rather than generating them; I don't know.

> And how are these going to be grouped ? One set per language or One set  
> for all languages/group of languages ?

You can group the fragment plugins any way you like, but I would suggest
one lang-pack per language (actually locale, not language).  Each
lang-pack would contain all the fragments for that language, across all
the JBoss Tools plugins.  This means that you might get translations for
plugins you haven't installed, but that's okay.  I suppose you could
have a lang-pack per feature, per language, but (a) it's more work from
a releng perspective and (b) it requires the user to select/install
several lang-packs if they have several features to localise.

And I think each lang-pack would need an associated feature if it's
going to work through an update-site.  I will probably need help with
that part.  And with the best way to integrate into the build process.

-- 
Sean Flanigan

Senior Software Engineer
Engineering - Internationalisation
Red Hat

-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 551 bytes
Desc: OpenPGP digital signature
Url : http://lists.jboss.org/pipermail/jbosstools-dev/attachments/20081021/478a2fcf/attachment.bin 