|
|
|
|
Localization of scripts Explains how to add translation capabilities to your scripts |
Introduction |
| Adding the translated versions of the strings adds a great value to your scripts. The process of translating a part of software is called localization. KVIrc offers some commands and functions for this purpose and this document explains briefly how to use them. |
The big picture |
|
All of the strings in your script are written in a primary language. The most common primary language is English, but theoretically it can be any language of your choice. By the means of the gettext package programs you extract the strings from your script and produce a translation file. The translation file is then effectively translated in another language and later compiled in a binary form. The binary form translations are then loaded in the KVIrc executable at runtime and a function is used to look up the translations. |
How to translate scripts |
|
Your strings should be surrounded by the $tr() function in the following way: |
$tr("your default language text") |
|
Then you should run the xgettext command on your script files. This is done by a shell commandline similar to the following: |
xgettext -o myscript.pot -ktr mykvsfile1.kvs mykvsfile2.kvs ... |
|
Copy the translation file obtained in the following way: |
cp myscript.pot myscript_XX.po |
| Where the XX is your country/language code. For example, for Italian it would be: |
cp myscript.pot myscript_it.po |
|
Translate mytranslation_it.po. The format of the po file is straightforward. There are msgid lines with the original English text and immediately following msgstr lines that must be filled with the corresponding translation. For example in Italian you would translate: msgid "your default language text" msgstr "il tuo testo in linguaggio predefinito" Compile your translation to binary form with the following command: |
msgfmt -o myscript_it.mo myscript_it.po |
|
Copy the generated *.mo file to the locale subdirectory
in the KVIrc's local directory (usually $HOME/.kvirc/locale/).
Set the system language to the XX above with the following command: |
export LANG="XX" |
| For Italian it would be: |
| export LANG="it" |
|
Start KVIrc and type in the commandline: |
echo $tr("your default language text","myscript") |
|
If you did everything well, you should see the translated
text echoed in the window :) Obviously if you don't set LANG="XX", the same command will output the original string unchanged. You can manage translations in several languages by producing several *.mo files all with the proper language/country code appended. The right *.mo file will be magically loaded by KVIrc that will look up the user's LANG variable. (If you don't want to use LANG, you can use KVIRC_LANG instead, it will still work). |
Caveats |
|
You should never use variables or identifiers inside the $tr() function. This because the translation files are generated offline, when the string is not evaluated yet (i.e variables ad identifiers are not substituted by their actual return values). The translation process, instead, happens at runtime, when the variables and identifiers have been substituted by their actual values. This would lead to a mismatch between the string you look up in the translation catalog and the effectively translated one. If you need to include variables in your strings you should compose the string with smaller pieces |
echo $tr("On this channel") %number $tr("users are operators") |
| The translation process can be realized only if your scripts are written in external files. This makes sense since if you're translating the script then you will probably want to distribute it and the only way to distribute it is on files. But well.. this is a caveat. |