Localization Module
 | Allows translating Strings into different languages |
| Type | JAR |
| Category | |
| Developed by | Unknown |
| Rating | |
| License | GNU Lesser General Public License 2.1 |
| Bundled With | XWiki Standard |
| Compatibility | Since 4.3M2 |
Table of contents
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:
See the Translation Macro documentation for more details.
From Velocity
From Java
Two main entry points (components) are available on Java side to manipulate translations:
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.
From JavaScript
define('my-translation-keys', {
prefix: 'livedata.',
keys: [
"dropdownMenu.title",
"selection.infoBar.allSelectedBut",
//...
]
});
// Then you require the translation messages using the dedicated loader.
require(['xwiki-l10n!my-translation-keys'], function(l10n) {
// Translation key without parameters.
console.log(l10n['dropdownMenu.title']);
// Translation key with parameters.
console.log(l10n.get('selection.infoBar.allSelectedBut', 'parameter value'));
});
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, XWiki 14.10.2+, 15.0+ requires Script right unless the localization.wiki.restrictUserTranslations configuration option is disabled)
- 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.other.translation.key=Some other translation message
See the localization guide for best practices about naming translation keys and how to best use the translation mechanism.
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).
Translation bundles priorities
Each bundle type has a priority number as described in the table below. A bundle with lower priority number takes precendence on the ones with higher priority numbers.
| Bundle type | Description | Priority number |
|---|---|---|
| XWikiPreferences bundle | Bundle declared as a translation bundle in XWikiPreferences object in page XWiki.XWikiPreferences | 300 |
| Document translation bundle | Bundle declared in a wiki page with object XWiki.TranslationDocumentClass | 900 |
| Jar/root bundle | Bundle defined in a JAR | 1000 |
REST API
XWiki 13.3+
The raw source of XWiki translations can be accessed using the REST API.
/wikis/{wikiName}/localization/translations[?locale=l&prefix=p[&key=k]*]
- HTTP Method: GET
- Media Types: application/xml or application/json
- Description: The list of translations of the requested keys in a given locale
- Query Parameters:
- locale: (optional) the locale of the returned translation, if missing the locale is resolved from the context
- prefix: (optional) a common prefix concatenated to all the provided keys.
- key: (multiple) a list of translation keys
- Status Code:
- 200: if the request was successful
- Response:
- a list of translation objects, each containing the translation key (concatenated with the prefix) and the resolved raw sources (the translation values without the parameters resolved).
Examples:
curl -H 'Accept: application/json' http://localhost:8080/xwiki/rest/wikis/xwiki/localization/translations?key=administration.section.users.deleteUser.newAuthor.error
# {"translations":[{"key":"administration.section.users.deleteUser.newAuthor.error","rawSource":"The selected user doesn''t have {0} rights!"}]}
# Request of two translation keys with the fr locale, and a common prefix
$ curl -H 'Accept: application/json' http://localhost:8080/xwiki/rest/wikis/xwiki/localization/translations\
?prefix=administration.section.users&locale=fr&key=.deleteUser.newAuthor.error&key=.enableUser.inProgress
# {"translations":[{"key":"administration.section.users.deleteUser.newAuthor.error","rawSource":"L''utilisateur sélectionné n''a pas les droits {0} !"},{"key":"administration.section.users.enableUser.inProgress","rawSource":"Activation du compte utilisateur…"}]}
# Same request as above but with the default xml media type
$ curl http://localhost:8080/xwiki/rest/wikis/xwiki/localization/translations\
?prefix=administration.section.users&locale=fr&key=.deleteUser.newAuthor.error&key=.enableUser.inProgress
# <translations xmlns="http://www.xwiki.org/localization"><translation><key>administration.section.users.deleteUser.newAuthor.error</key><rawSource>L''utilisateur sélectionné n''a pas les droits {0} !</rawSource></translation><translation><key>administration.section.users.enableUser.inProgress</key><rawSource>Activation du compte utilisateur…</rawSource></translation></translations>
Configuration
XWiki 14.10.2+, 15.0+ The localization.wiki.restrictUserTranslations configuration option in xwiki.properties determines if translations for the user scope (see above) shall be restricted to users with script right. It is enabled (true) by default. It is strongly recommended to keep this option enabled unless you absolutely need this feature for users without script right and you absolutely trust these users.
