XWiki Enterprise 8.4.4 Documentation » Customization Overview » Customize the Language and Timezone Settings

Customize the Language and Timezone Settings

Set Up the Supported Languages

To set up the supported languages, log in as administrator, click the DrawerMenuIcon.png button to open the drawer menu, then click on "Administer Wiki".

AdministerWikiMenu.png

In the wiki administration page, click on the "Localization" link from the menu to the left.

AdministrationLocalization.png

At this point you have 3 possibilities:

  • keep the default settings by leaving "Multilingual" to "---" which means that the default language of the wiki will be English ("en").
  • set "Multilingual" to "No" and enter the default language you wish to have on your wiki. XWiki currently supports 37 languages as explained in the documentation page about "Internationalization".
  • set "Multilingual" to "Yes", enter the supported languages separated by comas ("en,fr,de,es"), then define the default language for the wiki.

The language text inputs have been replaced with filter drop-down boxes for easy use.

LanguageAdministration.pngDefaultLanguageAdministration.png

Define a Document Bundle

To enable multiple languages, go to the wiki administration page, set "Multilingual" to "Yes" and list the different languages you wish to use in the "Supported Languages" field as explained in the above section.

To tell XWiki that your page is a document bundle, go to the wiki administration page, click on the "Localization" link in the vertical menu to the left and enter it in the "Internationalization Document Bundles" input from the "Translations" section. You may specify several pages, separated by commas.

DocumentBundle.png

When creating "Internationalization Document Bundles", you should avoid naming the pages with names that include spaces. For example, a document name of Main.My Messages could cause issues, instead, use Main.MyMessages.

Another way to register a document resource bundle is 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 below:

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

The content of a document resource bundle should be a list of key=value pairs as explained in the next section.

You can also provide a file resource bundle in a JAR extension which can contain its own translations bundle in the root. The name convention should be:

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

For more details, check the documentation page about the "Localization Module". 

Write Parametrized Translation Keys

First you have to create a page that will host your key/value pairs. Next, add all the key/value pairs to that page using the "Wiki" editor. For example:

greeting=hello
welcome=Welcome
withparams=I can {0} pass {1} {2} params too using the Java MessageFormat syntax

Finally, on the page where you want to use the internationalized message, use:

$msg.get("key")
$msg.get("key", ["param0", "param1", "param2"])

where key is the key for the message to retrieve.

Translation Keys for Class Fields

Supposing you have a class containing two String properties and one Static List property with two values, the first step would be to create the document bundle that will store your keys. Next, edit it in "Wiki" mode and enter the keys using the syntax

classFullname_propertyName=Translation Message 

for the String fields and the syntax

classFullname_propertyName_propertyValue=Translation Message

for each value of the Static List property.

To exemplify, suppose you have a class named "EmployeesClass" created in the "Employees" space. This class contains two String properties, "first_name" and "last_name" and one Static List field, "availability", with two possible values: "active" and "inactive". Your translation keys will have the following syntax:

Employees.EmployeesClass_first_name=First Name
Employees.EmployeesClass_last_name=Last Name
Employees.EmployeesClass_availability=Availability
Employees.EmployeesClass_availability_inactive=Inactive
Employees.EmployeesClass_availability_active=Active

On the page where you want to use the internationalized message, for instance the sheet of the class "EmployeesClass", you will use a script service:

$services.localization.render("Employees.EmployeesClass_0_first_name")
$services.localization.render("Employees.EmployeesClass_0_last_name")
$services.localization.render("Employees.EmployeesClass_availability")
$services.localization.render("Employees.EmployeesClass_availability_inactive")
$services.localization.render("Employees.EmployeesClass_availability_active")

or the "Translation" macro:

{{translation key="Employees.EmployeesClass_0_first_name" locale="en_US"/}}

Global Timezone Settings

XWiki Enterprise comes with the "Localization" section in the wiki administration page allowing administrators to globally set the timezone without the need to directly access the server. So, in order to use a specific timezone for the whole wiki, just select it from the "Timezone" filter drop-down list in the "Date/Time" section. 

GlobalTimezoneSettings.png

        

Search this space