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.

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)
• Greek
• Hebrew
• Thai and Lao
• All scripts in Unicode 3.2 that do not require special processing

On Windows NT/2000/XP and Unix/X11 with Xft (client side font support) the following languages are also supported:

• Bengali
• Devanagari
• Divehi (Win XP only)
• Gujarati
• Gurmukhi
• Kannada
• Khmer
• Malayalam (X11 only)
• Syriac
• Tamil
• Telugu
• Thaana
• Tibetan (X11 only)

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 Report #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 it's 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.

Step by Step

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

    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 greet_type )
    {
        static const char* greeting_strings[] = {
            QT_TR_NOOP( "Hello" ),
            QT_TR_NOOP( "Goodbye" )
        };
        return tr( greeting_strings[greet_type] );
    }

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

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

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

    QPopupMenu *file = new QPopupMenu( this );
    file->insertItem( tr("&Quit"), this, SLOT(quit()),
                      QKeySequence(tr("Ctrl+Q", "File|Quit")) );

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

    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").ascii() );
    qDebug( s2.arg(5).arg(10).arg("somefile.txt").ascii() );

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

        // translation file for Qt
        QTranslator qt( 0 );
        qt.load( QString( "qt_" ) + QTextCodec::locale(), "." );
        app.installTranslator( &qt );

        // translation file for application strings
        QTranslator myapp( 0 );
        myapp.load( QString( "myapp_" ) + QTextCodec::locale(), "." );
        app.installTranslator( &myapp );

        ...

        return app.exec();
    }

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

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

    ...; // use encoded_string in 8-bit operations

    QCString encoded_string = ...; // Some ISO 8859-5 encoded text.

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

    ...; // Use string in all of Qt's QString operations.

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