New tutorial: How to translate Minibloq

As promised, here is the tutorial about how to translate the new Minibloq.v0.81.Beta to a new language (of course, we are always looking for translators!). This is a fragment of the new Minibloq's Developers Guide (still under construction), where we describe (briefely by now) how to translate, customize the GUI, add new blocks and in the near future, how to compile Minibloq both under Linux and Windows:


1. How to translate Minibloq

Since the version v0.81.Beta, Minibloq supports internationalization (i18n) / localization (i10n). This brief tutorial explains how to translate Minibloq, using open source tools. Before start translating, you will need to:

1. Download the last Minibloq version from the downloads page.
2. Install Minibloq in your computer. For development purposes, it's highly recommended to install it in a directory where you can freely modify files, instead of the default C:\Program Files (or C:\Program Files (x86) folder. For example, in Windows 7, the Program Files folder is protected. So it will be better to install Minibloq elsewhere, in some temporal dir where you can write, copy, delete or edit files without administrative permissions.
3. Download Poedit from http://poedit.net (we used the version 1.4.6 for all our internal work).

It's also important to know that there is a specific topic in Minibloq's forum related to internationalization (18n).

1.1. Translating the GUI

The first thing to be translated is the GUI itself. This task is relatively easy, by following these steps:

1. Every language has an international 2 letters code, called ISO 639-1. You will need to find your language code first. You can go to this link for that:  http://en.wikipedia.org/wiki/List_of_ISO_639-1_codes
2. In Minibloq's installation path (for example C:\Program Files (x86)\Minibloq.v0.81.Beta), go to the following folder: Components\Minibloq\v1.0\GUI\Texts, and make a copy of the files en.po and en.Metadata.po.
3. Now rename both new files (the copies you just made) using your 2 letters language code, instead of the English code "en". For example: Supose we are translating to Spanish. The code for Spanish is "es", so you will end with a file named es.po and another named es.Metadata.po (note: the names are case sensitive, so you must take care of using exactly these names).
4. Open the Metada "po" file (ie, en.Metadata.po for English, es.Metadata.po for Spanish, etc.) with a raw text editor (in Windows you can even use the Notepad) and change the "en" code in the following line by your new language code:
   
   

    msgid "en.Name"
   

   
   For example, for Spanish, you will end with a line like this:
   
   

    msgid "es.Name"
   

5. Now open the Metadata file with Poedit and change the language name ("English" in this case) by the new language name, but written in the new language itself. For example, for Spanish, it will be "Español":

6. In Poedit, press the Save button (or go to the menu File->Save). This will not only save the .po file, but will also generate the .mo file, which is the compiled, portable, OS independent file that Minibloq will need to work (but please don't delete the .po file, it will be deployed with Minibloq also!)
7. Now open the file xx.po with Poedit (where xx is your language code). In our example with Spanish, it will be the es.po file. Here, you can start translating each text string with the Poedit software. Poedit have, among other features, support for nearly any charset out there. Here is a screenshot with the Spanish file:

Every time you advance with the translation, it's good to press the save button. As before, it will generate the .mo file also. Once you finish, you will have for files: xx.Metadata.po, xx.Metadata.mo, xx.po and xx.mo (where "xx" is your language code).


8. Now you can test the new language files without restarting Minibloq. Just go to the View->Properties menu and press the Reload languages button. If everything is fine, your new language must be listed in the Language combobox:

1.2. Translating blocks' tooltips

Now let's translate the tooltips for the blocks. As Minibloq is modular and every user can add his own blocks, each block has its own tooltip files. These files are located in the subdir Doc of each block directory (the blocks directories are here: Components\Minibloq\Lib\CPP\Blocks). So, inside each Doc subdir you will find standard .po files that can be translated easily with Poedit, and saved to .mo. You just need to open them with Poedit, change the tooltip string and save it. Here is a screenshot of Poedit with a .po file:

 1.3. Translating help files

The help files do not involve any special program or procedure to be translated. They are just plain HTML files, and they can be edited and translated with any decent HMTL editor. There are only three important things regarding help files:

1. You must keep the names of the files, in English, just as they are now.
2. You will need to add the directory with the help files for your language, even if you don't translate them. If you don't do this, Minibloq may show an error dialog box when you select your language or  when you start the application. If you will not translate the files, our advice is just to copy the English help files directory (called simply "en"), and renaming it. The name must be the 2 letters code (ISO 639-1) mentioned above.
3. If you translate the files, try to use a plain text editor, or a good HTML editor which does not add overhead, nor hidden characters.

The help files are in the following Minibloq's subdir: Components\Minibloq\v1.0\Doc