Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 6 Next »

What developers need to know/do

Hudson's i18n support has two aspects that developers need to be aware of.

  1. Generation of type-safe Messages classes from Messages.properties
  2. Marking messages in jelly files

Generation of Messages classes

Hudson uses localizer to generate classes for accessing message resources in a type-safe way. For each src/main/resources/**/Messages.properties, a Messages class is generated. See the referenced page for how this class looks like. If your IDE fails to find these classes, manually add "target/generated-sources/localizer" directory to your source root.

Wherever the code returns a String for display purpose (such as Descriptor.getDisplayName()), use the Messages class to obtain a localized message. At the runtime, a proper locale is selected automatically. A typical workflow for this is as follows:

  1. You identify messages that need be localized
  2. You place that in Messages.properties. One can choose to have this file for each package, or you could just have one such file for the whole module/plugin.
  3. You run mvn compile once to re-generate Messages.java
  4. Update your code to use the newly generated message formatting method

As usual, looking at how the core code does this might help you get the idea of how to do this.

Marking messages in jelly files

Your jelly files in src/main/resources often contain messages that need to be localized, and those need to be marked as well.

In the simplest case, suppose you have a part of a Jelly file that looks like the following:

<h1>Output</h1>
<p>...</p>

Then all you need to do is to change this to the following:

<h1>${%Output}</h1>
<p>...</p>

The ${%...} marker indicates stapler to look for localized resources, and when none is found it'll just print "Output" for this, which is what you want.

Let's consider the case where the localization requires parameters. Suppose you have a Jelly file foo.jelly like this:

<p>Click <a href="${obj.someMethod(a,b,c)}">here</a></p>

In this case, first you have to write foo.properties for the default locale:

click.here.link=Click <a href="{0}">here</a>

Then update foo.jelly to refer to this like this:

<p>${%click.here.link(obj.someMethod(a,b,c))}</p>

If you have multiple parameters you can pass them by separating ',' (just like a function call), and from property files you can reference them as {0}, {1}, etc., by following the MessageFormat class convention.

Finally, let's consider the case where you put a message in an expression like this. Suppose you have a Jelly file like this:

<p>${h.ifThenElse(x,"no error","error")}</p>

You can mark those two strings for localization like this:

<p>${h.ifThenElse(x,"%no error","%error")}</p>

What translators need to know/do

The Hudson project always welcomes contributions to translations. If you are interested in helping us, please drop us a note at dev@hudson.dev.java.net, so that we can give you the commit access. In the reminder of this section, we'll discuss what needs to be translated and how.

Translating Messages.properties

Developers place messages that require localizations in Messages.properties. Those need to be translated in the usual manner. See Messages_ja.properties in the core as an example if you are new to this process.

Sometimes looking at Messages.properties alone doesn't give you enough contextual information as to where the messages are used. For this, developers are encouraged to access messages by using the type-safe Messages class generated by localizer. To find out where messages are actually used, use your IDE to find all the usages of the message format method.

Translating message references in Jelly

The other messages that need to be translated are in Jelly view files, which are in src/main/resources/**.jelly. To localize them, first you run Maven to generate skeleton property file for your locale:

$ cd hudson/main/core  (or hudson/plugins/xyz)
$ mvn stapler:i18n -Dlocale=fr

This will generate a bunch of *_fr.properties all over src/main/resources with an empty value. If the file already exists, it will append missing entries to existing files.

You then need to work on each such property file and translate messages. You don't have to translate the entire file — if you leave some entries empty, they'll fall back to the default locale.

Quick locale switcher firefox extension is useful to toggle between various locales.

Translating static HTML resources

Stand-alone HTML files are often used in Hudson for things like inline help messages. These resources need to be translated by adding the locale code between the file name and the extension. For example, the Japanese version of abc.html would be abc.ja.html, and British version of it could be abc.en_GB.html. These files need to be encoded in UTF-8.

Pushing changes

Once you made some changes, you can commit them. Translators should consider themselves as owning property files for their locale, so feel free to go ahead and just commit. If you are new to this, doing a small commit first is a good idea. You can also always send in a patch if you prefer to be safe.

When starting a translation, try to check if there's anyone else working on the same locale. You can find out who they are by finding existing localization and looking at its CVS history. Try to get in touch with them to avoid a surprise.

  • No labels