This is an internal documentation. There is a good chance you’re looking for something else. See Disclaimer.

The i18n subsystem

Note

This is mostly a direct copy from an old package-info.java file from the ch.tocco.nice2.textresources.api.i18n package. Feel free to rewrite or expand this documentation.

Contexts

The application always runs in a context. Some examples for contexts:

  • admin: The administration interface.

  • www: The public web site.

  • correspondence: Rendering of bills, letters etc.

In this example, the context admin might only be available in german, because the company is e.g. in Zürich. The web site, however, might additionally be available in french. Letters might be translated into many other languages to ensure communication, e.g. also turkish.

Contexts may be marked with tags to provide some additional information. E.g. www and admin might both be tagged with web: The output is HTML, the protocol HTTP(S). Or correspondence may be rendered as mail or pdf, and pdf is printable.

Locales

Mostly, the handling of Locales is implemented as specified in IETF BCP 47. This also means that you should use Locale#forLanguageTag() to get a Locale object from a string and Locale#toLanguageTag() to convert it back to a String. Java’s own syntax for locales non-standard and therefore deprecated in Nice2.

The algorithm to match the best matching locale for a given requested locale, however, differs from BCP 47 in one important point: While BCP 47 prohibits matching a more specific locale, the algorithm of Locales#lookup does exactly this. In contrast to BCP 47, de-CH is a viable candidate for a requested locale de or even de-DE.

For all locale handling, only the four main elements will be considered: Language, script, region and variant. Any standard or private extensions will be stripped.

The Persistence Layer

There are two ways to access internationalised fields:

  • By specifying the language: myField_de refers to the german version of the field.

  • By the current locale: myField refers to the best matching field

Note: The region will not be considered. myField_de-CH will not match any locale. myField_ru-Cyrl, myField_ru-Latn or even myField_en-scotland will be resolved as usual.

Write access is only allowed to a specific language. In the above example, setValue("myField_de") will set the german value of myField. setValue("myField") will throw an exception.

Internationalised fields can be used transparently in queries and result ordering:

  • find MyEntity where label == "foo"

    Find MyEntity where the label in the best matching language equals “foo”.

  • find MyEntity where label_en == "foo"

    Find MyEntity where the english label equals “foo”.

  • find MyEntity order by label

    Find MyEntity ordering the results by label in the best matching language.

  • find MyEntity order by label_en

    Find MyEntity ordering the results by the english value of label.