Localization
Contents
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:
- CMS/Sites
-
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:
phrases[_LOCALE].properties
The API’s country codes use - as separator but the files use _. |
i18n/phrases.properties
i18n/phrases_en_US.properties
i18n/phrases_no.propertiesThis 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
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 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. |
Sample
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 å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:
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 documentation for MessageFormat for advanced use of placeholders.
| Placeholders get formatted according to requested locale |
