I18N API
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 "com.enonic.xp:lib-i18n:${xpVersion}"
}Add the import statement to your controller:
import i18nLib from '/lib/xp/i18n';Then you need to create files with original phrases and their translations. These files should be placed in the src/main/resources/site/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:
action.preview=Preview
notify.process.failed=Processing failed: {0}.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 for default locale. |
|
bundles |
string[] |
Required list of bundle names. Bundle names are specified as paths, relative to the |
Returns
An object with all phrases
Example
const phrasesEs = i18nLib.getPhrases('es', ['site/i18n/phrases']){
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[] |
Required list of bundle names. Bundle names are specified as paths, relative to the |
Returns
An array with all locales
Example
const locales = i18nLib.getSupportedLocales(['i18n/phrases'])["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.
Parameters
| Name | Kind | Details |
|---|---|---|
|
key |
string |
The phrase key |
|
locale |
string | string[] |
A string-representation of a locale, or an array of locales in preferred order. If the locale is not set, the site language is used. |
|
values |
string[] |
Optional placeholder values |
|
bundles |
string[] |
Optional list of bundle names |
|
application |
string |
Application key where to find resource bundles. Defaults to current application |
Returns
The localized string
Example
import {localize} from '/lib/xp/i18n';
const message2 = localize({
key: 'notify.process.failed',
locale: 'es',
values: ["StaleConnectionException"]
});Error al procesar: "StaleConnectionException".