Localization

{{{ #!comment 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 =

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("nls") 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.PVErrorFmt, error, pv);

}}}

By default, the {{{PVErrorFmt}}} 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.