Tutorial for Internationalizing a Form

Last modified by Vincent Massol on 2017/09/05

There are multiple ways you can integrate translation in XWiki. If you are a web developer which builds custom applications on top of XWiki, you certainly tried to create pages that contain multiple translations.

In order to facilitate these tasks, here is a tutorial which uses the best practices for achieving the following goals:

  • The first section shows how to create properly a small inline form. 
  • The second section shows you how to add translations in Romanian language to that form in the proper and recommended way. If you are interested only on the translations tutorial, you can skip the first section.

Step 1: Creating the XWiki Class

  • Create a page called MyCoolClass. This will hold the definition of the class.
  • Add the following fields:
  • name of Type String
  • Fill the Pretty Name field with "Your Name"
    addNameProprety.png
  • street of Type String
  • Fill the Pretty Name field with "Your Street Name"
    addStreetProprety.png
  • favColor of Type Static List
  • Fill the Pretty Name with Favourite Color
  • Fill the Values field with "red|blue|green|yellow"
    addFavColorProprety.png
  • edit the document in wiki mode and add the following line:
    {{include document="XWiki.ClassSheet"/}}
  • Click on the "Save & View" button

Step 2: Creating the XWiki Sheet

  • Create a page called MyCoolSheet
  • Edit the page in wiki mode and add the following
    {{velocity}}
    {{html}}
    <dl><dt><label>$doc.displayPrettyName('name', false, false)</label></dt>
    <dd>$doc.display('name')</dd>
    </dl>


    <dl><dt><label>$doc.displayPrettyName('street', false, false)</label></dt>
    <dd>$doc.display('street')</dd>
    </dl>

    <dl><dt><label>$doc.displayPrettyName('favColor', false, false)</label></dt>
    <dd>$doc.display('favColor')</dd>
    </dl>
    {{/html}}
    {{/velocity}}
  • Add a new class of type  XWiki.SheetClass and set its only property to "inline".
  • Click on the "Save & View" button

Step 3: Creating the XWiki Template

  • Create a page called MyCoolTemplate
  • Edit the page in wiki mode and add the following line:
    {{include document="MyCoolSheet"/}}
  • Click on the "Save & View" button

Step 4: Internationalizing the display

Before being able to add translations, XWiki must be set to support multiple languages:

  • Go to the administration section of the wiki
    • Click on "Localization"
    • Set Multilingual to yes
    • in the "Supported Languages" field add the languages you want your wiki to support in this format: "fr, en, ro" (without the quotes)
    • Click the "Save" button
  • Create a page called MyCoolTranslations; this page will hold the translations to other languages other than the default one.
  • Open the page in Wiki mode, and on the Document Translations panel from the right side of the page, click the "ro" button; now we will add the translation for the Romanian language.
    MyCoolTranslationsAddTranslations.png
  • Insert this text into the content:
    Main.MyCoolClass_name=Numele Tau
    Main.MyCoolClass_street=Numele Strazii
    Main.MyCoolClass_favColor=Culoarea Preferata

    Main.MyCoolClass_favColor_red=Rosu
    Main.MyCoolClass_favColor_green=Verde
    Main.MyCoolClass_favColor_blue=Albastru
    Main.MyCoolClass_favColor_yellow=Galben
  • The rule for creating translation keys is the following:
    • For class proprieties : spacename.classname + _ + property name
    • For static lists and boolean properties : spacename.classname + _ + property name + _ + property value

      Note that for boolean properties the possible values are 0 (=false), 1 (=true) and 2 (=undecided). E.g. SomeSpace.SomeClass_enabled_0=Disabled

  • Click on the "Save & View" button
  • To test your translation, append ?language=ro to your URL. For a better comparison you can see the English and the Romanian versions below.
  • For example, if your are using your xwiki on localhost use the following URLs:
  • English Version:
    MyCoolTemplateENView.png
  • Romanian Version:
    MyCoolTemplateROView.png
    Only the Translation document needs to have translations. The class, sheet, template and instance pages don't need to be translated; the localized messages will automatically be displayed in the selected language.
Tags:
Created by Vincent Massol on 2017/09/05
   

Get Connected