Localization Scripting

Last modified by Marius Dumitru Florea on 2022/02/23 06:28

cogProvide script oriented APIs to manipulate translations
Developed by

XWiki Development Team

0 Votes
LicenseGNU Lesser General Public License 2.1

Table of contents


The identifier of the Localization Script Service is localization.

A translation corresponding to a key can be obtained by calling:


The printable translation of a defined property is obtained by calling:


As with the old MessageTool, parametrized translations can be obtained with:

$services.localization.render('some.key', ['param1', 10])

where parameters is a list of parameter values. The format of the translation is the one accepted by the MessageFormat class.

It's also possible to choose the syntax in which the translation message is going to be rendered using:

$services.localization.render('some.key', 'xhtml/1.0', ['param1', 10])

XWiki 5.1+

$services.localization.render('some.key', 'xhtml/1.0')

the default being plain/1.0.

XWiki 9.0+

You can also pass the Locale to search for (instead of using the current Locale):

$services.localization.render('some.key', 'fr_FR')

Note that it will search for a key in the parent locale also (e.g. 'fr') if it cannot find the key in the given locale (e.g. 'fr_FR').

XWiki 10.2+

It's possible to pass a list of keys to test one by one until one is found.

$services.localization.render([$someInputKey, "some.${specific}.key", 'some.generic.key'])

It's possible to add on demand translation bundles for the current execution by indicating their type and identifier like in:

$services.localization.use('document', 'wiki:Space.PageWithTranslations')

XWiki 5.0M1+

You can retrieve the current Locale:


XWiki 14.1+

and the configured default Locale:


Get Connected