KDE i18n Howto

This document gives a brief introduction howto prepare KDE applications to successfully support other languages and to be used in other countries. It also lists some common problems and how to avoid them.

Contents

• Introduction
• i18n
  • How to prepare the code
  • Things to take care of
  • Makefiles and distributing translations
  • Technical details
• l10n
  • Technical details
• Links and additional information

Introduction

To support internationalization (i18n) and localization (l10n) KDE offers the class KLocale which is contained in kdecore. KLocale has a lot of functionality to make it as easy as possible for developers to make their code i18n aware. Nevertheless there are some things to take care of, so that applications are useable in other languages and countries, too.

To use KLocale, you don't have to create an instance of it by your own, but you have access to the global KLocale object with KGlobal::locale(). The object you receive takes care of all user settings and will be deleted automatically on application exit. The next few paragraphs will show in more detail how to use the functionality of KLocale and what you have to take care of.

i18n

i18n is a short for internationalization, and means that the program will be displayed in the language you choose. In KDE, all strings should be translated before they are displayed on the user's screen. What you should not translate are debug messages and similiar.

How to prepare the code

To make translations possible, the programmer has to use i18n() on all strings that should be displayed. i18n() takes a const char* as an argument and returns a translated QString or the original string if no translation was found. As you see on the returned value, which is of type QString, you should use QString for all strings, that can be translated, because it uses internally unicode characters and therefore can handle strings in all languages. While when you you are using the classical char* string, you will have to take care of the different possible charsets by your own. (If you are wondering where to find documentation of the i18n() function: it is defined as a global function in klocale.h and uses KLocale::translate() internally)

Since all equal strings are summarized and are therefore translated with the same string, there is an additional extended function i18n() which takes two const char* arguments. The first argument is an additional description of the second string (which is shown to the user) and both strings together are used to find the corresponding translation. In addition the first argument is shown to the translators as hint of the meaning or context of this string.

Example: Think of a file manager, where you can open a context menu on a file and select View to view the file. In this context View is a verb. Additionaly the window of the file manager has a menu View in the menubar. In this context View is a noun. In the english version of the application everything looks fine, but in most other languages one of the strings will be wrong and confuses the user. Even if equal strings would not be translated with the same string, it would be difficult for the translators to find out, which of these strings is used as verb and which as noun. The solution for this is to use the extended i18n() function: For the context menu something like i18n("to view something","View") and for the menu in the menubar i18n("the view","View"). This way both strings are translated as separate strings and the translator has a hint how to translate these strings.

In general it is a very good idea to use this extended function, if the string to translate is short and the meaning is hard to find out, when the context is not exactly known.

You may have seen another translation function in application templates or other existing code: I18N_NOOP(). This function does not actually translate a string, but just marks the string for translation, so that the string will get extracted and included in the po files. If you want to translate the string, you still have to use i18n() with exactly the same string afterwards. I18N_NOOP() is typically used for strings given to KAboutData, because it is constructed before the KApplication and you can use i18n() only after the construction of the KApplication. So it is safe to use always i18n() and never I18N_NOOP() if you are sure, that the code will be executed after construction of KApplication.

Things to take care of

Although using i18n() for all visible messages is the main work to get your application translated, there are some traps, which prevent your application to be usable in some languages. Mainly these are layout problems and problems with string concatenation.

• You might know, that english text is often very compact while in other languages the translated text might be a lot longer. If you developed the GUI of your application carefully, you will not have a problem with this, because you might anyway have used a layoutmanager to take care of the widget geometry for you. Of course you can implement geometry management by your own, but it is very likely, that you might get in trouble with the widget geometry when you use functions like QWidget::setGeometry() or similiar. To get rid of this problem and let your application look nice also when used in other languages it is highly recommended to use layout manager as they are provided by Qt with QLayout and derived classes. For more information look at the documentation of QLayout.
• Another thing to take care of, is to not concatenate strings together like this:

  QString msg=i18n("Do you want to replace ")+oldFile+i18n(" with ")+newFile+"?"

  The result of contructs like this is, that it is only very hard or impossible to translate, because the structure of the sentence may be completly different in another language and the translator will only see parts of the sentences and has to guess what belongs together.
  The solution for this problem is to use QString::arg() which lets the translator not only make good translations because he sees the whole sentence but also let him change the order of the arguments freely. Because of this last advantage QString::arg is also recommended to use instead of sprintf and similar functions. The above example would then look like this:

  QString msg=i18n("Do you want to replace %1 with %2").arg(oldFile).arg(newFile)

  Note: Don't insert anything else then numbers, names or similiar with this method, since in some languages the translation depends on the inserted words. Better use more complete strings instead, if possible.
• Don't ever call QString::latin1() on translated strings unless you really know what you are doing. KDE applications are translated in many languages, that use other charsets than latin1. If you really need a char* representation of a string, better use QString::local8Bit() or even better QString::utf8(). For more information on charsets and unicode in special see the KDE Unicode Howto.
• Many people define common messages with #define for example to have a consistent name for the application. Although this works in principle, there is a problem with extracting the text, because gettext does not recognize these strings and therefore these get not translated. A solution is to create a dummy cpp-file, that contains these strings and so gettext can extract these messages, too. Such a file would look like this:

  i18n("The first text");
  i18n("The second text");

  and then you can define somewhere else

  #define FIRSTTEXT i18n("The first text")
  #define SECONDTEXT i18n("The second text")

  Note: The strings must be exactly the same to get translated.
• Messages, that contain a version string or similiar often changing things should use QString::arg() to insert this string into the message. Otherwise every change will cause the translators to change the translated messages, too. Of course only names, numbers and such things should be inserted with QString::arg().
  (Since for example KDE 2.0 is translated into more than 30 languages, a single change causes at least 30 people to open the file, find the changed message, look carefully, if this is the only thing that has changed, change the translation, save the file again and commit the changed file into CVS. All in all such a small change might cause work of more than one hour. Just to give you an idea, to please think carefully about the messages you use.)

Makefiles and distributing translations

If your application is in KDE CVS you don't have to do anything. The messages are automatically extracted and will then translated by the KDE translation teams.

If your application is not in the KDE CVS you have to extract the messages by yourself and provide the translated po files within your distribution. To extract the messages you need to have gettext installed and extractrc from kdesdk has to be in your path. (Note:KDE uses a patched version of gettext to use the above mentioned additional context information. You can find this patch in kdesdk/scripts). Then just call in the base directory of your distribution make -f admin/Makefile.common package-messages and after that you will find a file <appname>.pot, which contains all messages of your application, in the subdirectory po. If there is not already a Makefile.am in this directory create one with the following single line as content:

POFILES = AUTO

and add the po-directory to SUBDIRS in Makefile.am of the base directory. Now you just have to find translators to translate the extracted messages into the various languages. ;-) Translated po files then have to be stored in the po-directory with the naming scheme <languagecode>.po.
If you are extracting messages when you already have translated po files of older versions, just call make -f admin/Makefile.common package-merge and the new contents of the pot file will be merged into the already translated po files. This way translators only have to translate new or changed messages.

Technical details

The actual translation is done with the gettext package. It contains tools for extracting the messages from source files and to handle changed messages, so that translators does not have to start over and over again. The extracted messages and the translations are stored in so called po files using different encodings. These files are then compiled into a binary format (mo files) which then get installed.

All translations of a language has to be stored in the same encoding, which is defined in the charset file. KLocale reads this file when constructed and uses this information to decode the translations.

l10n

l10n is a short for localization, and means that the program will be aware of your location (i.e. where you live) and use that information when the program asks for input or print something to the screen. For example to format numbers or money strings. Below is a list of the most important l10n supported by KLocale. All input and output of your application should use these functions. The usage of this function should be straight forward. See the documentation of KLocale for more details.

Technical details

The user's configuration is stored in kdeglobals and the different country profiles are stored in share/locale/l10n/+country_code. country_code is replaced with the short version of ISO 3166 country code for the country in lower case.

Links and additional information

• gettext
• KDE Unicode Howto
• i18n pages of KDE
• Linux Internationalization Initiative
• International Linux
• Linux i18n project

Last updated: 3 February 2001, Matthias Kiefer <kiefer@kde.org>