Localizing your projects

Use cases

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

For any project targeting users with different languages, you may want to localized the specific interface. You may use the localization framework in the following areas:


Use the the localization API to dynamically localize any text phares in your app


Similar to controllers, some views will integrate the framework-based localization directly, consult your specific view documentation for more details.


Labels and texts in content types, input types and schemas in general can also be localized.

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

When localizing, a best match pattern will be applied to select the optimal version. If the locale for a request is resolved to "en-US", XP will look for the localization key in the following order:

  • phrases_en_US.properties

  • phrases_en.properties

  • phrases.properties

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.

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.