Localization Module

The Localization Module is the new replacement for the MessageTool class and allows applications and components to be translated into different languages. The source code is published on GitHub.


  • The Localization component efficiency comes from the usage of cache. 
  • The pluggable Translation Bundle types allow creating new types of translations. The supported bundles are:
    • document translation bundles which are in fact wiki documents that are specified as "Internationalization Document Bundles" in the "Localization" section of the wiki administration. Document Translation Bundles can be dynamically registered using XWiki translation objects. The main advantage is that applications and components can include their own translation documents without the need of additional configuration.
    • file translation bundles i.e. the .properties files packed in the XWiki core jar. E.g. "ApplicationResources.properties", "ApplicationResources_fr.properties". 
  • The Localization module allows using parametrized translations as supported by the Java MessageFormat class.


From Velocity

You can expose the Localization module API in Velocity using a script service: $services.localization.*


  1. Get the corresponding translation of a key

will display

watchlist.notification.email.singleUpdate.intro:This message is sent by XWiki. Here is the document in your watchlist that has been modified since the last notification:

2. Print the corresponding translation of a key


will only display

This message is sent by XWiki. Here is the document in your watchlist that has been modified since the last notification:

3. Write parametrized translations

The syntax is $services.localization.render('Translation_Key', ['Name_Parameter_1', 'Name_Parameter_2', ...])

So, the key

$services.localization.render('watchlist.event.update.multiple', [$firstDate, $xwiki.formatDate($event.getDate()), $event.getVersions().size(), $event.getAuthors().size(), $authors])

will have the corresponding translation:

watchlist.event.update.multiple=Between {0} and {1}, the document has been modified {2} times, by {3} user{3,choice,0#s|1#|2#s}: {4}

4. Choose the syntax in which to render the translation message

$services.localization.render('Translation_Key', 'Supported_Syntax', ['Name_Parameter_1', 'Name_Parameter_2', ...])


$services.localization.render('Translation_Key', 'Supported_Syntax')

The supported syntaxes are: xwiki/2.0, xwiki/2.1, confluence/1.0, jspwiki/1.0, creole/1.0, mediawiki/1.0, twiki/1.0, xhtml/1.0, html/4.01, plain/1.0, docbook/4.4, markdown/1.0, markdown/1.1, apt/1.0 and the default value is plain/1.0.

To learn how to configure the list of supported syntaxes, go to the Content Macro documentation page.

5. Add translation document bundle on demand

$services.localization.use('document', 'xwiki:XWiki.WatchListTranslations')

6. Retrieve the current locale


From Java

The API of the Localization component is available in the LocalizationManager interface. To access it, you can declare a dependency on the Localization tool in your Component:

private LocalizationManager localization;

Another way is to request the Component from the Component Manager as explained in the dedicated Component Module documentation page.

Translation Macro

Another possibility of adding a translation is by using the Translation Macro:

{{translation key="search.panel.header" locale="en_US"/}}

Register a Document Resource Bundle

In order to mark a wiki document as a Document Bundle, you need to attach an "XWiki.TranslationDocumentClass" object:


The "Scope" property has 4 options:

  • GLOBAL: the translation is registered for the whole farm
  • WIKI: the translation is registered only for the document wiki
  • USER: the translation is registered only for the document author
  • ON_DEMAND: the translation can be registered using the code: $services.localization.use('document', 'xwiki:XWiki.WatchListTranslations') 

The content of a document resource bundle should be a list of key=value pairs.

Provide a File Resource Bundle in a JAR

A JAR extension can contain its own translations bundle in the root. The name convention is:

  • ApplicationResources.properties for the default language
  • ApplicationResources_<locale>.properties for the translations

The translations bundle for core extensions will be automatically registered at startup whereas the ones for installed extensions will be registered during the installation.


Related Pages

Trying to decide between Cloud and On Premise? See the comparison on the XWiki Help Center.

Search this space