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.

Features

  • 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.

Usage

From Velocity

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

Examples

  1. Get the corresponding translation of a key
$services.localization.get('watchlist.notification.email.singleUpdate.intro')

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

$services.localization.render('watchlist.notification.email.singleUpdate.intro')

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', ...])

OR

$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

$services.localization.getCurrentLocale()

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:

@Inject
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:

TranslationDocumentClassObject.png

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

Search this space

 

Most popular tags

Failed to execute the [groovy] macro
  1. access rights
  2. activity stream
  3. annotation
  4. attachment
  5. comment
  6. Document Tree Macro
  7. export
  8. Extension Manager
  9. Flamingo skin
  10. global user
  11. Groovy event listener
  12. group
  13. nested page
  14. search
  15. skin
  16. syntax
  17. user
  18. user profile
  19. velocity macros
  20. wiki
  21. wysiwyg
  22. XWiki Applications
  23. xwikiattachment_archive table
  24. xwikiattachment table
  25. xwikiattrecyclebin table
  26. xwikiproperties table

[Display all tags from this space]