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 localization for the following use-cases:


Use the the localization API to dynamically localize any text phrases 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 these cases, the developer must control and explicitly specify locale.

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:

The API’s country codes use - as separator but the files use _.
Sample localization bundle

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= 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:

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 the best matching pattern to find the optimal localization 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 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.


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

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


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:

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.

See Java documentation for MessageFormat for advanced use of placeholders. The only difference with Java MessageFormat implementation is that DateFormat timezone is UTC.

XP XP 7.8.0 7.8.0 Placeholders get formatted according to requested locale