Development/Tutorials/Localization/i18n (fr)

Development/Tutorials/Localization/i18n

Languages: عربي | Asturianu | Català | Česky | Kaszëbsczi | Dansk | Deutsch | English | Esperanto | Español | Eesti | فارسی | Suomi | Français | Galego | Italiano | 日本語 | 한국어 | Norwegian | Polski | Português Brasileiro | Română | Русский | Svenska | Slovenčina | Slovenščina | српски | Türkçe | Tiếng Việt | Українська | 简体中文 | 繁體中文

Avoir à l'esprit le besoin de traduction lorsque l'on écrit une application

Série de tutoriels	Localization
Prérequis	Lire l'introduction à l'Unicode est recommandé, mais ce n'est pas obligatoire
Suite	Éviter les pièges de traduction les plus courants
Aller plus loin	n/a

Théorie

Avoir un grand nombre d'utilisateur et de développeurs requiert que votre logiciel puisse être traduit, ou tout au moins qu'il soit linguistiquement et culturellement (formats d'écriture (date, heure, ...), alphabets, sens d'écriture, ...) adapté à l'utilisateur de votre application. C'est le travail de la traduction (ou localisation) et ce tutoriel vous guidera sur les voies de la création d'applications facilement traduisibles.

Que sont l'internationalisation et la traduction ?

L'internationalisation, ou i18n ('i', suivit de 18 lettres, puis d'un 'n'), est le processus d'écriture d'applications qui peuvent être facilement localisables. Cela signifie prendre en compte des choses telles que :

• les messages textuels qui sont affichés à l'utilisateur
• les données envoyées ou écrites par l'utilisateur ; les fichiers par exemple
• les formats de dates, nombres, monnaie, etc.

La localisation, ou l10n ('l', suivit de 10 lettres, puis d'un 'n'), est le fait de "prendre" une application internationalisée et l'adapter à un pays ou à une langue.

D'une façon générale, les programmeurs internationalisent leurs applications, et les équipes de traduction les localisent.

Pourquoi est-ce si important ?

Le développement de KDE se fait principalement en Anglais, ce qui permet d'avoir de plus grandes communautés de développement et de traduction. Cependant, l'Anglais n'est pas le langage majoritaire dans le monde. En réalité, moins de 8% de l'Humanité par Anglais, et cette langue n'est la langue maternelle que de 5% des personnes. Mais, si actuellement 35% des personnes allant sur Internet parlent cette langue, ce chiffre diminue. De plus, un grand nombre de langues (9 par mis les 10 majoritaires) utilisent des caractères non-ASCII. Il est donc facile de comprendre le besoin de fournir un logiciel localisé.

En tant que projet international, une telle localisation est une des valeurs fondamentales de KDE. En fait, pendant que de nombreux développeurs de KDE écrivent leurs logiciels e Anglais, ils utilisent sur leur ordinateur leur langue native (qui n'est pas forcément l'Anglais).

Translatable Code Using i18n()

To ensure your application is ready to be localized you have to follow a few simple rules. All user-visible strings in your application should be translated before they are displayed on the user's screen, exceptions to this being debugging messages, configuration keys and similar types of text data.

KDE provides the KLocale class as part of libkdecore to facilitate the technical details of localization. KLocale makes it as easy as possible for developers to make their code i18n aware, but there are some things you need to be aware of so that applications are usable in other languages and countries.

Access to a global KLocale object is provided via KGlobal::locale(). This KLocale object is created automatically by KInstance and takes care of all user i18n related settings. It is deleted automatically on application exit.

Translations are made possible by the QString i18n(const char*) method, defined in klocalizedstring.h, which you must wrap all strings that should be displayed in. The QString returned by i18n() is the translated (if necessary) string. This makes creating translatable widgets as simple as in this example:

1. include <klocalizedstring.h>

[...] QPushButton* myButton = new QPushButton(i18n("Translate this!"));

QString's native Unicode support ensures that all translations are represented correctly. All string handling done by your application should therefore use QString.

Tip

If the string to be translated contains any non-UTF8 characters, use the utf8() method to get a char*.

ki18n

The i18n() method requires that a KInstance (e.g. KApplication) has been created. For any strings that are created prior to this there is another method provided: ki18n(). This allows one to mark strings that should be translated later as such. The ki18n() will return a KLocalizedString, which can be finalized into a QString (i.e. translated for real) after the KInstance has been created, using its toString() method.

ki18n() 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. Other than these special cases, it is always safe to use i18n() if you are sure that the code will be executed after construction of KApplication or some other KInstance.

Adding Context with i18nc()

There is an extended method, i18nc() which takes two const char* arguments. The first argument is an additional contextual description of the second string which will be translated. The first string is used to find the proper corresponding translation at run-time and is shown to translators to help them understand the meaning of the string.

Use i18nc() whenever the purpose of the text might be ambiguous without further context. For example, consider a context menu in a file manager with an entry called "View" which opens a viewer for the currently selected file. In this context "View" is a verb. However, the same application also may have a menu called "View" in the menubar. In that context "View" is a noun. In the English version of the application everything looks fine, but in most other languages one of the two "View" strings will be incorrect.

Additionally, translators sometimes need extra help in understanding what the text is actually referring to during the translation process.

In the file manager example above, one might therefore write:

contextMenu->addAction(i18nc("verb, to view something", "View")); viewMenu->addAction(i18nc("noun, the view", "View"));

Now the two strings will be properly translatable, both by the human translators and at runtime by KLocale.

Use this form of i18n whenever the string to translate is short or the meaning is hard to discern when the context is not exactly known. For example:

QString up = i18nc("Go one directory up in the hierarchy", "Up"); QString relation = i18nc("A person's name and their familial relationship to you.", "%1 is your %2", name, relationship);

Note

There is also a ki18nc("context","text") method for providing context to strings which are constructed before the KInstance. It returns a KLocalizedString, so use the toString() method afterwards to convert it into a QString.

Contexts can also be added when building forms in Qt Designer. Each widget label, including tooltips and whatsthis texts, has a "disambiguation" attribute (named "comment" prior to Qt 4.5), which will serve the same purpose as first argument to i18nc() call.

Standard Context For Common Phrases

Below is a chart showing some common words and phrases in English and the context that must be used with them to ensure proper translation of them in other languages.

Standard Contexts

Phrase	Context	i18nc Call	Example
Busy	Referring to a person	i18nc("A person is busy", "Busy")
Busy	Referring to a thing	i18nc("A thing is busy", "Busy")
Color	Color mode, as opposed to Grayscale	i18nc("Not Grayscale", "Color")
Creator	Referring to a person	i18nc("A person who creates", "Creator")
Creator	Referring to software	i18nc("Software", "Creator")
Display	Referring to hardware	i18nc("Hardware display", "Display")
Editor	Referring to a person	i18nc("A person who edits", "Editor")
Editor	Referring to software	i18nc("Software", "Editor")
Line	Referring to drawing	i18nc("Draw a line", "Line")
Line	Referring to text	i18nc("Line of text", "Line")
Name	Referring to a name of thing	i18nc("A thing's name", "Name")	In theme change dialog: i18nc("Theme name", "Name")
Name	Referring to first name and last name of person	i18nc("Person's first and last name", "Name")	In KAddessbook contact edit dialog: i18nc("Person's first and last name", "Name")
New	Create something	i18nc("Action", "New")
New	Status	i18nc("New mail message", "New")
No	Answer to a question	i18nc("Answer to a question", "No")
No	Availability of a thing	i18nc("Availability", "No")
(Re)load	(Re)load a document, medium etc.	i18nc("(Re)load a document", "(Re)load")
(Re)load	(Re)start a program, daemon etc.	i18nc("(Re)start a program", "(Re)load")
Title	Referring to a person	i18nc("A person's title", "Title")
Title	Referring to a thing	i18nc("A thing's title", "Title")
Trash	Referring to the action of emptying	i18nc("The trash is not empty. Empty it", "Empty")
Trash	Referring to the state of being empty	i18nc("The trash is empty. This is not an action, but a state", "Empty")
Volume	Referring to sound	i18nc("Sound volume", "Volume")
Volume	Referring to a filesystem	i18nc("Filesystem volume", "Volume")
Volume	Referring to books	i18nc("Book volume", "Volume")
Yes	Answer to a question	i18nc("Answer to a question", "Yes")
Yes	Availability of a thing	i18nc("Availability", "Yes")

Plurals

Plurals are handled differently from language to language. Many languages have different plurals for 2, 10, 20, 100, etc. When the string you want translated refers to more than one item, you must use the third form of i18n, the i18np(). It takes the singular and plural English forms as its first two arguments, followed by any substitution arguments as usual, but at least one of which should be integer-valued. For example:

msgStr = i18np("1 image in album %2", "%1 images in album %2", numImages, albumName); msgStr = i18np("Delete Group", "Delete Groups", numGroups);

i18np() gets expanded to as many cases as required by the user's language. In English, this is just two forms while in other languages it may be more, depending on the value of the first integer-valued argument.

Note that this form should be used even if the string always refers to more than one item as some languages use a singular form even when referring to a multiple (typically for 21, 31, etc.). This code:

i18n("%1 files were deleted", numFilesDeleted);

is therefore incorrect and should instead be:

i18np("1 file was deleted",

    "%1 files were deleted",
    numFilesDeleted);

To provide context as well as pluralization, use i18ncp as in this example:

i18ncp("Personal file", "1 file", "%1 files", numFiles);

Formatting Dates and Numbers

When displaying a number to the user, your program must take care of the decimal separator, thousand separator and currency symbol (if any) being used. These symbols differ from region to region. In English speaking countries a dot (.) is used to separate the fractional part of a number, while in some European countries a comma (,) is used instead. Below is a short summary of functions that will help you format the numbers correctly, taking the local conventions into account for you.

Functions to Format Numbers

Formats a..	From a..	Function Prototype
Number	String	QString formatNumber( const QString & numStr )
Number	Integer, double	formatNumber( double num, int precision = -1 )
Money	String	formatMoney( const QString & numStr )
Money	Number	formatMoney( double num, const QString & currency, int digits = -1 )
Date	String	formatDate( const QDate & pDate, bool shortFormat=false )
Time	QTime	formatTime( const QTime & pTime, bool includeSecs=false)
Date and time	QDateTime	formatDateTime( const QDateTime &pDateTime, bool shortFormat = true, bool includeSecs = false )

Similar functions exist to read information provided by the user at runtime in their localized format, e.g. readNumber() or readMoney().

Calendaring

Developing applications dealing with dates and time, such as calendars, is a very complex area. Not only may the displayed string containing a date or time look different based on locale, but one also has to take care of other aspects such as:

• what calendar system is being used (e.g. Hebrew, Hijri)
• which day in the week is the first one (cf int weekStartDay())
• how many months in a year there are
• "era"-based calendars
• whether to use 24-hour time format (cf bool use12Clock())

QDate only implements a hybrid Julian/Gregorian calendar system, if the user's locale has a different calendar system then any direct calls to QDate will result in incorrect dates being read and displayed, and incorrect date maths being performed. All date calculations and formatting must be performed through the KLocale and KCalendarSystem methods which provide a full set of methods matching those available in QDate. The current locale calendar system can be accessed via KGlobal::locale()->calendar(). The KLocale date formatting methods will always point to the current global calendar system.

KLocale provides, among others, these methods:

Calendar Data Functions

Formats a..	From a..	Function Prototype
Date	QDate	formatDate( const QDate & pDate, bool shortFormat=false )
Time	QTime	formatTime( const QTime & pTime, bool includeSecs=false )
Date and time	QDateTime	formatDateTime( const QDateTime &pDateTime, bool shortFormat=true, bool includeSecs=false )

Warning

This section needs improvements: Please help us to

cleanup confusing sections and fix sections which contain a todo

provide more info on the different calendar systems

Avoiding Common Traps

There are a number of common problems that may prevent an application being properly localized. See Avoiding Common Localization Pitfalls to learn more about them, and how to avoid them.

Note

Thanks to Lukáš Tinkl, Matthias Kiefer and Gary Cramblitt for writing the original version of this tutorial.