Docs Developer Site
Developer Docs Code Xp8 Fundamentals I18n

Localization

Contents

Localizing strings in your XP applications.

Use cases

This section covers code-level localization, not multi-lingual content or websites.

For any project targeting users in different languages, you may want to localize the interface.

The XP framework provides localization for the following use cases:

CMS/Sites

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

Admin Console

Localize labels and texts in schemas such as content types. The framework will use the locale derived from the browser’s Accept-Language header.

Webapps and more

The localization API may also be used for any other purpose. In these cases the developer controls and specifies the locale 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 an app that supports the following localizations:

  • English (en)

  • English (US) (en-US)

  • Norwegian Nynorsk (nn)

  • Norwegian Nynorsk, Norway (nn-NO)

Each locale needs 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.properties
i18n/phrases_en_US.properties
i18n/phrases_nn.properties
i18n/phrases_nn_NO.properties

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

The filenames are case sensitive!

Locale format

A locale is composed of 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 an underscore (_).

The string representation of a locale is:

la[_CO][_VA]

where

  • la — two-letter language code (ISO-639).

  • CO — optional two-letter country code (ISO-3166).

  • VA — optional variant. May contain multiple subtags joined by _.

A sample locale including a vendor-specific variant:

es_ES_Traditional_WIN
Variants are rarely used in XP and can usually be ignored.

Best match resolving

Given a requested locale, the framework selects the best matching localization file. If the requested locale is en-US, the framework checks files in this order:

  • phrases_en_US.properties

  • phrases_en.properties

  • phrases.properties

If a request’s locale is en, the framework uses phrases_en.properties. If the locale does not match any file, phrases.properties is used as the fallback. If no matching key is found in any file in the bundle, the default NOT_TRANSLATED is returned.

Encoding and special characters

Property keys

Must be in the ISO-8859-1 range (Latin-1). Non-Latin-1 characters must use Unicode escape sequences, e.g. \u00E6 for the Norwegian letter æ.

Property values

Support any Unicode characters.

We always recommend saving property files using the UTF-8 charset.

Sample

A property file looks like this:

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 supports parameter values that are merged into the localized strings:

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 number corresponds to the position of the value in the values argument passed to the API.

See MessageFormat for advanced placeholder syntax.

Placeholders are formatted according to the requested locale.

Contents

Contents