Tutorials

• Tutorial for Internationalizing a Form

Using properties located in XWiki pages

• Create a page that will host your key/value pairs
• Enter all the key/value pairs in that page (use the wiki editor). For example:
  greeting=hello
  welcome=Welcome
  withparams=I can {0} pass {1} {2} params too using the Java MessageFormat syntax

  NB: the Java MessageFormat syntax is described in the MessageFormat Javadoc. There's in particular an important peculiarity for messages with parameters: single quotes need to be doubled to show up in the translated string, which is not the case for messages that are not parameterized.

• While editing this page in wiki mode, you will be able to translate it in other languages by clicking on languages next to "Translate this page in" in the "Page Translations" sections of the right panel.

  To enable multiple languages you'll need to go to the Administration page and set MultiLingual to true and list the different languages you wish to use in the Languages field.

• Tell XWiki that your page is a Translation page by adding an Object of type TranslationDocumentClass to your page.
• On the page where you want to use use either the {{translation}} macro or the Localization Script Service (check the document for the Localization module). Quick examples:

  From wiki syntax:

  {{translation key="key"/}}

  From Script (Velocity in this example):

  $services.localization.render("key")
  $services.localization.render("key", ["param1", "param2", ...])

  where key is the key for the message to retrieve. Parameters can also be passed as is shown in the second syntax above. Beware the parameters need to be passed as an array, not a plain String even if there's only one parameter: $services.localization.render("key", ["param1"]).

Old way

Prior to XWiki 4.3, the way to register a Document Resource Bundle was by going to the Administration page, selecting the "Localization" section and entering it in the "Internationalization Document Bundles" field. You could specify several pages, separated by commas.

Alternatively you could also specify the list of Internationalization Document Bundles in xwiki.cfg under the key xwiki.documentBundles.

I18n of XWiki Objects

This is currently not implemented (see our logged issue: XWIKI-69). There are 2 workarounds you can use:

• Have several objects, one for each language, with a language field, and then decide which object to use (for example in a Class Sheet, based on the current language):
  $doc.getObject('Your.Class', 'lang', $context.language')
  ## Will select the object whose 'lang' property is set to the current language
• Use Velocity scripting to do an IF in your object. For example, you could have:
  #if ($context.language == "fr")
    French texts
  #else
    Default texts
  #end

I18n of XWiki Macros

To internationalize macros, the keys below can be added to the Translation document as presented above.
A concrete example is presented in the Macro Tutorial.

Using the static Resource Bundles

• Stop your XWiki instance
• Extract the ApplicationResources*.properties file for your language from the WEB-INF/lib/xwiki-*oldcore-*.jar file and put them in your WEB-INF/classes directory
• Edit this file and add/modify the key/value pairs you need for your application
• In your document, use the following to get the value associated with a key: $services.localization.render("key")

This will get the value from the Resource Bundle corresponding to the current language you are using in XWiki.

If you're writing an extension JAR and wish to have static translation resources, you can put them in a ApplicationResources*.properties file at the root of your extension JAR and they'll get picked up by the Localization module. See the Localization module for more details.