View source for Development:i18n:docs


== 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, ie. 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 comparisons on labels

; 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_thereshold"));
 threshold.addItem(MessageManager.getString("label.threshold_feature_above_thereshold"));
 threshold.addItem(MessageManager.getString("label.threshold_feature_below_thereshold"));
 [...]
 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 [http://issues.jalview.org/browse/JAL/component/10682 Jalview's i18n component]. You should also put in a request to sign up on the [http://www.jalview.org/mailman/jalview-dev 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 [http://issues.jalview.org/issues/?jql=component%20%3D%20i18n%20AND%20project%20%3D%20JAL 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====
# Make sure you can compile and launch the Jalview Desktop from the source.
# Create a new issue in the [http://issues.jalview.org/browse/JAL/component/10682 Jalview's i18n component] for your translation. You must at least give the two letter country code for the translation in the summary.
# Edit ``{jalview.home}/resources/lang/Messages_xx.properties`` (where *xx* refers to your language country code). If it doesn't exits, make a copy of ``Messages.properties`` called ``Messages_xx.properties``.
# Next step...start transtalation!
# Once you have created your translation, upload it as an attachment to the issue you created on the i18n component, and then post a message to the Jalview Development List so we can discuss it. Once everyone is happy, we'll commit it to the code base.

Thanks so much for this in advance!