224 lines
8.1 KiB
Plaintext
224 lines
8.1 KiB
Plaintext
/****************************************************************************
|
|
**
|
|
** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
|
|
** Contact: http://www.qt-project.org/
|
|
**
|
|
** This file is part of the documentation of the Qt Toolkit.
|
|
**
|
|
** $QT_BEGIN_LICENSE:FDL$
|
|
** GNU Free Documentation License
|
|
** Alternatively, this file may be used under the terms of the GNU Free
|
|
** Documentation License version 1.3 as published by the Free Software
|
|
** Foundation and appearing in the file included in the packaging of
|
|
** this file.
|
|
**
|
|
** Other Usage
|
|
** Alternatively, this file may be used in accordance with the terms
|
|
** and conditions contained in a signed written agreement between you
|
|
** and Nokia.
|
|
**
|
|
**
|
|
**
|
|
**
|
|
**
|
|
** $QT_END_LICENSE$
|
|
**
|
|
****************************************************************************/
|
|
|
|
/*!
|
|
\example linguist/arrowpad
|
|
\title Arrow Pad Example
|
|
|
|
This example is a slightly more involved and introduces a key \e
|
|
{Qt Linguist} concept: "contexts". It also shows how to use two
|
|
or more languages.
|
|
|
|
\image linguist-arrowpad_en.png
|
|
|
|
We will use two translations, French and Dutch, although there is no
|
|
effective limit on the number of possible translations that can be used
|
|
with an application. The relevant lines of \c arrowpad.pro are
|
|
|
|
\snippet examples/linguist/arrowpad/arrowpad.pro 0
|
|
\codeline
|
|
\snippet examples/linguist/arrowpad/arrowpad.pro 1
|
|
|
|
Run \c lupdate; it should produce two identical message files
|
|
\c arrowpad_fr.ts and \c arrowpad_nl.ts. These files will contain all the source
|
|
texts marked for translation with \c tr() calls and their contexts.
|
|
|
|
See the \l{Qt Linguist manual} for more information about
|
|
translating Qt application.
|
|
|
|
\section1 Line by Line Walkthrough
|
|
|
|
In \c arrowpad.h we define the \c ArrowPad subclass which is a
|
|
subclass of QWidget. In the screenshot above, the central
|
|
widget with the four buttons is an \c ArrowPad.
|
|
|
|
\snippet examples/linguist/arrowpad/arrowpad.h 0
|
|
\snippet examples/linguist/arrowpad/arrowpad.h 1
|
|
\snippet examples/linguist/arrowpad/arrowpad.h 2
|
|
|
|
When \c lupdate is run it not only extracts the source texts but it
|
|
also groups them into contexts. A context is the name of the class in
|
|
which the source text appears. Thus, in this example, "ArrowPad" is a
|
|
context: it is the context of the texts in the \c ArrowPad class.
|
|
The \c Q_OBJECT macro defines \c tr(x) in \c ArrowPad like this:
|
|
|
|
\snippet doc/src/snippets/code/doc_src_examples_arrowpad.cpp 0
|
|
|
|
Knowing which class each source text appears in enables \e {Qt
|
|
Linguist} to group texts that are logically related together, e.g.
|
|
all the text in a dialog will have the context of the dialog's class
|
|
name and will be shown together. This provides useful information for
|
|
the translator since the context in which text appears may influence how
|
|
it should be translated. For some translations keyboard
|
|
accelerators may need to be changed and having all the source texts in a
|
|
particular context (class) grouped together makes it easier for the
|
|
translator to perform any accelerator changes without introducing
|
|
conflicts.
|
|
|
|
In \c arrowpad.cpp we implement the \c ArrowPad class.
|
|
|
|
\snippet examples/linguist/arrowpad/arrowpad.cpp 0
|
|
\snippet examples/linguist/arrowpad/arrowpad.cpp 1
|
|
\snippet examples/linguist/arrowpad/arrowpad.cpp 2
|
|
\snippet examples/linguist/arrowpad/arrowpad.cpp 3
|
|
|
|
We call \c ArrowPad::tr() for each button's label since the labels are
|
|
user-visible text.
|
|
|
|
\image linguist-arrowpad_en.png
|
|
|
|
\snippet examples/linguist/arrowpad/mainwindow.h 0
|
|
\snippet examples/linguist/arrowpad/mainwindow.h 1
|
|
|
|
In the screenshot above, the whole window is a \c MainWindow.
|
|
This is defined in the \c mainwindow.h header file. Here too, we
|
|
use \c Q_OBJECT, so that \c MainWindow will become a context in
|
|
\e {Qt Linguist}.
|
|
|
|
\snippet examples/linguist/arrowpad/mainwindow.cpp 0
|
|
|
|
In the implementation of \c MainWindow, \c mainwindow.cpp, we create
|
|
an instance of our \c ArrowPad class.
|
|
|
|
\snippet examples/linguist/arrowpad/mainwindow.cpp 1
|
|
|
|
We also call \c MainWindow::tr() twice, once for the action and
|
|
once for the shortcut.
|
|
|
|
Note the use of \c tr() 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) and a
|
|
German translator "Strg+E" (for Beenden). When using \c tr() for
|
|
\key Ctrl key accelerators, the two argument form should be used
|
|
with the second argument describing the function that the
|
|
accelerator performs.
|
|
|
|
Our \c main() function is defined in \c main.cpp as usual.
|
|
|
|
\snippet examples/linguist/arrowpad/main.cpp 2
|
|
\snippet examples/linguist/arrowpad/main.cpp 3
|
|
|
|
We choose which translation to use according to the current locale.
|
|
QLocale::system() can be influenced by setting the \c LANG
|
|
environment variable, for example. Notice that the use of a naming
|
|
convention that incorporates the locale for \c .qm message files,
|
|
(and TS files), makes it easy to implement choosing the
|
|
translation file according to locale.
|
|
|
|
If there is no QM message file for the locale chosen the original
|
|
source text will be used and no error raised.
|
|
|
|
\section1 Translating to French and Dutch
|
|
|
|
We'll begin by translating the example application into French. Start
|
|
\e {Qt Linguist} with \c arrowpad_fr.ts. You should get the seven source
|
|
texts ("\&Up", "\&Left", etc.) grouped in two contexts ("ArrowPad"
|
|
and "MainWindow").
|
|
|
|
Now, enter the following translations:
|
|
|
|
\list
|
|
\li \c ArrowPad
|
|
\list
|
|
\li \&Up - \&Haut
|
|
\li \&Left - \&Gauche
|
|
\li \&Right - \&Droite
|
|
\li \&Down - \&Bas
|
|
\endlist
|
|
\li \c MainWindow
|
|
\list
|
|
\li E\&xit - \&Quitter
|
|
\li Ctrl+Q - Ctrl+Q
|
|
\li \&File - \&Fichier
|
|
\endlist
|
|
\endlist
|
|
|
|
It's quickest to press \key{Alt+D} (which clicks the \gui {Done \& Next}
|
|
button) after typing each translation, since this marks the
|
|
translation as done and moves on to the next source text.
|
|
|
|
Save the file and do the same for Dutch working with \c arrowpad_nl.ts:
|
|
|
|
\list
|
|
\li \c ArrowPad
|
|
\list
|
|
\li \&Up - \&Omhoog
|
|
\li \&Left - \&Links
|
|
\li \&Right - \&Rechts
|
|
\li \&Down - Omlaa\&g
|
|
\endlist
|
|
\li \c MainWindow
|
|
\list
|
|
\li E\&xit - \&Afsluiten
|
|
\li Ctrl+Q - Ctrl+A
|
|
\li File - \&Bestand
|
|
\endlist
|
|
\endlist
|
|
|
|
We have to convert the \c tt1_fr.ts and \c tt1_nl.ts translation source
|
|
files into QM files. We could use \e {Qt Linguist} as we've done
|
|
before; however using the command line tool \c lrelease ensures that
|
|
\e all the QM files for the application are created without us
|
|
having to remember to load and \gui File|Release each one
|
|
individually from \e {Qt Linguist}.
|
|
|
|
Type
|
|
|
|
\snippet doc/src/snippets/code/doc_src_examples_arrowpad.qdoc 1
|
|
|
|
This should create both \c arrowpad_fr.qm and \c arrowpad_nl.qm. Set the \c
|
|
LANG environment variable to \c fr. In Unix, one of the two following
|
|
commands should work
|
|
|
|
\snippet doc/src/snippets/code/doc_src_examples_arrowpad.qdoc 2
|
|
|
|
In Windows, either modify \c autoexec.bat or run
|
|
|
|
\snippet doc/src/snippets/code/doc_src_examples_arrowpad.qdoc 3
|
|
|
|
When you run the program, you should now see the French version:
|
|
|
|
\image linguist-arrowpad_fr.png
|
|
|
|
Try the same with Dutch, by setting \c LANG=nl. Now the Dutch
|
|
version should appear:
|
|
|
|
\image linguist-arrowpad_nl.png
|
|
|
|
\section1 Exercises
|
|
|
|
Mark one of the translations in \e {Qt Linguist} as not done, i.e.
|
|
by unchecking the "done" checkbox; run \c lupdate, then \c lrelease,
|
|
then the example. What effect did this change have?
|
|
|
|
Set \c LANG=fr_CA (French Canada) and run the example program again.
|
|
Explain why the result is the same as with \c LANG=fr.
|
|
|
|
Change one of the accelerators in the Dutch translation to eliminate the
|
|
conflict between \e \&Bestand and \e \&Boven.
|
|
*/
|