Product \ internationalisation

main Tutorial

Overview

Take a look at the following two user interfaces.
Basic UI   Translated UI

The Basic UI is exactly the same Java code as the Translated UI. The translated UI was provided an text file at runtime which contains translated versions of the original texts. The translation file for the translated user interface is provided below:

Java code

Lets see some Java code on how this is accomplised! The following code shows a very simple untranslated user interface, it contains a label that is shown on a window. We are going to change this minimum UI example later to provide i18n;

FastGui looks like this:

In order to make sure the line of text on screen is shown correctly in whatever country or language we have to ask the Translator class for the translated version before placing it on screen.
This is accomplised by calling the i18n method:

the translate method is implemented like this:

The name 'fastgui' which is used as an argument to the instanciation of Translate is used to search for a translations file with that name. Different parts of your user interface can use different translation files which makes it easier to manage translations.
We recommend using a different translations name for each 'context' your program has. Example contexts are: 'main', 'preferences', 'plugins', 'searcherplugin' etc.

If you have adjusted the FactGui class with the 2 changes explained above you will not yet see a translated user interface; there are 2 more steps to follow. Read on:
First you have to tell translate which locale to use, this is a combination of language and country strings. (more)
adding this to your main() will set the current locale to be austrian [AT] (where they use the german language [de]).

            Translate.setLocale("de","AT");

Last you will have to place the translations files in your classpath. A translations file is a normal properties file containing simple name=value pairs. Please read the relevant documentation on properties files for correct formatting. ( here)

in file named: fastgui_de_AT.properties

        Single\ line\ of\ text = einzeln text Reihe

You can find the source to the example application sourcecode here, and the example properties file here
When you try to compile them; please make sure the graphics.jar and the fastgui_de_AT.properties file are in your classpath during compile and execute.

Translating and mnemonics.

Any user interface should allow easy keyboard navigation for people that can't use a mouse, or people that simply dislike grabbing the mouse. Swing allows you to use mnemonics; these are single character shortcuts in combination with the [ALT] key that activate the widget that defined them.
Most user interfaces already have them; they are visible by a small underline under the relevant character. If you look at the prefs example at the top of this page the english version has an underline under the 'A' on the 'Apply' button.

Translating a user interface means the mnemonic will have to be translated as well, the translated UI at the top of this page does not have an 'A' in the corresponding text for the Dutch button.

To place and translate mnemonics using the Translator is really easy; all you have to do is place an '&' in front of the character you want to appoint the mnemnonic.

To define the Apply button you would create this code:

        JButton applyButton = new JButton();
        applyButton.setText(translate().getButtonText("&Apply"));
        applyButton.setMnemonic(translate().getMnemonic("&Apply"));

To translate this your translations file would contain the following line:

    &Apply = Toe&passen

Where does this fit into UICollection

All Java swing user interfaces created using the UICollection will automatically contain the translate() method and all widgets will use the translation methods to place their content on screen.
In practice this means that the code written above will not have to be written when you use UICollection.

Using UICollection generated UIs Internationalisation will work after you:

  1. write properties files for all the languages you wish to support.
  2. Divide your application in different 'contexts' by overriding the translate() method in your extending class and providing a different argument to the instanciation of the Translate class.
  3. Optionally set the locale on the Translator (via setLocale()) if you wish to override the machine's locale.

We hope you will create lots of easily translated user interfaces.