i18n Library – in the Spotlight

Hello, Hola, Bonjour, Ciao, Γεια, Halò and welcome to another edition of in the Spotlight. We’re looking at the new i18n library from LiveCode. If the intro did not give this away this library is all about internationalization. i18n allows you to easily handle language translations inside your application. Let’s dive in…

First, why i18n? It’s a question I had when I first saw this new library. It turns out, Internationalization just takes too darn long to type, so if you count the number of letters between the first i and the last n in the word you reach 18. There, now it makes sense. Take a look at this short demo video.

I18n is an internationalization library written in and for LiveCode. It consists of a translation system that allows support for multiple languages in our LiveCode applications.

Note: This library is inspired by i18njs.com with some modifications.

We start off with language files. Language files are where your translated text is stored. In this example lets assume my app consists of just two buttons. Button 1 has a label of “Back” and button 2 has a label of “Next Step”. Our English language file would look something like this…

{
  "id": "en",
  "values": {
    "back": "Back",
    "next": "Next Step" 
}
}

We would then need to create a language file for all of the languages we wish to translate our app into. For this example let’s say we wish to translate into Gaelic. Ali Lloyd on our team has been learning this language and it’s probably one you all don’t see very often. Well our Gaelic language file would look something like this

{
  "id": "gd",
  "values": {
    "back": "Air ais",
    "next": "An ath cheum"
}
}

Now that we have our language files and we have our app that consists of two buttons, we now have to initialise the library by telling LiveCode where our language files are located. This is a short snippet of code and in this example we add it to our preopenstack handler. This means that if we ever add any new language files they will be detected each time preopenstack is run.

on preopenstack
     local tPath
     set the itemdel to "/"
     put item 1 to -2 of the filename of this stack into tPath
     i18nInit (tPath & "/languages")
end preopenstack

We now need to tell the library which values in our language file match to our LiveCode objects. This is made easy by the Magic Palette plugin included with the bundle. It is also worth noting here that you only have to do this step for one of the languages. Once these match ups have been made for a single language, any new languages added will take care of it automatically.

Thats it. Our sample app now translates between English and Gaelic.

In the sample app shown in the video we have built in a dropdown language selector and we use this to change the language shown in the app. When you are working in the IDE you can quickly change the active language using the Magic Palette as shown in the screenshot below. However in a real world app you may want to do something more like this…

The language selector used in this example changes the language by using setActiveLocale. This allows the library to switch to the correct language. Here is the snippet of code that runs when you click on Spanish in the dropdown.

on mouseup
     setActiveLocale "es"
     # Updating all UI texts.
     updateLocale the long id of this stack
end mouseup

The i18n library offers many more features not covered in the video. One of these additional features is Pluralisation. Pluralisation is how the library handles some of rules found in languages. The following is an example of how you might use pluralisation in the English language file. In this example we are showing the results of a search. In English you would not expect to see 0 result, you would expect to see 0 results. Similarly you would not expect to see 1 results, you would expect to see 1 result. Finally you would not expect to see 10 result, you would expect to see 10 results. Here is what your language file might look like to achieve this.

{
  "id":"en",
  "values":{
    "%n results":[
      [0, 0, "%n results"],
      [1, 1, "%n result"],
      [2, null, "%n results"]
    ]
  },
  "name":"English"
}

Then we would add this our search script

answer translate("%n results", numberOfResults)

This would result in one of the following

• 0 results
• 1 result
• >1 results

This has been a great library to put in the Spotlight and it’s been a lot of fun using it. To sum up, it’s an incredibly simple to use library, especially when you are using it the way I have used it in the video. You can produce an app for multiple languages with relatively little effort. It has more advanced options such as pluralisation, formatting and context which are there and well documented in a user guide if you need them.

Some things to look out for when using this library – make sure your fields are big enough for the translation that has the most characters in it. Always get quality translations when you can, the library is only as good as the translations we put into it.

If you’ve got any questions or comments about the library let me know in the comments below. The i18n library along with the Magic Palette are included free with the Summer Mega Bundle.