Chapter 1: Hello, Latin World!

The first program is a remake of the hello-world example from the Qt tutorial, with a Latin translation. The screenshot above shows the English version.

/****************************************************************
**
** Translation tutorial 1
**
****************************************************************/

#include <qapplication.h>
#include <qpushbutton.h>
#include <qtranslator.h>

int main( int argc, char **argv )
{
    QApplication a( argc, argv );

    QTranslator tor( 0 );
    tor.load( "tt1_la", "." );
    a.installTranslator( &tor );

    QPushButton hello( QPushButton::tr("Hello world!"), 0 );

    a.setMainWidget( &hello );
    hello.show();
    return a.exec();
}

Line by Line Walk-Through

    #include <qtranslator.h>

This line includes the definition of the QTranslator class. Objects of this class provide translations for user-visible text.

        QTranslator tor( 0 );

This creates a QTranslator object without a parent.

        tor.load( "tt1_la", "." );

Here, we try to load a file called tt1_la.qm (the .qm file extension is implicit) that contains Latin translations for the source texts used in the program.

        a.installTranslator( &tor );

This adds the translations from tt1_la.qm to the pool of translations used by the program.

        QPushButton hello( QPushButton::tr("Hello world!"), 0 );

This line creates a push button that displays "Hello world!". If tt1_la.qm exists and contains a translation for "Hello world!", the translation appears; if not, the source text appears.

All classes that inherit QObject have a tr() function. Inside a member function of a QObject class, we would simply write tr("Hello world!") instead of QPushButton::tr("Hello world!") or QObject::tr("Hello world!").

Running the Application in English

If you run the program now, you will obtain a big push button labelled "Hello world!". Since we still haven't made the file tt1_la.qm, the source text is shown.

Creating a Latin Message File

English is fun, but we now want to have a Latin version to please our Roman users.

The first step is to create a project file tt1.pro that lists all the source files for the project (main.cpp). The project file can be a tmake project file, or even an ordinary makefile. Any file that contains

    SOURCES         = main.cpp
    TRANSLATIONS    = tt1_la.ts

will do. TRANSLATIONS specifies the message files we want to maintain. In this example, we just maintain one set of translations, namely Latin.

Notice the file extension: It is .ts, not .qm. The .ts format (Translation Source format) is suited to developing programs and their translations, while the .qm format (Qt Message format) is much faster for running the finished application, but no good for developing it. In a nutshell, .ts files are text, much bigger than .qm, slower to read, and contain more information. Because they are text, .ts files are easy to store in version control systems and send in email.

The next step is to run the lupdate utility. It reads all the source and header files of the project (as specified by the HEADERS and SOURCES lines of the project file) and extracts the strings that appear in a tr() function call. Then it updates the message files (tt1_la.ts in this case) to keep them in synch with the source code.

You can use lupdate at any time, as lupdate does not destroy any information. For example, you can put it in the makefile, so the .ts files are updated whenever the source changes.

Try running lupdate right now, like this:

    lupdate tt1.pro

You should now have a file tt1_la.ts in the current directory, containing this:

    <!DOCTYPE TS><TS>
    <codec>iso8859-1</codec>
    <context>
        <name>QPushButton</name>
        <message>
            <source>Hello world!</source>
            <translation type='unfinished'></translation>
        </message>
    </context>
    </TS>

You don't need to understand this file. It's an XML file, which is used since XML is both extensible and easy to program for.

Translating to Latin with Qt Linguist

We will use Qt Linguist to provide the translation. (You can use any XML editor to do it, of course.)

To start Qt Linguist, type

    linguist tt1_la.ts

You should now see the text "QPushButton" on the left. Double-click on it, then click on "Hello world!" and enter "Orbis, te saluto!"in the Translation field at the right. Don't forget the exclamation mark!

Click on the Finished button and choose Save from the File menu. The .ts file now contains

            <translation>Orbis, te saluto!</translation>

instead of

            <translation type='unfinished'></translation>

Running the Application in Latin

To see the application running in Latin, we have to generate tt1_la.qm file from tt1_la.ts. In the Qt Linguist, choose Release... from the File menu. Once done, run the hello-world program again. You should see "Orbis, te saluto!" on the push button.

You may now go on to chapter two.

[Next tutorial] [Main tutorial page]