Internationalization with Qt

The internationalization of an application is the process of making the application usable by people in countries other than one's own.

• Step by Step
• Use QString for All User-Visible Text
• Use tr() for All Literal Text
• Use QKeySequence() for Accelerator Values
• Use QString::arg() for Dynamic Text
• Produce Translations
• Support for Encodings
• Localize
• Dynamic Translation
• Translating Non-Qt Classes
• System Support
• Unix/X11
• Windows
• Mac OS X
• Relevant Qt Classes

In some cases internationalization is simple, for example, making a US application accessible to Australian or British users may require little more than a few spelling corrections. But to make a US application usable by Japanese users, or a Korean application usable by German users, will require that the software operate not only in different languages, but use different input techniques, character encodings and presentation conventions.

Qt tries to make internationalization as painless as possible for developers. All input widgets and text drawing methods in Qt offer built-in support for all supported languages. The built-in font engine is capable of correctly and attractively rendering text that contains characters from a variety of different writing systems at the same time.

Qt supports most languages in use today, in particular:

• All East Asian languages (Chinese, Japanese and Korean)
• All Western languages (using Latin script)
• Arabic
• Cyrillic languages (Russian, Ukrainian, etc.)
• Greek
• Hebrew
• Thai and Lao
• All scripts in Unicode 4.0 that do not require special processing

On Windows, Unix/X11 with FontConfig (client side font support) and Qt for Embedded Linux the following languages are also supported:

• Bengali
• Devanagari
• Dhivehi (Thaana)
• Gujarati
• Gurmukhi
• Kannada
• Khmer
• Malayalam
• Myanmar
• Syriac
• Tamil
• Telugu
• Tibetan

Many of these writing systems exhibit special features:

• Special line breaking behavior. Some of the Asian languages are written without spaces between words. Line breaking can occur either after every character (with exceptions) as in Chinese, Japanese and Korean, or after logical word boundaries as in Thai.
• Bidirectional writing. Arabic and Hebrew are written from right to left, except for numbers and embedded English text which is written left to right. The exact behavior is defined in the Unicode Technical Annex #9.
• Non-spacing or diacritical marks (accents or umlauts in European languages). Some languages such as Vietnamese make extensive use of these marks and some characters can have more than one mark at the same time to clarify pronunciation.
• Ligatures. In special contexts, some pairs of characters get replaced by a combined glyph forming a ligature. Common examples are the fl and fi ligatures used in typesetting US and European books.

Qt tries to take care of all the special features listed above. You usually don't have to worry about these features so long as you use Qt's input widgets (e.g. QLineEdit, QTextEdit, and derived classes) and Qt's display widgets (e.g. QLabel).

Support for these writing systems is transparent to the programmer and completely encapsulated in Qt's text engine. This means that you don't need to have any knowledge about the writing system used in a particular language, except for the following small points:

• QPainter::drawText(int x, int y, const QString &str) will always draw the string with its left edge at the position specified with the x, y parameters. This will usually give you left aligned strings. Arabic and Hebrew application strings are usually right aligned, so for these languages use the version of drawText() that takes a QRect since this will align in accordance with the language.
• When you write your own text input controls, use QFontMetrics::charWidth() to determine the width of a character in a string. In some languages (e.g. Arabic or languages from the Indian subcontinent), the width and shape of a glyph changes depending on the surrounding characters. Writing input controls usually requires a certain knowledge of the scripts it is going to be used in. Usually the easiest way is to subclass QLineEdit or QTextEdit.

The following sections give some information on the status of the internationalization (i18n) support in Qt. See also the Qt Linguist manual.

 LoginWidget::LoginWidget()
 {
     QLabel *label = new QLabel(tr("Password:"));
     ...
 }

 void some_global_function(LoginWidget *logwid)
 {
     QLabel *label = new QLabel(
                 LoginWidget::tr("Password:"), logwid);
 }

 void same_global_function(LoginWidget *logwid)
 {
     QLabel *label = new QLabel(
                 qApp->translate("LoginWidget", "Password:"), logwid);
 }

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

 static const char *greeting_strings[] = {
     QT_TRANSLATE_NOOP("FriendlyConversation", "Hello"),
     QT_TRANSLATE_NOOP("FriendlyConversation", "Goodbye")
 };

 QString FriendlyConversation::greeting(int type)
 {
     return tr(greeting_strings[type]);
 }

 QString global_greeting(int type)
 {
     return qApp->translate("FriendlyConversation",
                            greeting_strings[type]);
 }

     exitAct = new QAction(tr("E&xit"), this);
     exitAct->setShortcut(tr("Ctrl+Q"));

 void FileCopier::showProgress(int done, int total,
                               const QString &currentFile)
 {
     label.setText(tr("%1 of %2 files copied.\nCopying: %3")
                   .arg(done)
                   .arg(total)
                   .arg(currentFile));
 }

 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");

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

 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

 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();
 }

 QString string = ...; // some Unicode text

 QTextCodec *codec = QTextCodec::codecForName("ISO 8859-5");
 QByteArray encodedString = codec->fromUnicode(string);

 QByteArray encodedString = ...; // some ISO 8859-5 encoded text

 QTextCodec *codec = QTextCodec::codecForName("ISO 8859-5");
 QString string = codec->toUnicode(encodedString);

 void Clock::setTime(const QTime &time)
 {
     if (tr("AMPM") == "AMPM") {
         // 12-hour clock
     } else {
         // 24-hour clock
     }
 }

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

 class MyClass
 {
     Q_DECLARE_TR_FUNCTIONS(MyClass)

 public:
     MyClass();
     ...
 };