Internationalisation

Internationalisation of mathlets can be done by using localizable messages (identified by keys) for e.g. the title or descriptions inside the mathlet. The mathlet developer is encouraged to use localisable messages instead of static strings in order to free the code from language dependant expressions and therefore to provide a more flexible language integration.

At start-up, the mathlet tries to load the correct message set for the executing system, else it tries to load it in the default language (English).

About Locales

In order to load the correct message set, the locale of the executing system must correspond to that of the message set. Each language has its own locale, e.g. "en" for English, "de" for German or "fr" for French. This language prefix identifies a set of messages/texts.

The locale of the mathlet runtime can be set via properties/parameters, otherwise the system locale will be used.

Storing messages

There are several possibilities to store messages outside a mathlet, whereas it is
possible to combine them.

Messages Files

Message files confirm to the Java Property Format and store the messages of a single set (i.e. for a single language) in an own file. The syntax is key = message.

The filename of a message-file is determined by the prefix Messages_ followed by the locale and the file ending .properties (e.g. Messages_en.properties for English). This file must reside in the mathlet’s files directory.

A message in the "en" set could be:


myApplet.title = This is the title in english!

whereas in the "de" set:

myApplet.title = Dies ist der Titel auf deutsch!

XML Messages

Since applets may be regarded as extensions too, sets of messages can also be defined via XML in a mathlet’s property file or a LSP sheet. See [[..:extensions:message_properties|language sensitive texts]] in the chapter extensions for more information.

This section also deals with the definition of additional message files.

Parametrised Messages

Sometimes a message does not only contain a static text but may also include variable content. Instead of splitting the text around this content, placeholders can be used inside the text definition. The values they represent are defined in a list which must be specified while retrieving the message. Their name corresponds to the respective position of their value in the list, prefixed with a "%%$%%" character. The numbering starts as usual at "1". It is possible to use the same placeholder multiple times in a message.

If the list does not contain the appropriate number of items, an exception will be thrown.

The following example demonstrates a message with two variables:


my_text_key = The value is $1 but must be $2.

This message must be retrieved with a list of two values. The list could be created as follows:

Object[] list = new Object[] { "my value 1", "my value 2" };

See the next section for more information about retrieving messages.

Retrieving Messages

Messages of the current set can be retrieved through the two getMessage() methods defined in the BaseApplet class. Both methods return null if no such message is found in the current set.

The first method only takes a String argument which represents the key:

public String getMessage(String key)

Note that only non-parametrised messages can be retrieved with it.

The second method has an additional argument for the list of parameters:

public String getMessage(String key, Object[] params)

It allows to retrieve parametrised messages with the given parameters. The parameters are typically simple strings, otherwise their toString() method will be used.

Examples:

setTitle(getMessage("title"));
addText(getMessage("my_text_key", new String[] { "my value 1", "my value 2" }));

Add picture from clipboard (Maximum size: 500 MB)