Texts

This document is referring to a past Scout release. Please click here for the recent version.

The TEXTS class is a convenience class to access the default Text Provider Service used for the localization of the texts in the user interface.

Listing 1. Text lookup
TEXTS.get("persons");

It’s also possible to use some parameters:

Listing 2. Text lookup
String name = "Bob";
int age = 13;

TEXTS.get("NameWithAge", name, age);

In this case, some placeholders for the parameters are needed in the translated text:

Listing 3. Text lookup
 NameWithAge={0} is {1} years old;

Text properties files

Scout uses the java.util.ResourceBundle mechanism for native language support. So whatever language files you have in your <project-prefix>.shared/resources/texts/*.properties are taken as translation base.

Example setup:

  • <project-prefix>.shared/resources/texts/Texts.properties

  • <project-prefix>.shared/resources/texts/Texts_fr.properties

It is possible to edit these files in the Eclipse Scout SDK or IntelliJ Scout Plugin using the NLS Editor.

Text Provider Service

Text Provider Services are services responsible to provide localization for texts in the user interface. A typical application contains such a service contributed by the Shared Project.

  • implements: ITextProviderService

  • extends: AbstractDynamicNlsTextProviderService (default, translations are stored in properties files)

Using Text Provider Services developers can decide to store the translations in a custom container like a database or XML files. Furthermore, using TextProviderServices it is very easy to overwrite any translated text in the application (also texts used in Scout itself) using the bean order.

Localization using .properties files

By default, the internationalization mechanism relies on .properties files using a reference implementation of the TextProviderServices:

Service extending the AbstractDynamicNlsTextProviderService class.

A Text Provider Service working with the default implementation need to define where the properties files are located. This is realized by overriding the getter getDynamicNlsBaseName(). Here an example:

Listing 4. Text lookup
  @Override
  protected String getDynamicNlsBaseName() {
    return "resources.texts.Texts";
  }

If configured like this, it means that the .properties files will be located in the same module at the location:

  • /resources/texts/Texts.properties (default)

  • /resources/texts/Texts_fr.properties (french)

  • /resources/texts/Texts_de.properties (german)

  • …​ (additional languages)

If you decide to store your translated texts in .properties files, you might want to use the NLS Editor to edit them.

You need to respect the format defined by the Java Properties class. In particular the encoding of a .properties file is ISO-8859-1 (also known as Latin-1). All non-Latin-1 characters must be encoded. Examples:

'à' => "\u00E0"
'ç' => "\u00E7"
'ß' => "\u00DF"

The encoding is the "Unicode escape characters": \uHHHH where HHHH is a hexadecimal id of the character in the Unicode character table. Read more on the .properties File on wikipedia.

File Watcher

The NlsFileWatcher observes changes in text property files. If a change in a text property file occurs, the nls resource bundle cache will be invalidated. This means that there is no need to restart the server when working on texts and translations. The file watcher is only active if scout.devMode=true is set and can be disabled with scout.dev.texts.fileWatcherEnabled=false. By default, the file watcher is enabled in development mode.