Graphical Desktop Environments like KDE and GNOME and the various applications that ship with them are written using C/C++ programming languages. Translating these environments means translating the tens of thousands of user visible strings from their native language (i.e. English) to a target language (i.e. Arabic). This is NOT done by copying the source code and replacing all the English strings with Arabic ones, its done by translating already extracted strings into their various files in order to ease the overall process.

The user visible strings are, thus, extracted from the source code with a program called 'gettext'. They these strings are extracted then are stored in a text file with a '.pot' extension. The '.pot' extension means that this file has NOT been translated yet (i.e. its in its original form). If you want to start a 'POT' file translation, then you have to first rename the file with the same name but with a '.po' extension. Let's say that you want to start translating the file 'filename.pot', you would then:

$ mv filename.pot filename.po
     

Work on translating the file and when satisfied with the amount of work you have accomplished, do the following:

$ cvs remove filename.pot
$ cvs add filename.po
$ cvs commit[]
      

The '.po' extension means that the translation has started on this file, without necessarily meaning that it is finished. Please remember to never translate 'POT' files. Either the files you are translating already have a '.po' extension or you'll be forced to rename them according to what has been described above. You are not required to change the extension of 'POT' files that you will NOT be translating in the very near future. This renaming has come to sorta mean that the person that renamed them owns them and will be working on them. If you have any doubts/questions, post to the 'doc' mailing list.

At run-time, the desktop environment will load the user visible strings from the target language translated 'PO' files and display them accordingly without any apparent change in the program behavior. If the translation is incomplete, the environment will simply display the original English strings where the translation is missing.

The sections that follow will give some guidelines with regards to how to translate 'PO' files. Remember that you can always use the 'doc' mailing list whenever you have any concerns (it would be unrealistic of us to pretend that these guidelines treat all issues that a translator may face). Translators are also encouraged to look at already translated 'PO' files in the CVS repository in a possible bid to learn further the various issues noted.

'msgid' strings starting with '_:' indicate a comment to help the translator or to give him/her more information about the message to translate is included. The comment ends with a '\n' (new line) sequence. Do NOT translate the help comment and simply put in the 'msgstr' the translation of only what follows the comment's '\n' (new line) sequence according to what you understood the comment was directing you to do.

Example:

#: cupsdconf.cpp:808 cupsdconf.cpp:831 cupsdconf.cpp:847
msgid ""
"_: Base\n"
"Root"
msgstr ""
"الجذر"
      

Translate only what comes after the '=' character while keeping the keyword intact (i.e. don't translate or modify "Comment" or "Name"); keep the keywords in English.

Example:

#: kde-i18n/vi/messages/entry.desktop:1
msgid "Name=Vietnamese"
msgstr "Name=الفييتنامية"
      

Some applications use Rich Text features (for paragraphs, colors, bold fonts, etc) to make their strings look nicer. This is accomplished while using HTML tags such as the "<p>" tag for instance. It is very important that the translated message keep all those tags. This is also the case for C print characters like "\n" or "\t" etc or "%s". Translate the text between the tags only. Also, remember that when you are in Right-to-Left input mode (i.e. when your are typing Arabic), the "\n" sequence may look odd - "n\". In either mode, remember that you need to enter first the "\" character and then the "n" irrespective of how they look on screen.

Example:

#: kio/kio/global.cpp:451
msgid "</p><p><b>Details of the Request</b>:"
msgstr "</p><p><b>تفاصيل الطّلب</b>:"
      

Keep the same punctuation in the translated messages as those found in the original strings. Carriage returns (or new lines) need to also be included. So if there multiple strings within a single 'msgid', the resulting 'msgstr' ought to mimic the original message in line number count (lines beginning with "_:" ought to be ignored as noted above since they are mere comments). See the example of comments.

The plural forms feature offers the possibility to display the correct word form depending on the quantity. They are distinguished by the "%n" character.

Sample:

msgid "_n: one cat\n"
"%n cats"
msgstr "قطّة واحدة\n"
"قطّتان\n"
"%n قطط\n"
"%n قطّة"          
      

The first 'msgstr' is displayed when there's a single cat. The second is displayed when there are 2 cats. The third is displayed when there are 3 to 10 cats. The last entry is displayed when the number of cats is equal-to or greater to 11. There is no need to report the "_n" in the translated message. Don't forget to use the "\n" character to separate between the different entries.

Characters preceded by an underscore character ("_") are called shortcuts or accelerators. The shortcut is used as a means to access directly a menu entry instead of selecting it via the mouse of cursor. The accelerators need to be translated in order to fit with an Arabic keyboard. That means that you will have to choose a letter from the word (or the sentence) as the accelerator. Try not to assign the same letter for two accelerators which are in the same menu (you can guess that from the location of the 'msgid' for example). As a rule of thumb, assign the first letter of the word to be the accelerator, if that letter is already used as shortcut in the current context, assign the second letter, etc. Do please try to be consistent.

Names (people, locations, some programs) can be transliterated to Arabic characters, others can even be translated totally or partly to Arabic. Acronyms like ASCII, HTTP, C++ etc should be kept in Latin characters. This is the same for program directives, class names, variables etc. Remember to read the Arabic Documentation Standards. When in doubt, post on the 'doc' list.

Some special characters like "&" need to be entered twice to tell the parser to keep it as is. Please translate and take this in account when needed.

Sample:

#: rc.cpp:19
msgid "Color && Animation"
msgstr "اللّون و الحركة"
      

Menu actions like "Edit", "Save", "Quit" etc and other related cases must be translated to Arabic in the imperative form. This is done for a standardization purpose (follow with the existing) and in order to give a more lively user/machine interaction. This is of EXTREME importance.

Sample:

#: ktouch.cpp:239
msgid "Save file..."
msgstr "إحفظ ملفّ..."
      

Please remember to ALWAYS save your files in UTF-8 encoding ^[4]. Otherwise, it can cause the file to be unreadable by others. UTF-8 is a global all-encompassing encoding (created and maintained by Unicode). UTF-8 enables the user to encode all world's languages as well as various symbols (mathematical ones for instance) in a single file. Before Unicode and UTF-8, it was nearly impossible to exchange documents between localized systems. So it is VERY important that all work be saved in this UTF-8 encoding (posting Arabic messages to 'doc' should also only occur in UTF-8). KBabel, once configured properly (more on that later), will automatically save all your files in UTF-8. If you use a text editor to do your translations, on the other hand, please check that your editor of choice supports UTF-8 and that you are indeed saving your work in that encoding. A check can be done with the 'file' command:

$ file filename.po
      

This command will give you filename.po's encoding.

If you start to work on a file and you find that it isn't saved in UTF-8 or that it has an encoding problem (displays boxes instead of regular characters for example) immediately stop working on this file and report the issue/problem to the 'doc' list. Once the problem is reported and prior to resolution, do work on another file instead of waiting by idly :-)

In order to check that the 'PO' file that you've translated does not contain any syntactical/syntax errors, you need to,

$ msgfmt -c --statistics filename.po
      

'msgfmt' being a program from GNU's 'gettext' package.

Is there are any errors, you will explicitly be warned about them with the appropriate line number(s) so you can easily locate and correct issues (missing double quotes ' " ' are very common). Baring any errors, this "msgfmt" command will give you statistics about what's been translated, what's not translated and how many fuzzy strings are in the file. Please, report these statistics in the commit log (i.e. when committing the file(s) to the CVS repository).

After translating an entire or part of a 'PO' file which you deem ought to be sent back to the repository, you need to commit the file(s) back to the repository. Here's a check-list of things you MUST do before committing a file:

If one or more of these requirements are not fulfilled, then please refer to what have been discussed above in order to remedy any problems. Otherwise, your files are eligible to be put on CVS :-)

If you had worked and translated several files at once, do please do a 'cvs commit' in order to send all those files grouped rather than committing them separately (saves bandwidth, less headaches, etc). While committing, and this is VERY IMPORTANT, remember to put the files' translation statistics in the commit log (how many strings on a per file basis were translated, untranslated and fuzzy). In case of a conflict (very unlikely), please refer to the CVS HOWTO.