Localization

Note:
This wiki source was generated from a [[DocBook]] file.
Instead of modifying the wiki text you might prefer to
edit the original [[DocBook]] file, because otherwise your
wiki text changes could later be overridden when the
wiki text is re-generated from the [[DocBook]] file.

Localization

(XXX macro: "PageOutline")

Since control system tools are used in countries with different languages, it is often a good idea to localize the texts in CSS plugins. This way, they can be not only in English but also German, French, Chinese, Japanese or in other languages.

Externalize Source Code Strings

When developing source code for CSS, it is a good idea to enable compiler warning for non-localized strings, found in the Eclipse preferences under Java, Compiler, Errors/Warnings, Code style as "Non-externalized strings (missing/unused $NON-NLS$ tag)" .

With this warning enabled, it is easy to spot non-localized texts in Java source code. For example, the texts in the following will be marked as non-localized:

final String ID = "org.csstudio.someplug.someid";
label.setText("Hello");

To remove the warnings, there are fundamentally three options:

• Some strings like plugin IDs, host names, certain file names are not meant to be localized. The software depends on the fixed value of these strings. You can mark them with a NON-NLS comment like this to indicate that the text cannot be localized: final String ID = "org.csstudio.someplug.someid"; //$NON-NLS-1$ The Eclipse Quick Fix in the context menu of the warning can add appropriate NON-NLS comments.
• Sometimes a whole method or class cannot be localized because all the texts in the are internal to the application and not meant to display in a user interface. In that case, adding @[SuppressWarnings] to the method or class will suppress all localization warnings.
• Finally, if the text should indeed be localized, it is best to use the tool invoked from the menu Source, Externalize Strings... to extract the texts into a separate Messages class. Your code will then look like this: label.setText(Messages.Hello); The generated Messages class will load the text from a properties file.

Message Properties Files

The Externalize Strings... tool will create a file messages.properties that includes the extracted test, for example:

# File messages.properties
Hello=Hello

This file will be used as a default. You create translations by adding additional property files:

# File messages_de.properties
Hello=Hallo





# File messages_fr.properties
Hello=Bonjour

Test Localization in IDE

To run CSS with a different localization, you typically need to install it on a computer with an operating system that uses that localization. For example, on a computer with the German version of Windows, CSS will use the de localization files.

It is also possible to pass a command-line argument to the Eclipse launcher to force a specific localization. Products launched within the IDE will typically include this as a default program argument:

-nl ${target.nl}

By changing the run configuration to use

-nl de_DE

you can run the product with German localization.

Language Codes

The locale identifier consists of a language and country. For the messages.properties file names, it is often sufficient to only use the language code as in messages_fr.properties for French, but in principle you could also create files messages_fr_FR.properties and messages_fr_CA.properties with different localizations for France and Canada.

Other example language and country codes:

• en_US: English, USA
• en_CA: English, Canada
• de_DE: German, Germany
• zh_CN: Simplified Chinese, China
• ja_JP: Japanese, Japan

Externalize Texts in plugin.xml

To localize for example the labels of menu items or the title of a view, you need to localize the corresponding text in the plugin.xml:

1. Create a file plugin.properties with content like this: TryThis=Try this!
2. Add this option to the MANIFEST.MF which instructs Eclipse to use the properties file: Bundle-Localization: plugin
3. Replace fixed texts in the plugin markup with references to the texts defined in the properties file using a percent sign: <page name="%TryThis"> ...
4. Create translated files like plugin_de.properties

Language Caveats

It is often not sufficient to simply translate words, because the structure of sentences can be very different in another language. For example, when a message needs to be constructed based on PV names and an error, it is suggested to use the NLS formatting utility for this:

final String pv = .. some PV name;
final String error = .. some error info;
final String message =
  NLS.bind("There was an error {0} with PV {1}",
           error, pv);

This way, the message format can be externalized:

NLS.bind(Messages.PV[[ErrorFmt]], error, pv);

By default, the PV[[ErrorFmt]] would be

"There was an error {0} with PV {1}" , but it can be translated into another language with a different sentence structure, for instance

"The PV {1} produced an error. Original error description: {0}" .

Externalize Texts in Online Help

To localize online help, the default online help subdirectory needs to be replicated into subfolders nl/de, nl/zh and so on for the various languages. Refer to eclipse online help for details.