Localization Module

Version 41.1 by Oana Florea on 2019/12/03 15:44

cogAllows translating Strings into different languages
TypeJAR
Category
Developed by

XWiki Development Team

Rating
0 Votes
LicenseGNU Lesser General Public License 2.1
Bundled With

XWiki Enterprise, XWiki Enterprise Manager

Compatibility

Since 4.3M2

Description

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.

Features

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

Usage

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

See Localization Scripting.

From Java

Two main entry points (components) are available on Java side to manipulate translations:

import org.xwiki.localization.ContextualLocalizationManager;
import org.xwiki.localization.LocalizationManager;

@Component
public class MyComponent
{
 // For most use cases (simpler API, use the locale from the context, plain text output helper, etc.)
 @Inject
 private ContextualLocalizationManager contextLocalization;

 // Or if you need more control
 @Inject
 private LocalizationManager localization;

...
}

See Component Module if you need more details on how to lookup a component.

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 visible in the whole farm (requires Programming rights)
    • WIKI: translation visible only for the current wiki, i.e the wiki where the page saved is in (requires Admin rights)
    • USER: translation visible only for the current user (page author since it's the current user who saves the page)
    • ON DEMAND: translation is not automatically visible, it needs to be registered through scripting

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

Tip: the single quotes inside values need to be doubled. Example:
my.translation.key=des droits d''auteur

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

Tags: translation
    

Get Connected