How to add custom translations to your wiki content

Written by

Andreea Chirica

, Communications and Support Specialist

When it comes to using XWiki in an international context, it's good to know that XWiki can be set to support one or multiple languages. Currently, the XWiki product has translations in 40 languages. If you first need to learn about changing the default language on your wiki or making your wiki multilingual, check out this article.

There are various situations when you could need to add custom translations to your wiki. See below more details on each case and our proposed solutions.

1. When a menu field is incorrectly displayed
2. When you want to translate a custom panel on your multilingual wiki
   1. The steps to follow
   2. Check out this video guide showing how I translated the Getting Started panel
3. Bonus option: Language switcher on the footer of your website based on XWiki

When a menu field is incorrectly displayed

In the case when on a wiki which currently has set the French (fr) language, we can notice in the screenshot below that the menu field Pages "sœurs" is rendered as Pages "sœurs".

This can easily be corrected on your wiki with a quick fix: 

1. Create a new page on your wiki. The name and location are not important, but it should at least be suggestive that it is a translation. (e.g. XWiki.TranslateSiblings — a new page called TranslateSiblings in the XWiki space).

2. Edit this new page in object mode, and add the TranslationDocumentClass object (for the Scope field, you should select WIKI, or GLOBAL if you want it to be visible from other wikis as well). Save the new page object.

3. Now edit the same page in Wiki mode, and as content, you need to add the desired translations in French, in a key=value format. In this case :

4. Finally, save this page and check the result:

When you want to translate a custom panel on your multilingual wiki

In the case when you would have a multilingual wiki with English (en), French (fr), German (de), and Spanish (es) as supported languages, and you have a custom panel that is currently displayed in only one language, you can use these steps to translate the panel in the remaining languages. Let's say that your wiki is currently set in English. Your custom panel is called Getting Started and it is displayed on the left side of your wiki:

The steps to follow

Below, you can find the steps for adding a translation to a custom panel in XWiki:

1. Create a new document that will become the translations page. For this example, I chose to create a page called GS-Custom-Translation in the space Panels.
2. Edit the page in object mode and add the object TranslationDocumentClass (for the scope, you should select WIKI, or GLOBAL if you will use the panel on other multilingual subwikis). Save the page.
3. Then, edit the same page in wiki mode. You can see for what language you are currently adding a translation on the right panel, where you would see the Page Translations panel and a message like "You are editing the original page (en)" if the page was created while the wiki was set in English.
4. While editing the page in wiki mode, this will be where you add translation keys representing the content of the panel that you want to translate. You can compose suggestive key names, but the format would need to be key=value (in my example, for the panel title I added panels.gettingstarted.title=Getting Started). Continue with a key for each content section you want to translate.
5. After you have added and saved the English translations, check the Page Translations panel on the right and click on the language locale from the Translate this document in: fr (the keys part have to remain consistent between the languages).
6. When you finish and save the new translation, click on the remaining versions, de, and es and modify the translation values accordingly.
7. Now that you added the translations, go to the Getting Started panel and edit the page and replace whichever text you have created a translation for with the following: $services.localization.render('insert here the key from the translation document'). Example: for the title of the panel, you will need to modify the line #panelheader('Getting Started') with #panelheader($services.localization.render('panels.gettingstarted.title')) 

If you choose to add or modify content on the Getting Started panel, you can go back to those resulting GS-Custom-Translation pages and update the translation keys as needed.

Check out this video guide showing how I translated the Getting Started panel

In this video, we'll walk you through how we translated the Getting Started panel in our wiki so that you can do your own translations to your custom panels as well.

Bonus option: Language switcher on the footer of your website based on XWiki

Check out the footer of this page to see the Language switcher which currently includes a switch between the English and the French version of this page. This has been a custom development feature made for xwiki.com and we'd be happy to offer you support for making your wiki multilingual and adapted to your business needs.