Internationalisation avec Qt

L'internationalisation d'une application est le processus ayant pour but de rendre l'application utilisable en dehors de son propre pays.

Pas � pas
Utiliser QString pour tous les textes visibles par l'utilisateur	Utiliser QString::arg() pour les textes dynamiques	Gestion des encodages
Utiliser tr() pour tous les textes litt�raux	Produire les traductions	Faire la localisation
Utiliser QKeySequence() pour les valeurs de raccourcis clavier
Support syst�me
Unix/X11	Windows	Mac OS X

Classes et API Qt impliqu�es

Ces classes permettent l'internationalisation des applications Qt.

QInputContext	Abstraction des donn�es et �tats de composition sp�cifiques aux m�thodes de saisie.
QLocale	Conversions entre des nombres et leur repr�sentation en cha�nes de caract�res dans diverses langues.
QSystemLocale	Peut �tre utilis� pour des ajustements fins des options r�gionales de l'utilisateur.
QTextCodec	Conversions entre encodages de texte.
QTextDecoder	D�codeur.
QTextEncoder	Encodeur.
QTranslator	Gestion de l'internationalisation des textes affich�s.
R�gles de traduction pour les pluriels	Un r�sum� des r�gles de traduction pour les pluriels produites par les outils d'internationalisation (i18n) de Qt.
�crire du code source pour la traduction	La fa�on d'�crire du code source rendant possible la traduction des textes visibles par l'utilisateur.

Langues et syst�mes d'�criture

Dans certains cas, l'internationalisation est simple ; par exemple, rendre une application destin�e aux USA accessible aux utilisateurs australiens ou anglais peut ne demander que quelques corrections orthographiques. Mais rendre la m�me application utilisable par des japonais ou rendre une application cor�enne utilisable par des allemands va demander au logiciel de non seulement op�rer dans des langues diff�rentes, mais aussi d'utiliser des techniques de saisie et des conventions de pr�sentation diff�rentes et diff�rents encodages de caract�res.

Qt tente de rendre l'internationalisation la moins p�nible possible pour les d�veloppeurs. Tous les widgets de saisie et les m�thodes de dessin de texte dans Qt int�grent la gestion de toutes les langues support�es. Le moteur de polices int�gr� est capable de simultan�ment produire un rendu correct de textes contenant des caract�res de syst�mes d'�criture diff�rents.

Qt g�re la plupart des langues utilis�es aujourd'hui, en particulier :

• les langues est-asiatiques (chinois, japonais et cor�en) ;
• les langues occidentales (utilisant l'�criture latine) ;
• l'arabe ;
• les langues cyrilliques (russe, ukrainien, etc.) ;
• le grec ;
• l'h�breu ;
• le tha� et le laotien ;
• tous les scripts en Unicode 5.1 ne demandant pas de traitement particulier.

Sur Windows, Unix/X11 avec FontConfig (gestion des polices c�t� client) et Qt for Embedded Linux, les langues suivantes sont �galement support�es :

• bengali ;
• d�vanagari ;
• divehi (alphabet th�na) ;
• gujar�t� ;
• gurmukhi ;
• kannada ;
• khmer ;
• malay�lam ;
• birman ;
• syriaque ;
• tamil ;
• t�lougou ;
• tib�tain ;
• n'ko.

Plusieurs de ces syst�mes d'�criture poss�dent des caract�ristiques particuli�res.

• Comportement sp�cial des sauts de ligne. Certaines langues asiatiques sont �crites sans espaces entre les mots. Les sauts des lignes peuvent se produire soit apr�s chaque caract�re (avec des exceptions) comme en chinois, japonais et cor�en ou sur des fronti�res logiques des mots comme en tha�.
• �criture bidirectionnelle. L'arabe et l'h�breu sont �crits de droite � gauche, sauf pour les nombres et les fragments de texte en Anglais qui sont �crits de gauche � droite. Le comportement exact est d�crit dans l'annexe technique Unicode #9.
• Marques diacritiques (accents ou umlauts dans les langues europ�ennes). Certaines langues comme le vietnamien font un usage intensif de ces marques et certains caract�res peuvent poss�der simultan�ment plusieurs marques pour clarifier la prononciation.
• Ligatures. Dans certains contextes, des paires de caract�res sont remplac�es par un glyphe combin� formant une ligature. Les ligatures fl et fi utilis�es dans les livres europ�ens et am�ricains sont les exemples les plus courants.

Qt essaie de traiter tous les cas list�s ci-dessus. Vous ne devez normalement pas vous soucier de ces particularit�s tant que vous utilisez les widgets de saisie Qt (par exemple, QLineEdit, QTextEdit et leur classes d�riv�es) et les widgets d'affichage de Qt (comme QLabel).

La gestion de ces syst�mes d'�criture est transparente pour le programmeur et compl�tement encapsul�e dans le moteur texte de Qt. Cela signifie que vous n'avez pas besoin de conna�tre le syst�me d'�criture utilis� dans une langue particuli�re, sauf pour les points mineurs suivants :

• QPainter::drawText(int x, int y, const QString &str) dessinera toujours la cha�ne avec un bord gauche � la position sp�cifi�e par les param�tres x et y. Ceci donnera le plus souvent un texte align� � gauche. Les cha�nes en arabe et en h�breu sont g�n�ralement align�es � droite, donc, pour ces langues, il faut utiliser la version de drawText() prenant en param�tre un QRect pour obtenir un alignement en fonction de la langue ;
• lorsque vous �crivez vous propres contr�les de saisie de texte, utilisez QTextLayout. Dans certaines langues (par exemple l'arabe ou les langues du sous-continent indien), la largeur et la forme du glyphe changent en fonction des caract�res voisins, ce qui est pris en compte par QTextLayout. L'�criture d'un contr�le de saisie requiert souvent une connaissance du contexte dans lequel il va �tre utilis�. Le plus simple est g�n�ralement de d�river QLineEdit ou QTextEdit.

Les sections suivantes donnent des informations sur l'�tat du support de l'internationalisation (i18n) dans Qt. Voir aussi le manuel de Qt Linguist.

Pas � pas

L'�criture de logiciel international et multi-plateforme avec Qt est un processus simple et incr�mental. Votre logiciel peut �tre internationalis� en suivant les �tapes suivantes.

Utiliser QString pour tous les textes visibles par l'utilisateur

�tant donn� que QString utilise en interne l'encodage Unicode 5.1, toutes les langues du monde peuvent �tre trait�es de fa�on transparente en utilisant les op�rations famili�res de manipulation de texte. De plus, comme toutes les fonctions Qt pr�sentant du texte � l'utilisateur prennent un param�tre QString, il n'y a pas de surco�t li� � la conversion de char * en QString.

Les cha�nes qui sont dans le « domaine du programmeur » (comme les noms de QObject et les textes des formats de fichier) n'ont pas besoin d'utiliser QString ; le char * traditionnel ou la classe QByteArray suffit.

Vous ne devriez pas remarquer de diff�rence du fait de l'usage de l'Unicode ; QString et QChar se comportent comme des versions plus faciles � utiliser des const char * et char du C traditionnel.

Partout o� votre programme utilise du « texte entre guillemets » pour du texte qui sera pr�sent� � l'utilisateur, assurez-vous qu'il sera trait� par la fonction QCoreApplication::translate(). Pour l'essentiel, il suffit d'utiliser QObject::tr(). Par exemple, en supposant que

LoginWidget

est une classe d�riv�e de QWidget :

 LoginWidget::LoginWidget()
 {
     QLabel *label = new QLabel(tr("Mot de passe:"));
     ...
 }

Ce cas repr�sente 99 % des cha�nes visibles par l'utilisateur que vous �crirez.

Si le texte n'est pas dans une fonction membre d'une classe d�riv�e de QObject, utilisez soit la fonction tr() de la classe appropri�e, soit directement la fonction QCoreApplication::translate():

 void some_global_function(LoginWidget *logwid)
 {
     QLabel *label = new QLabel(
                 LoginWidget::tr("Mot de passe:"), logwid);
 }
 
 void same_global_function(LoginWidget *logwid)
 {
     QLabel *label = new QLabel(
                 qApp->translate("LoginWidget", "Mot de passe:"), logwid);
 }

Si vous devez traduire du texte compl�tement � l'ext�rieur d'une fonction, deux macros peuvent vous aider : QT_TR_NOOP() et QT_TRANSLATE_NOOP(). Elles marquent simplement le texte pour une extraction par l'utilitaire lupdate d�crit ci-dessous. Les macros ne conservent que le texte (sans le contexte).

Exemple de QT_TR_NOOP() :

 QString FriendlyConversation::greeting(int type)
 {
     static const char *greeting_strings[] = {
         QT_TR_NOOP("Bonjour"),
         QT_TR_NOOP("Au revoir")
     };
     return tr(greeting_strings[type]);
 }

Exemple de QT_TRANSLATE_NOOP() :

 static const char *greeting_strings[] = {
     QT_TRANSLATE_NOOP("FriendlyConversation", "Bonjour"),
     QT_TRANSLATE_NOOP("FriendlyConversation", "Au revoir")
 };
 
 QString FriendlyConversation::greeting(int type)
 {
     return tr(greeting_strings[type]);
 }
 
 QString global_greeting(int type)
 {
     return qApp->translate("FriendlyConversation",
                            greeting_strings[type]);
 }

Si vous d�sactivez la conversion automatique de const char * en QString en compilant votre logiciel avec la macro QT_NO_CAST_FROM_ASCII d�finie, vous aurez de fortes chances de d�tecter des cha�nes que vous auriez manqu�. Voir QString::fromLatin1() pour plus d'informations. D�sactiver la conversion peut rendre la programmation plus lourde.

Si votre langue source utilise des caract�res hors du jeu Latin1, vous pourriez trouver QObject::trUtf8() plus pratique que QObject::tr(), �tant donn� que tr() d�pend de QTextCodec::codecForTr(), ce qui le rend plus fragile que QObject::trUtf8().

Les valeurs de raccourcis clavier comme Ctrl+Q or Alt+F doivent elles aussi �tre traduites. Si vous �crivez directement Qt::CTRL + Qt::Key_Q pour « Quitter » dans votre application, les traducteurs ne pourront pas changer ces valeurs. L'idiome correct est :

     exitAct = new QAction(tr("Q&uitter"), this);
     exitAct->setShortcuts(QKeySequence::Quit);

Les fonctions QString::arg() fournissent une m�thode simple de substitution des arguments :

 void FileCopier::showProgress(int done, int total,
                               const QString &currentFile)
 {
     label.setText(tr("%1 sur %2 fichiers copi�s.\nCopie de : %3")
                   .arg(done)
                   .arg(total)
                   .arg(currentFile));
 }

Dans certaines langues, l'ordre des arguments doit �tre chang� et cela peut �tre fait facilement en changeant l'ordre des arguments %. Par exemple :

 QString s1 = "%1 of %2 files copied. Copying: %3";
 QString s2 = "Kopierer nu %3. Av totalt %2 filer er %1 kopiert.";
 
 qDebug() << s1.arg(5).arg(10).arg("somefile.txt");
 qDebug() << s2.arg(5).arg(10).arg("somefile.txt");

Ceci produit la sortie correcte en anglais et en norv�gien :

 5 of 10 files copied. Copying: somefile.txt
 Kopierer nu somefile.txt. Av totalt 10 filer er 5 kopiert.

Produire les traductions

Une fois que vous avez plac� les

tr()

dans toute l'application, vous pouvez commencer � produire les traductions des textes visibles par l'utilisateur.

Le manuel de Qt Linguist contient des informations suppl�mentaires sur les outils de traduction de Qt, Qt Linguist, lupdate et lrelease.

La traduction d'une application Qt se d�roule en trois �tapes :

1. ex�cuter lupdate pour extraire les textes � traduire du code source C++ de l'application Qt, ce qui produit un fichier message pour les traducteurs (un fichier TS). Cet utilitaire reconnait la construction tr() et les macros QT_TR*_NOOP() d�crites ci-dessus et produit des fichiers TS (en principe, un par langue) ;
2. effectuer les traductions des textes du fichier TS en utilisant Qt Linguist. �tant donn� que les fichiers TS sont au format XML, vous pouvez aussi les �diter � la main ;
3. ex�cuter lrelease pour cr�er un fichier message all�g� (un fichier QM) � partir du fichier TS. On peut voir les fichiers TS comme des « fichiers source » et les fichiers QM comme des « fichiers objet ». Le traducteur �dite les fichiers TS mais les utilisateurs de votre application ont seulement besoin des fichiers QM. Ces deux types de fichier sont ind�pendants de la plateforme et des param�tres r�gionaux.

Normalement, vous r�p�terez ces �tapes � chaque version de votre application. L'utilitaire lupdate essaie de r�utiliser au maximum les traductions des versions pr�c�dentes.

Avant de lancer lupdate, vous devez pr�parer un fichier projet. Voici un exemple de fichier projet (fichier .pro) :

 HEADERS         = funnydialog.h \
                   wackywidget.h
 SOURCES         = funnydialog.cpp \
                   main.cpp \
                   wackywidget.cpp
 FORMS           = fancybox.ui
 TRANSLATIONS    = superapp_dk.ts \
                   superapp_fi.ts \
                   superapp_no.ts \
                   superapp_se.ts

Quand vous lancez lupdate ou lrelease, vous devez donner le nom du fichier projet en argument de ligne de commande.

Dans cet exemple, quatre langues exotiques sont g�r�es : le danois, le finnois, le norv�gien et le su�dois. Si vous utilisez qmake, vous n'aurez en g�n�ral pas besoin d'un fichier projet suppl�mentaire pour lupdate ; votre fichier de projet qmake fonctionnera correctement si vous ajoutez l'entr�e TRANSLATIONS.

Dans votre application, vous devez charger les fichiers de traduction appropri�s � la langue de l'utilisateur avec QTranslator::load() et les installer avec QCoreApplication::installTranslator().

linguist, lupdate and lrelease sont install�s dans le sous-r�pertoire bin du r�pertoire de base dans lequel Qt est install�. Cliquez sur « Help|Manual » dans Qt Linguist pour acc�der au manuel utilisateur ; il contient un tutoriel destin�s aux d�butants.

Qt lui-m�me contient quatre cents cha�nes devant aussi �tre traduites dans les langues que vous ciblez. Vous trouverez des fichiers de traduction pour le fran�ais, l'allemand et le chinois simplifi� dans $QTDIR/translations, ainsi qu'un mod�le pour la traduction dans d'autres langues. Ce r�pertoire contient aussi des traductions non support�es qui peuvent �tre utiles.

Habituellement, la fonction main() de votre application ressemblera � ceci :

 int main(int argc, char *argv[])
 {
     QApplication app(argc, argv);
 
     QTranslator qtTranslator;
     qtTranslator.load("qt_" + QLocale::system().name(),
             QLibraryInfo::location(QLibraryInfo::TranslationsPath));
     app.installTranslator(&qtTranslator);
 
     QTranslator myappTranslator;
     myappTranslator.load("myapp_" + QLocale::system().name());
     app.installTranslator(&myappTranslator);
 
     ...
     return app.exec();
 }

Notez l'usage de QLibraryInfo::location() pour trouver l'emplacement des traductions de Qt. Les programmeurs doivent demander le chemin des traductions � l'ex�cution en passant QLibraryInfo::TranslationsPath � cette fonction au lieu d'utiliser la variable d'environnement QTDIR.

Gestion des encodages

La classe QTextCodec et les fonctionnalit�s de QTextStream facilitent la gestion de nombreux encodages des donn�es de vos utilisateurs en entr�e et en sortie. Lorsqu'une application est lanc�e, les param�tres r�gionaux de la machine vont d�terminer l'encodage sur 8 bits utilis� pour des donn�es 8 bits, comme pour la s�lection de polices, l'affichage de texte, les entr�es/sorties de texte 8 bits et les saisies de caract�res.

L'application peut dans certains cas demander des encodages diff�rents de l'encodage 8 bits local par d�faut. Par exemple, une application en Cyrillic KOI8-R (l'encodage par d�faut en Russie) peut avoir besoin de produire du cyrillique en encodage ISO 8859-5. Le code pour faire cela serait :

 QString string = ...; // du texte Unicode
 
 QTextCodec *codec = QTextCodec::codecForName("ISO 8859-5");
 QByteArray encodedString = codec->fromUnicode(string);

Pour la conversion de l'Unicode en encodage 8 bits local, il existe un raccourci : la fonction QString::toLocal8Bit() renvoie des donn�es 8 bits localis�es. Un autre raccourci utile est QString::toUtf8(), qui renvoie du texte en encodage 8 bits UTF-8 : ceci pr�serve parfaitement l'information Unicode tout en ayant l'apparence de l'ASCII simple si le texte est enti�rement ASCII.

Pour la conversion en sens inverse, il existe les fonctions QString::fromUtf8() et QString::fromLocal8Bit(), ou le code g�n�ral, illustr� par cette conversion de ISO 8859-5 Cyrillic vers Unicode :

 QByteArray encodedString = ...; // du texte en encodage ISO 8859-5
 
 QTextCodec *codec = QTextCodec::codecForName("ISO 8859-5");
 QString string = codec->toUnicode(encodedString);

Id�alement, il faudrait utiliser les entr�es-sorties Unicode, car elles maximisent la portabilit� des documents entre les utilisateurs du monde entier mais, en r�alit�, il est utile de g�rer tous les encodages dont vos utilisateurs auront besoin pour traiter les documents existants. En g�n�ral, Unicode (UTF-16 ou UTF-8) est adapt� pour les informations transf�r�es entre destinataires arbitraires, alors que, � l'int�rieur d'une langue ou d'un groupe national, un standard local est souvent plus appropri�. L'encodage le plus important � g�rer est celui renvoy� par QTextCodec::codecForLocale(), car c'est celui dont l'utilisateur a le plus de chances d'avoir besoin pour communiquer avec d'autres personnes et d'autres applications (c'est l'encodage utilis� par local8Bit()).

Qt g�re nativement les encodages les plus utilis�s. Pour une lise compl�te des encodages support�s, voir la documentation QTextCodec.

Dans certains cas et pour les encodages moins courants, il peut �tre n�cessaire d'�crire votre propre classe d�riv�e de QTextCodec. Suivant l'urgence, il peut �tre utile de contacter le support technique de Qt ou de poster une question sur la liste de diffusion qt-interest pour savoir si quelqu'un d'autre travaille d�j� sur cet encodage particulier.

Faire la localisation

La « localisation » est le processus d'adaptation aux conventions locales, par exemple la pr�sentation des dates et des heures en utilisant le format pr�f�r�. Ceci peut se faire en utilisant des cha�nes tr().

 void Clock::setTime(const QTime &time)
 {
     if (tr("AMPM") == "AMPM") {
         // horloge sur 12 heures
     } else {
         // horloge sur 24 heures
     }
 }

Dans l'exemple, pour les USA, nous laisserions telle quelle la traduction de « AMPM » et donc utiliserions la branche avec l'horloge sur 12 heures ; mais, en Europe, nous traduirions autrement et donc le code utiliserait la branche avec l'horloge sur 24 heures.

Pour la localisation des nombres, voir la classe QLocale.

La localisation des images n'est pas recommand�e. Choisissez des images claires appropri�es pour toutes les r�gions du monde plut�t que de vous appuyer sur des m�taphores locales. Les images des fl�ches gauches et droites sont des exceptions pouvant n�cessiter une inversion pour la langue arabe et l'h�breu.

Traductions dynamiques

Certaines applications, comme Qt Linguist, doivent �tre capables de g�rer des changements des param�tres de langue de l'utilisateur en cours d'ex�cution. Pour que les widgets d�tectent les changements des QTranslators install�s, r�impl�mentez la fonction changeEvent() pour v�rifier si l'�v�nement est de type LanguageChange et mettez � jour le texte affich� par les widgets en utilisant la fonction tr() de la fa�on habituelle. Par exemple :

 void MyWidget::changeEvent(QEvent *event)
 {
     if (e->type() == QEvent::LanguageChange) {
         titleLabel->setText(tr("Titre du document"));
         ...
         okPushButton->setText(tr("&OK"));
     } else
         QWidget::changeEvent(event);
 }

Tous les autres changements doivent �tre trait�s par l'appel de l'impl�mentation par d�faut de la fonction.

La liste des traducteurs install�s peut changer en r�action � un �v�nement LocaleChange et l'application peut aussi fournir une interface permettant � l'utilisateur de changer la langue courante.

Le gestionnaire d'�v�nements par d�faut pour les classes d�riv�es de QWidget r�pond � l'�v�nement QEvent::LanguageChange et appellera cette fonction si n�cessaire.

Les �v�nements LanguageChange sont post�s lorsqu'une nouvelle traduction est install�e en utilisant la fonction QCoreApplication::installTranslator(). De plus, d'autres composants de l'application peuvent forcer les widgets � se mettre � jour en leur postant des �v�nements LanguageChange.

Traduction des classes non Qt

Il est parfois n�cessaire de g�rer l'internationalisation pour des cha�nes utilis�es dans des classes ne d�rivant pas de QObject et n'utilisant pas la macro Q_OBJECT pour activer les fonctions de traduction. Comme Qt traduit les cha�nes � l'ex�cution en fonction de la classe � laquelle elle sont associ�es et que lupdate cherche les cha�nes � traduire dans le code source, les classes non Qt doivent utiliser des m�canismes fournissant �galement cette information.

Une mani�re d'activer la traduction pour une classe non Qt est d'utiliser la macro Q_DECLARE_TR_FUNCTIONS() ; par exemple :

 class MyClass
 {
     Q_DECLARE_TR_FUNCTIONS(MyClass)
 
 public:
     MyClass();
     ...
 };

Ce code fournit � la classe les fonctions tr() qui peuvent �tre utilis�es pour traduire les cha�nes associ�es � la classe, et permet � lupdate de trouver les cha�nes � traduire dans le code source.

Une alternative est d'utiliser la fonction QCoreApplication::translate() qui peut �tre appel�e avec un contexte sp�cifique, qui sera reconnu par lupdate et Qt Linguist.

Support syst�me

Certains syst�mes d'exploitation et syst�mes de fen�trage sur lesquels Qt fonctionne ont un support limit� d'Unicode. Le niveau de support disponible dans le syst�me sous-jacent influence le support que Qt peut fournir sur ces plateformes, bien qu'en g�n�ral les applications Qt ne devraient pas avoir trop � se soucier des limitations sp�cifiques aux plateformes.

Unix/X11

• Polices et m�thodes de saisie d�pendant des param�tres r�gionaux. Qt les remplace par des entr�es et sorties Unicode.
• Les conventions de syst�me de fichiers comme UTF sont en d�veloppement dans certaines variantes d'Unix. Toutes les fonctions sur les fichiers de Qt autorisent Unicode mais convertissent les noms de fichier en encodage 8 bits local, ce qui est la convention Unix (voir QFile::setEncodingFunction() pour explorer les encodages alternatifs).
• Les entr�es-sorties fichier se font par d�faut en encodage 8 bits local, avec des options Unicode dans QTextStream.
• De nombreuses distributions Unix ne contiennent qu'un support partiel de certaines options r�gionales. Par exemple, avoir un r�pertoire /usr/share/locale/ja_JP.EUC ne signifie pas forc�ment que vous pouvez afficher du texte japonais ; vous avez aussi besoin de polices encod�es en JIS (ou de polices Unicode) et le r�pertoire /usr/share/locale/ja_JP.EUC doit �tre complet. Il est conseill� d'utiliser des localisations compl�tes produites par le fournisseur du syst�me.

Windows

• Qt fournit une gestion compl�te d'Unicode, incluant les m�thodes de saisie, les polices, le presse-papier, le glisser-d�poser et les noms de fichier.
• Les entr�es-sorties fichier se font par d�faut en Latin1, avec des options Unicode dans QTextStream. Notez que certains programmes Windows ne comprennent pas les fichier texte Unicode big-endian, alors qu'il s'agit de l'ordre prescrit par le standard Unicode en l'absence de protocole de plus haut niveau.

Mac OS X

Pour les d�tails des sp�cificit�s de la traduction sur Mac OS X, voir ce document.

[ Suivant : �crire du code source pour la traduction ]

Remerciements

Merci � <!idiallo!> pour la traduction et ainsi qu'� <!dourouc!> et <!eusebe!> pour la relecture !