Translation Tutorial - Chapter 2: Two Custom Widgets

# Chapter 2: Two Custom Widgets

We will now see a more complex example, with several contexts and several texts in each context. And we'll learn what a context is.

- arrowpad.h contains the definition of ArrowPad, a custom widget;
- arrowpad.cpp contains the implementation of ArrowPad;
- mainwindow.h contains the definition of MainWindow, a QMainWindow subclass;
- mainwindow.cpp contains the implementation of MainWindow;
- main.cpp contains main().

We will provide several translations, and define "several" as meaning "two". Namely, we will provide a French and a Dutch translation. The relevant lines of tt2.pro are

        HEADERS         = arrowpad.h \
                          mainwindow.h
        SOURCES         = arrowpad.cpp \
                          main.cpp \
                          mainwindow.cpp
        TRANSLATIONS    = tt2_fr.ts \
                          tt2_nl.ts

Now run lupdate. You should get two identical message files (tt2_fr.ts and tt2_nl.ts).

## Line by Line Walk-Through

### arrowpad.h

        class ArrowPad : public QGrid
        {
            Q_OBJECT

ArrowPad is a subclass of QWidget. On the screenshot above, the central widget with the four buttons is an ArrowPad.

"ArrowPad" is also a context: It is the context of the texts in the ArrowPad class. The Q_OBJECT macro defines `tr(x)` in ArrowPad like this:

        qApp->translate( "ArrowPad", x )

Knowing which class each text occurs enables the Qt Linguist to show the right texts together, which in turn eases the translation of the program.

### arrowpad.cpp

            skip();
            (void) new QPushButton( tr("&Up"), this );
            skip();
            (void) new QPushButton( tr("&Left"), this );
            skip();
            (void) new QPushButton( tr("&Right"), this );
            skip();
            (void) new QPushButton( tr("&Down"), this );
            skip();

Here, we use ArrowPad::tr() four times.

### mainwindow.h

        class MainWindow : public QMainWindow
        {
            Q_OBJECT

In the screenshot above, the whole window is a MainWindow. Here too, we use Q_OBJECT, so that MainWindow will become a context in the Qt Linguist.

### mainwindow.cpp

        MainWindow::MainWindow( QWidget *parent, const char *name )
            : QMainWindow( parent, name )
        {
            ArrowPad *ap = new ArrowPad( this, "arrow pad" );
            setCentralWidget( ap );

In the MainWindow constructor, we create an ArrowPad.

            QPopupMenu *file = new QPopupMenu( this );
            file->insertItem( tr("E&xit"), qApp, SLOT(quit()),
                              QAccel::stringToKey(tr("Ctrl+Q")) );

Here we call MainWindow::tr() twice. Notice the use of QAccel::stringToKey() to support different keys in other languages. "Ctrl+Q" is a good choice for Quit in English, but a Dutch translator might want to use "Ctrl+A" (for Afsluiten) or a German translator "Strg+E" (for, strangely, Beenden).

### main.cpp

            QTranslator tor( 0 );
            tor.load( QString("tt2_") + QTextCodec::locale(), "." );
            a.installTranslator( &tor );

Here, we determine which translation to use according to the current locale. QTextCodec::locale() can be influenced by setting the `LANG` environment variable, among others.

## Translating to French and Dutch

Let's translate the example application to French first. Start Qt Linguist with tt2_fr.ts. You should get the seven source texts ("&Up", "&Left", etc.) grouped in two contexts ("ArrowPad" and "MainWindow").

Now, enter the following translations:

- ArrowPad
  - &Up - &Haut
  - &Left - &Gauche
  - &Right - &Droite
  - &Down - &Bas
- MainWindow
  - E&xit - &Quitter
  - Ctrl+Q - Ctrl+Q
  - &File - &Fichier

(Use the "Finish & Next" button to mark the current item as finished and to start editing an unfinished item.)

Save the file and do the same for Dutch:

- ArrodPad
  - &Up - &Boven
  - &Left - &Links
  - &Right - &Rechts
  - &Down - &Onder
- MainWindow
  - E&xit - &Afsluiten
  - Ctrl+Q - Ctrl+A
  - File - &Bestand

Now, we have to convert t1_fr.ts and t1_nl.ts into .qm files. We could use Qt Linguist for that, as in chapter one, but then we would miss an opportunity to use the lrelease utility. lrelease produces .qm files from .ts files without user interaction. It's chiefly meant for use in makefiles.

Type

        lrelease tt2.pro

You should now have both tt2_fr.qm and tt2_nl.qm. Set the `LANG` environment variable to `fr`. In Unix, one of the two following commands should do it:

        export LANG=fr
        setenv LANG fr

In Windows, either modify autoexec.bat or run

        set LANG=fr

When you run the program, you should now get

Now, try the same with Dutch, by setting `LANG=nl`. You should get

## Exercices

Remove the Q_OBJECT macro from the header files, run lupdate and look at the result in Qt Linguist. What's different now?

Set `LANG=fr_CA` (French Canada) and run the example program again. Explain why the result is the same as with `LANG=fr`.

Let's go on to chapter three.

[Previous tutorial] [Next tutorial] [Main tutorial page]