Development:i18n

Jalview i18n Best practices

• Follow the standards described in this guide
• Always use properties files for user interface text; never include displayable text in code
• Use properties files only for user interface text (Messages_xx.properties) and config files for configuration settings (jalview.properties).
• Use a proper naming schema for keys in your resource bundles. The name of the keys should provide some information about the context of the displayed text. This helps the translators during the translation process.
• Group keys by view, e.g. edit.title, edit.instructions, list.title, list.instructions, create.title, etc
• Never use displayable text when executing comparisons within the logic of the tool (separate codified values from displayable text)
• Always use the MessageManager class for retrieving properties values, and invoke MessageManager methods dynamically, to accommodate dynamic user preferences (see MessageManager below).
• All numbers and dates should be formatted specific to the user's locale (e.g. java.text.NumberFormat and java.text.DateFormat)
• Test code in more than one language

MessageManager

The jalview.util.MessageManager class is a wrapper class for the ResourceBundle class. It provides dynamic language/locale support for individual users, and is recommended for all Jalview code. To use it within your code, you only have to invoke MessageManager with the text key in Messages_xx.properties:

JButton ok = new JButton(MessageManager.getString("button.ok"));

This will set JButton text to the one included at button.ok key. In English JButton text will be OK, while in Spanish will be Aceptar. This is the big thing of i18n. :)

Don't rely on comparisons of label text

Don't use this type of coding

threshold.addItem("No Threshold");
threshold.addItem("Above Threshold");
threshold.addItem("Below Threshold");
[...]
if (threshold.getSelectedItem().equals("Above Threshold"))
{
 aboveThreshold = AnnotationColourGradient.ABOVE_THRESHOLD;
}
else if (threshold.getSelectedItem().equals("Below Threshold"))
{
 aboveThreshold = AnnotationColourGradient.BELOW_THRESHOLD;
}

Once text has been translated, these equals() will fail as the label won't be the English ones. Use getSelectedIndex() instead of getSelectedItem(). The internationalised code would then look like this:

threshold.addItem(MessageManager.getString("label.threshold_feature_no_threshold"));
threshold.addItem(MessageManager.getString("label.threshold_feature_above_threshold"));
threshold.addItem(MessageManager.getString("label.threshold_feature_below_threshold"));
[...]
if (threshold.getSelectedIndex()==1)
{
 aboveThreshold = AnnotationColourGradient.ABOVE_THRESHOLD;
}
else if (threshold.getSelectedIndex()==2)
{
 aboveThreshold = AnnotationColourGradient.BELOW_THRESHOLD;
}

How to translate Jalview

Anyone interested in localizing/translating Jalview first needs to sign up at http://issues.jalview.org and get in contact with the lead for Jalview's i18n component. You should also put in a request to sign up on the Jalview development list. Oh - don't forget to read the rest of this page, too, before proceeding !

If you are planning on working on a Jalview translation, please first check the list of i18n issues and ensure no-one else is working on it. If they are, you could also contact them to ask if you can help out.

Next, get the source code for the latest version of Jalview. Ideally, you should get this by checking it out from the appropriate branch of our git repository (see Development for info on this}, but you can also grab a tarball for the latest builds of the *current release* and *next release* branches from the link at http://www.jalview.org/development/development-builds.

Creating a new translation

1. Make sure you can compile and launch the Jalview Desktop from source.
2. Create a new issue in the Jalview's i18n component for your translation. You must at least give the two letter country code for the translation in the summary.
3. Edit ``{jalview.home}/resources/lang/Messages_xx.properties`` (where xx refers to your language country code). If it doesn't exist, make a copy of ``Messages.properties`` called ``Messages_xx.properties``.
4. Next step...start translation!

Once you have created your translation, upload and attach it to the issue you created on the i18n component, and then post a message to the jalview-dev list so we can discuss it. Someone will then commit it to the code base as soon possible. Thanks so much for this in advance!

Tips and Gotchas

1. if your translated text is longer than the original, check it fits in the space available; if you're not sure how, ask
2. don't translate strings that may become keys in a saved Jalview Project file, as this would fail to open in a different locale; if unsure, ask
3. note that the Web Service menu items (Alignment, Secondary Structure Prediction, Analysis, Protein Disorder) are (for now at least) hard-wired and should not be translated
4. if you find missing strings in the code that you think should be externalised, include these in your patch (but note that text for all supported languages will need to be added)