Freitag, 7. Februar 2014

To offer a wherigo in several languages

This is the english version of the article. It is also available in german

Good to know for this article: "Der Einstieg in lua“

In this tutorial you'll learn how to offer your wherigo cartridge in several languages.

Picture 1: Definition of the text outputs in three different languages
First we will define an array messages where we can define the outputs in different languages
Very important is to define the language parameter to to ZVariables because we want to save the value when we save and restore the cartrigde.
For each language (german, english and fresh in our example) we define a subarry like in row 5-7. After that we define the output strings.
How it works I can show you at the example for the key hello. Depending on the selected language we want to see "Herzlich Willkommen", "Welcome" oder "Bienvenue" in our display. Maybe you have noticed that for the key hi are no english value defined. For this case the program will use the defaultLanguage (see row 4) So if your language is set to en and no value for message.en.hi is defined the default value => "Hi" (row 11) is used.
The next part is very important:
In row 13-18 you can see examples for using placeholders, e.g the name of the play inside the translated output string
At runtime the #1# will be replace with the name, e.g. 'Krolock'. You will have one of the following output:
  • de => Hallo Krolock, wie geht es dir?
  • en => Hi Krolock, how are you
  • fr => Salue Krolock, ca va?
Be careful with blanks! # 1# will not work, #1 # will not work and Hi#1#How are you will transformed to "HiKrolockHow are you".

During the start of your cartrigde you can offer an multiple-choice-input for the user where he can select the langauge. After the input you can set the variable language to the fitting value

Picture 2: Build the value fitting to the key and language
But how to use the resource strings. As shown in picture 2, row 21 we use an array access for the language in first and the key in second level. Using "de" as language and "hello" as key will deliver Herzlich Willkommen zum i18n Wherigo.
If no array value is available a new try with the default value is shown in row 23. So it is very import to define an entry for each key in the default value (de in our example)

Picture 3: Values for the placeholders
Now it is time to look to the parameter replacement. I is import to use a placeholder that will not be part of the "regular" strings. So I decided to use #1#.
As you can see in line 27 at picture 3 i use string.gsub to replace #1# with the first, #2# with the second parameter and so on. Picture 3 shows a updated version of getMessage with replacing the placeholders
The vararg argument "..." is a good way to be flexible.
The function getMessage can be called with only the key, with one or multiple parameters like the following examples show :

With #arg we can retrieve the number of the arguments stored in the array arg. With arg[1], arg[2] we can access to the first, the second parameter and so on

Picture 4: Example for calling the translation method
If you have more than one parameter you have to take care for the order. For the key openDoor you have different orders in the german and english version.
Picture 4 shows us an example how to call the translation method in Urwigo. He have an example for no, one and two parameters.

Last but not least I will show you how to seperate your code and your translations. In the concept of resource bundles you will define a own file for each language and each file hast the same key, excect the language part of the key.
You can use a file messages_de.lua containing the german, messages_en.lua for the english and messages_fr.lua for the french values.
All the three files can be bind with require "messages_de" and so on.
Development-Tool line eclipse or Intellij IDEA have plugins to manage your resource bundles.

To seperate the file is optional. It will also work if you write all the key-value entries in one file, but it is not a good practise.