Localisation

Contents

Localisation

Localizing your projects

Use cases

This section applies to code level localization, not multi-lingual content and websites.

Any project targeting users with different languages, you may want to localize the interface.

The XP framework provides localisation a standard approach to localization for the following use-cases:

CMS/Sites

Use the the localization API to dynamically localize any text phares in your app. The framework will attempt to apply the locale specified in the site’s language property.

Admin Console

Localise labels and texts in schemas such as content types. The framework will attempt to use the locale derived from the browser’s "accept-language" settings.

Webapps and more

The the localization API may also be used for any other purpose. In tese cases, the developer must control and specify which locale to explicitly.

Localization files

The localization files are plain text files, using the properties format (key = value). The files must be placed in a specific project folder: /src/main/resources/i18n/.

Imagine, making an app that should support the following localizations.

  • 'English' (en)

  • 'English US' (en-US)

  • 'New Norwegian' (nn)

  • 'New Norwegian Norway' (nn-NO)

Each locale then needs to have a matching localization file, in the format:

phrases[_LOCALE].properties
The API’s country codes use - as separator but the files use _.
Sample localization bundle
i18n/phrases.properties
i18n/phrases_en_US.properties
i18n/phrases_no.properties

This format and packaging is commonly known as "property bundles".

The filenames are case sensitive!

Locale format

A locale is composed of two-letter codes for language, country and variant. Language is required, country and variant are optional.

For the property files, all codes are case sensitive and separated by and underscore (_).

The string-representation of a locale is

la[_CO][_VA]

where

  • la= two letter language code as specified by ISO-639

  • CO = optional two letter country code as specified by ISO-3166

  • VA = two letter rarely used variant-code.

A sample locale including vendor specific variant:

es_ES_Traditional_WIN"..
Variants are rarely used in XP, and can pretty much be discarded.

Best match resolving

Based on the requested locale to be used, the framework applies a best match pattern to find the optimal localisation file.

If the requested locale is "en-US", the XP framework will look for localization files in the following order:

  • phrases_en_US.properties

  • phrases_en.properties

  • phrases.properties

As such, if the locale for a request was en, the phrases_en.properties file would be used.

If the locale does not match a any specific file, the default phrases.properties will be used as fallback.

If no matching localization key is found in any of the files in a bundle, a default NOT_TRANSLATED will be displayed.

Encoding and special characters

Property keys

Must be in the ISO-8859-1 range, also known as Latin-1 characters. Non-Latin-1 characters use Unicode escape characters, e.g \u00E6 for the Norwegian letter 'æ'.

Property values

Supports any unicode characters

We always recommend saving property files using the UTF charset.

Sample

Below is an example of what a property file might look like

phrases.properties
user.greeting = Hello there!
message = Good to see you. How are you doing?
with_\u00e6_\u00f8_\u00e5 = This key contains norwegian characters æ, ø and å

Placeholders

The properties format also supports parameter values that can be merged into the localized strings. Below is an example of what this might look like:

phrases.properties
user.greeting = Hello, {0}!
message_url = http://localhost:8080/{0}
message_multi_placeholder = My name is {0} and I live in {1}
message_placeholder = Hello, my name is {0}.

Placeholders are marked with {<number>}. The given number corresponds with the function argument named values and the position of the parameter.

Contents