Docs Developer Site
Developer Docs Code Stable Libraries Lib I18n

I18N library

Contents

This API provides functionality for localization of text phrases.

Usage

This API uses standard framework functionality. Please read the framework localization docs before using this API.

Add the following to your build.gradle file:

dependencies {
  include xplibs.i18n
}

Add the import statement to your code:

import i18nLib from '/lib/xp/i18n';

Then you need to create files with original phrases and their translations. These files should normally be placed in the src/main/resources/i18n folder of your application. There must be a file named phrases.properties that contains all the default phrases. Additional files with translations named phrases_<locale>.properties should contain the same phrases with texts localised to <locale> language. If a phrase is missing from the locale-specific file, the default file will be used. This is what a couple of such files could look like:

phrases.properties
action.preview=Preview
notify.process.failed=Processing failed: {0}.
phrases_es.properties
action.preview=Vista Previa
notify.process.failed=Error al procesar: {0}.

You are now ready to use the API.

Functions

getPhrases

Returns an object of key/value-pairs for all phrases with the given locales in the specified bundles.

Parameters

Name Kind Details

locale

string | string[]

A string-representation of a locale, or an array of locales in preferred order. Pass in an empty array to use the site language.

bundles

string[]

Optional list of bundle names. Bundle names are specified as paths, relative to the src/main/resources/ folder.

Returns

object : An object whose keys are the phrase keys and whose values are the localized strings.

Example

Get all phrases for a locale
const phrasesEs = i18nLib.getPhrases('es', ['i18n/phrases']);
Sample response
{
    "action.preview": "Vista Previa",
    "notify.process.failed": "Error al procesar: {0}."
}

getSupportedLocales

Returns the list of supported locale codes for the specified bundles.

Parameters

Name Kind Details

bundles

string[]

Optional list of bundle names. Bundle names are specified as paths, relative to the src/main/resources folder.

Returns

string[] : Sorted array of supported locale codes (as language tags).

Example

Get the supported locales for a bundle
const locales = i18nLib.getSupportedLocales(['i18n/phrases']);
Sample response
["es"]

localize

Localizes a phrase by searching through the list of passed-in locales in the given order to find a translation for the phrase key. If no translation is found, the default phrase will be used. Some phrases will have placeholders ({0}, {1} etc.) for values that may be inserted into the phrase. These must be provided in the function call for those phrases.

The function takes a single params object with the following properties:

Parameters

Name Kind Details

key

string

The phrase key. Required.

locale

string | string[]

Optional. A string-representation of a locale, or an array of locales in preferred order. If not set, the site language is used.

values

string[]

Optional placeholder values.

bundles

string[]

Optional list of bundle names.

fallbackMessage

string

Optional fallback message returned when the phrase is not found. Defaults to "NOT_TRANSLATED".

Returns

string : The localized string, or the fallback message if the phrase is not found.

Example

Localize a message with a placeholder
import {localize} from '/lib/xp/i18n';

const message = localize({
    key: 'notify.process.failed',
    locale: 'es',
    values: ['StaleConnectionException']
});
Sample response
Error al procesar: StaleConnectionException.
Localize with a custom fallback
import {localize} from '/lib/xp/i18n';

const message = localize({
    key: 'action.preview',
    locale: ['es', 'en'],
    fallbackMessage: '(missing translation)'
});

Contents

Contents