Extensions Wiki » Extensions » Localization Module

Localization Module

Last modified by Andreea Popescu on 2014/08/18 10:23
cogAllows translating Strings into different languages
Developed by

XWiki Development Team

LicenseGNU Lesser General Public License 2.1
Bundled With

XWiki Enterprise, XWiki Enterprise Manager


Since 4.3M2


The Localization Component is an efficient and flexible replacement of the old MessageTool class, which eases the deployment of XWiki applications.

Localization here refers to translation; see the Wikipedia article about internationalization and localization for more details. In summary, this Component allows applications and components (or any Java code in general) to be translated into different languages.


  • Efficient implementation by making intensive use of caching.
  • Pluggable Translation Bundle types, allowing developers to create and use new types of translations. At the moment Bundles defined in wiki documents (a.k.a. Document Translation Bundles) and in .properties files (File Translation Bundles) are supported.
  • Document Translation Bundles can be dynamically registered using Translation XObjects. This allows applications and Components to include their own translation documents without requiring additional configuration, and without bloating the main File Translation Bundle (found in  ApplicationResources.properties).
  • Powerful parameterized translations, as supported by the Java MessageFormat class.


Translation macro

You can insert a translation in a content using the translation macro as follow:

{{translation key="some.translation"/}}

See the Translation Macro documentation for more details.

From Velocity

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])

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

the default being plain/1.0.

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')

[since 5.0M1] Getting the current Locale:


From Java

As with any other Component, you can either declare a dependency on the Localization tool in your Component, or you can request the Component from the Component Manager. The dependency should usually look like:

private LocalizationManager localization;

The API is located in org.xwiki.localization.LocalizationManager in the xwiki-platform-core/xwiki-platform-localization/xwiki-platform-localization-api module. The role (which is used for requesting the Localization Component from the Component Manager) is the name of this interface, org.xwiki.localization.LocalizationManager.

Register a wiki translation

It's possible to mark a document as a Document Resource Bundle by adding a XWiki.TranslationDocumentClass XObject to this document.

  • Scope:
    • GLOBAL: translation registered for the whole farm
    • WIKI: translation registered only for the document wiki
    • USER:  translation registered only for the document author

The content of this document is a list of key=value pairs, as in:

my.translation.key=Some translation message
my.other.translation.key=Some other translation message

Provide translation bundle in a jar

A jar (installed extension or core extension) can come with its own translations bundle. For that all is needed is to name it ApplicationResources.properties for the default language and ApplicationResources_<locale>.properties (for example ApplicationResources_pt_BR.properties) for its translations and put them in the default package (i.e. root of your JAR). It will be automaticlally registered at startup for core extensions and when installed for installed extension (it will also be unregistered automatically if the jar extension is uninstalled).


This extension has been tested with the following configurations.

Extension VersionXWiki FlavorNotes
XWiki Enterprise 4.3M2

Since XE 4.3.M2

Tags: translation
Created by Sergiu Dumitriu on 2008/10/14 20:54

Download XWiki

Get Connected