175 lines
6.7 KiB
Plaintext
175 lines
6.7 KiB
Plaintext
/****************************************************************************
|
|
**
|
|
** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies).
|
|
** All rights reserved.
|
|
** Contact: Nokia Corporation (qt-info@nokia.com)
|
|
**
|
|
** 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/hellotr
|
|
\title Hello tr() Example
|
|
|
|
This example is a small Hello World program with a Latin translation. The
|
|
screenshot below shows the English version.
|
|
|
|
\image linguist-hellotr_en.png
|
|
|
|
See the \l{Qt Linguist manual} for more information about
|
|
translating Qt application.
|
|
|
|
\section1 Line by Line Walkthrough
|
|
|
|
|
|
\snippet examples/linguist/hellotr/main.cpp 0
|
|
|
|
This line includes the definition of the QTranslator class.
|
|
Objects of this class provide translations for user-visible text.
|
|
|
|
\snippet examples/linguist/hellotr/main.cpp 5
|
|
|
|
Creates a QTranslator object without a parent.
|
|
|
|
\snippet examples/linguist/hellotr/main.cpp 6
|
|
|
|
Tries to load a file called \c hellotr_la.qm (the \c .qm file extension is
|
|
implicit) that contains Latin translations for the source texts used in
|
|
the program. No error will occur if the file is not found.
|
|
|
|
\snippet examples/linguist/hellotr/main.cpp 7
|
|
|
|
Adds the translations from \c hellotr_la.qm to the pool of translations used
|
|
by the program.
|
|
|
|
\snippet examples/linguist/hellotr/main.cpp 8
|
|
|
|
Creates a push button that displays "Hello world!". If \c hellotr_la.qm
|
|
was found and contains a translation for "Hello world!", the
|
|
translation appears; if not, the source text appears.
|
|
|
|
All classes that inherit QObject have a \c tr() function. Inside
|
|
a member function of a QObject class, we simply write \c tr("Hello
|
|
world!") instead of \c QPushButton::tr("Hello world!") or \c
|
|
QObject::tr("Hello world!").
|
|
|
|
\section1 Running the Application in English
|
|
|
|
Since we haven't made the translation file \c hellotr_la.qm, the source text
|
|
is shown when we run the application:
|
|
|
|
\image linguist-hellotr_en.png
|
|
|
|
\section1 Creating a Latin Message File
|
|
|
|
The first step is to create a project file, \c hellotr.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
|
|
|
|
\snippet examples/linguist/hellotr/hellotr.pro 0
|
|
\snippet examples/linguist/hellotr/hellotr.pro 1
|
|
|
|
will work. \c TRANSLATIONS specifies the message files we want to
|
|
maintain. In this example, we just maintain one set of translations,
|
|
namely Latin.
|
|
|
|
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 \c lupdate program to generate and update TS files with
|
|
the source text that is extracted from the source code.
|
|
Translators read and update the TS files using \e {Qt
|
|
Linguist} adding and editing their translations.
|
|
|
|
The 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
|
|
Latin1 (ISO 8859-1). One way to type in a Latin1 character such as
|
|
'\oslash' (Norwegian o with slash) is to use an XML entity:
|
|
"\ø". This will work for any Unicode 4.0 character.
|
|
|
|
Once the translations are complete the \c lrelease program is used to
|
|
convert the TS files into the QM Qt message file format. The
|
|
QM format is a compact binary format designed to deliver very
|
|
fast lookup performance. Both \c lupdate and \c 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.
|
|
|
|
\c lupdate is used to create and update the message files (\c hellotr_la.ts
|
|
in this case) to keep them in sync with the source code. It is safe to
|
|
run \c lupdate at any time, as \c lupdate does not remove any
|
|
information. For example, you can put it in the makefile, so the TS
|
|
files are updated whenever the source changes.
|
|
|
|
Try running \c lupdate right now, like this:
|
|
|
|
\snippet doc/src/snippets/code/doc_src_examples_hellotr.qdoc 0
|
|
|
|
(The \c -verbose option instructs \c lupdate to display messages that
|
|
explain what it is doing.) You should now have a file \c hellotr_la.ts in
|
|
the current directory, containing this:
|
|
|
|
\snippet doc/src/snippets/code/doc_src_examples_hellotr.qdoc 1
|
|
|
|
You don't need to understand the file format since it is read and
|
|
updated using tools (\c lupdate, \e {Qt Linguist}, \c lrelease).
|
|
|
|
\section1 Translating to Latin with Qt 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
|
|
TS file.
|
|
|
|
To start \e {Qt Linguist}, type
|
|
|
|
\snippet doc/src/snippets/code/doc_src_examples_hellotr.qdoc 2
|
|
|
|
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 \gui Translation pane (the middle right of the
|
|
window). Don't forget the exclamation mark!
|
|
|
|
Click the \gui Done checkbox and choose \gui File|Save from the
|
|
menu bar. The TS file will no longer contain
|
|
|
|
\snippet doc/src/snippets/code/doc_src_examples_hellotr.qdoc 3
|
|
|
|
but instead will have
|
|
|
|
\snippet doc/src/snippets/code/doc_src_examples_hellotr.qdoc 4
|
|
|
|
\section1 Running the Application in Latin
|
|
|
|
To see the application running in Latin, we have to generate a QM
|
|
file from the TS file. Generating a QM file can be achieved
|
|
either from within \e {Qt Linguist} (for a single TS file), or
|
|
by using the command line program \c lrelease which will produce one
|
|
QM file for each of the TS files listed in the project file.
|
|
Generate \c hellotr_la.qm from \c hellotr_la.ts by choosing
|
|
\gui File|Release from \e {Qt Linguist}'s menu bar and pressing
|
|
\gui Save in the file save dialog that pops up. Now run the \c hellotr
|
|
program again. This time the button will be labelled "Orbis, te
|
|
saluto!".
|
|
|
|
\image linguist-hellotr_la.png
|
|
*/
|