linguist-programmer.leaf

Linux下的基于X11的图形开发环境。

Since we haven't made the translation file \c tt1_la.qm, the source text
is shown when we run the application:

\img tt1_en.png
\caption Tutorial 1 Screenshot, English version

\section3 Creating a Latin Message File

\index tt1.pro
\index Latin

The first step is to create a project file, \c tt1.pro, that lists
all the source files for the project. The project file can be a qmake
project file, or even an ordinary makefile. Any file that contains

\index SOURCES!in Project Files
\index TRANSLATIONS!in Project Files

\quotefile tt1/tt1.pro
\skipto SOURCES
\printline SOURCES
\skipto TRANSLATIONS
\printline TRANSLATIONS

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

\index .ts Files
\index Translation Source Files
\index .qm Files
\index Qt Message Files

Note that the file extension is \c .ts, not \c .qm. The \c .ts
translation source format is designed for use during the
application's development. Programmers or release managers run the \l
lupdate program to generate and update \c .ts files with the source
text that is extracted from the source code. Translators read and
update the \c .ts files using \e {Qt Linguist} adding and editing
their translations.

\index XML

The \c .ts format is human-readable XML that can be emailed directly
and is easy to put under version control. If you edit this file
manually, be aware that the default encoding for XML is UTF-8, not
Latin-1 (ISO 8859-1). One way to type in a Latin-1 character such as
'\OSLASH' (Norwegian o with slash) is to use an XML entity:
"\ø". This will work for any Unicode character.

Once the translations are complete the \l lrelease program is used to
convert the \c .ts files into the \c .qm Qt message file format. The
\c .qm format is a compact binary format designed to deliver very
fast lookup performance. Both \l lupdate and \l lrelease read all the
project's source and header files (as specified in the HEADERS and
SOURCES lines of the project file) and extract the strings that
appear in \c tr() function calls.

\index lupdate

\l lupdate is used to create and update the message files (\c tt1_la.ts
in this case) to keep them in sync with the source code. It is safe to
run \l lupdate at any time, as \l lupdate does not remove any
information. For example, you can put it in the makefile, so the \c .ts
files are updated whenever the source changes.

\index .ts Files
\index Translation Source Files
\index XML

Try running \l lupdate right now, like this:
\code
    lupdate -verbose tt1.pro
\endcode
(The \c -verbose option instructs \c lupdate to display messages that
explain what it is doing.) You should now have a file \c tt1_la.ts in
the current directory, containing this:
\code
    <!DOCTYPE TS><TS>
    <context>
        <name>QPushButton</name>
        <message>
            <source>Hello world!</source>
            <translation type="unfinished"></translation>
        </message>
    </context>
    </TS>
\endcode
You don't need to understand the file format since it is read and
updated using tools (\l lupdate, \e {Qt Linguist}, \l lrelease).

\section3 Translating to Latin with Qt Linguist

\index Qt Linguist
\index Linguist

We will use \e {Qt Linguist} to provide the translation, although
you can use any XML or plain text editor to enter a translation into a
\c .ts file.

To start \e {Qt Linguist}, type
\code
    linguist tt1_la.ts
\endcode

You should now see the text "QPushButton" in the top left pane.
Double-click it, then click on "Hello world!" and enter "Orbis, te
saluto!" in the \e Translation pane (the middle right of the
window). Don't forget the exclamation mark!

Click the \e Done checkbox and choose \e File|Save from the
menu bar. The \c .ts file will no longer contain
\code
    <translation type='unfinished'></translation>
\endcode
but instead will have
\code
    <translation>Orbis, te saluto!</translation>
\endcode

\section3 Running the Application in Latin

\index Latin
\index lrelease

To see the application running in Latin, we have to generate a \c .qm
file from the \c .ts file. Generating a \c .qm file can be achieved
either from within \e {Qt Linguist} (for a single \c .ts file), or
by using the command line program \l lrelease which will produce one \c
.qm file for each of the \c .ts files listed in the project file.
Generate \c tt1_la.qm from \c tt1_la.ts by choosing
\e File|Release from \e {Qt Linguist}'s menu bar and pressing
\e Save in the file save dialog that pops up. Now run the \e tt1 example
program again. This time the button will be labelled "Orbis, te
saluto!".

\img tt1_la.png
\caption Tutorial 1 Screenshot, Latin version

\section2 Tutorial 2: Using Two or More Languages

\img tt2_en.png
\caption Tutorial 2 Screenshot, English version

\index .pro Files
\index Project Files
\index qmake!Project Files

\include tt2/tt2.pro
\caption tt2.pro

\index Translation Contexts
\index Contexts!for Translation

This example is a slightly more involved and introduces a key
\e {Qt Linguist} concept: "contexts".

\list
\i \c arrowpad.h contains the definition of \c ArrowPad, a custom widget;
\i \c arrowpad.cpp contains the implementation of \c ArrowPad;
\i \c mainwindow.h contains the definition of \c MainWindow, a subclass of
   \l QMainWindow
\i \c mainwindow.cpp contains the implementation of \c MainWindow;
\i \c main.cpp contains main().
\endlist

\index tt2.pro
\index French Language
\index Dutch Language

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 tt2.pro are

\quotefile tt2/tt2.pro
\skipto HEADERS
\printuntil tt2_nl.ts

\index lupdate
\index tt2_fr.ts
\index tt2_nl.ts

Run \l lupdate; it should produce two identical message files
\c tt2_fr.ts and \c tt2_nl.ts. These files will contain all the source
texts marked for translation with \c tr() calls and their contexts.

\section3 Line by Line Walk-through

\index ArrowPad!in Translation Tutorial
\index English Language

In \c arrowpad.h we define the \c ArrowPad subclass which is a
subclass of \l QWidget. In the \e {Tutorial 2 Screenshot, English
version}, above, the central widget with the four buttons is an
\c ArrowPad.

\quotefile tt2/arrowpad.h
\skipto class ArrowPad
\printline class ArrowPad

\index Q_OBJECT
\index tr()
\index QObject!tr()
\index Translation Contexts
\index Contexts!for Translation

When \l 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

\index QApplication!translate()
\index translate()!QApplication

\code
    qApp->translate( "ArrowPad", x )
\endcode

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.

\quotefile tt2/arrowpad.cpp
\skipto QPushButton
\printline QPushButton

We call \c ArrowPad::tr() for each button's label since the labels are
user-visible text.

\img tt2_en.png
\caption Tutorial 2 Screenshot, English version

\index Q_OBJECT
\index MainWindow!in Translation Tutorial

\quotefile tt2/mainwindow.h
\skipto QMainWindow
\printline QMainWindow
\printuntil Q_OBJECT

In the \e {Tutorial 2 Screenshot, English version}, 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}.

In the implementation of \c MainWindow, \c mainwindow.cpp, we create
an instance of our \c ArrowPad class

\quotefile tt2/mainwindow.cpp
\skipto arrow pad
\printline arrow pad

We also call \c MainWindow::tr() twice, once for the menu item and
once for the accelerator.

\index Ctrl Key
\index Alt Key

\skipto quit()
\printline quit()
\printuntil Ctrl+Q

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 Ctrl key accelerators,
the two argument form should be used with the second argument
describing the function that the accelerator performs.

\index main()

Our \c main() function is defined in \c main.cpp as usual.

\quotefile tt2/main.cpp
\skipto QTranslator
\printline QTranslator
\printuntil install

\index QTextCodec!locale()
\index locale()!QTextCodec
\index LANG!Environment Variable
\index Environment Variables!LANG

We choose which translation to use according to the current locale.
\l QTextCodec::locale() 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 \c .ts files), makes it easy to implement choosing the
translation file according to locale.

If there is no \c .qm message file for the locale chosen the original
source text will be used and no error raised.

\section3 Translating to French and Dutch

We'll begin by translating the example application into French. Start
\e {Qt Linguist} with \c 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:

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

It's quickest to press \Key Alt+D (which clicks the \e {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 tt2_nl.ts:

\list
\i \c ArrowPad
     \list
     \i \&Up - \&Boven
     \i \&Left - \&Links
     \i \&Right - \&Rechts
     \i \&Down - \&Onder
     \endlist
\i \c MainWindow
     \list
     \i E\&xit - \&Afsluiten
     \i Ctrl+Q - Ctrl+A
     \i File - \&Bestand
     \endlist
\endlist

We have to convert the \c tt1_fr.ts and \c tt1_nl.ts translation source
files into \c .qm files. We could use \e {Qt Linguist} as we've done
before; however using the command line tool \l lrelease ensures that
\e all the \c .qm files for the application are created without us
having to remember to load and \e File|Release each one
individually from \e {Qt Linguist}.

In practice we would include calls to \l lupdate and \l lrelease in the
application's makefile to ensure that the latest translations are
used.

\omit
an example of a makefile or .pro file that did this would be nice
\endomit

Type

\code
    lrelease tt2.pro
\endcode

\index LANG!Environment Variable
\index export!Unix Command
\index setenv!Unix Command

This should create both \c tt2_fr.qm and \c tt2_nl.qm. Set the \c
LANG environment variable to \c fr. In Unix, one of the two following
commands should work

\code
    export LANG=fr