linguist-programmer.leaf

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

\chapter Programmers

Support for multiple languages is extremely simple in Qt
applications, and adds little overhead to the programmer's workload.

Qt minimizes the performance cost of using translations by
translating the phrases for each window as they are created. In most
applications the main window is created just once. Dialogs are often
created once and then shown and hidden as required. Once the initial
translation has taken place there is no further runtime overhead for
the translated windows. Only those windows that are created,
destroyed and subsequently created will have a translation
performance cost.

Creating applications that can switch language at runtime is possible
with Qt, but requires a certain amount of programmer intervention and
will of course incur some runtime performance cost.

\section1 Making the Application Translation Aware

Programmers should make their application look for and load the
appropriate translation file and mark user-visible text and Ctrl
keyboard accelerators as targets for translation.

Each piece of text that requires translating requires context to help
the translator identify where in the program the text occurs. In the
case of multiple identical texts that require different translations,
the translator also requires some information to disambiguate the
source texts. Marking text for translation will automatically cause
the class name to be used as basic context information. In some cases
the programmer may be required to add additional information to help
the translator.

\section2 Creating Translation Files

\index .ts Files
\index Translation Source Files

Translation files consist of all the user-visible text and Ctrl key
accelerators in an application and translations of that text.
Translation files are created as follows:

\index lupdate
\index lrelease

\list 1
\i Run \l lupdate initially to generate the first set of \c .ts
translation source files with all the user-visible text but no
translations.
\i The \c .ts files are given to the translator who adds translations
using \e {Qt Linguist}. \e {Qt Linguist} takes care of any changed
or deleted source text.
\i Run \l lupdate to incorporate any new text added to the
application. \l lupdate synchronizes the user-visible text from the
application with the translations; it does not destroy any data.
\i Steps 2 and 3 are repeated as often as necessary.
\i When a release of the application is needed \l lrelease is run to
read the \c .ts files and produce the \c .qm files used by the
application at runtime.
\endlist

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

For \l lupdate to work successfully, it must know which translation
files to produce. The files are simply listed in the application's \c
.pro Qt project file, for example:
\quotefile  tt2/tt2.pro
\skipto TRANSLATIONS
\printline TRANSLATIONS
\printline

See the \link lupdate "lupdate" \endlink and \link lrelease
"lrelease" \endlink sections.

\section2 Loading Translations

\quotefile  tt1/main.cpp
\skipto main(
\printline main(
\printuntil QApplication

\index main()

This is how a simple \c main() function of a Qt application begins.

\index QTranslator!load()
\index load()!QTranslator
\index QApplication!installTranslator()
\index installTranslator()!QApplication

\quotefile tt1/main.cpp
\skipto main(
\printline main(
\printuntil app.installTrans

For a translation-aware application a translator object is created, a
translation is loaded and the translator object installed into the
application.

\quotefile tt2/main.cpp
\skipto main(
\printline main(
\printuntil app.installTrans

In production applications a more flexible approach, for example,
loading translations according to locale, might be more appropriate. If
the \c .ts files are all named according to a convention such as
\e appname_locale, e.g. \c tt2_fr, \c tt2_de etc, then the
code above will load the current locale's translation at runtime.

If there is no translation file for the current locale the application
will fall back to using the original source text.

\section2 Making the Application Translate User-Visible Strings

\index tr()
\index QObject!tr()

User-visible strings are marked as translation targets by wrapping them
in a \c tr() call, for example:
\code
    button = new QPushButton( "&Quit", this );
\endcode

would become

\code
    button = new QPushButton( tr("&Quit"), this);
\endcode

\index Q_OBJECT

All \l QObject subclasses that use the \c Q_OBJECT macro implement
the \c tr() function.

Although the \c tr() call is normally made directly since it is
usually called as a member function of a \l QObject subclass, in
other cases an explicit class name can be supplied, for example:

\code
    QPushButton::tr("&Quit")
\endcode

or

\code
    QObject::tr("&Quit")
\endcode

\section2 Distinguishing Identical Strings That Require Different
Translations

\index Translation Contexts
\index Contexts!for Translation
\index lupdate

The \l lupdate program automatically provides a \e context for every
source text. This context is the class name of the class that contains
the \c tr() call. This is sufficient in the vast majority of cases.
Sometimes however, the translator will need further information to
uniquely identify a source text; for example, a dialog that contained
two separate frames, each of which contained an "Enabled" option would
need each identified because in some languages the translation would
differ between the two. This is easily achieved using the
two argument form of the \c tr() call, e.g.

\code
    rbc = new QRadioButton( tr("Enabled", "Color frame"), this );
\endcode

and

\code
    rbh = new QRadioButton( tr("Enabled", "Hue frame"), this );
\endcode

\index Ctrl Key

Ctrl key accelerators are also translatable:

\quotefile tt3/mainwindow.cpp
\skipto quit()
\printline quit()
\printuntil Quit

It is strongly recommended that the two argument form of \c tr() is used
for Ctrl key accelerators. The second argument is the only clue the
translator has as to the function performed by the accelerator.

\section2 Helping The Translator With Navigation Information

\index TRANSLATOR!in Comments
\index Translator Comments
\index Comments!for Translators

In large complex applications it may be difficult for the translator to
see where a particular source text comes from. This problem can be
solved by adding a comment using the keyword \e TRANSLATOR which
describes the navigation steps to reach the text in question; e.g.

\code
    /*  TRANSLATOR FindDialog

	Choose Edit|Find from the menu bar or press Ctrl+F to pop up the
	Find dialog.
    */
\endcode

These comments are particularly useful for widget classes.

\section2 Coping With C++ Namespaces

\index Namespaces
\index C++!Namespaces
\index lupdate

C++ namespaces and the \c {using namespace} statement can confuse
\l lupdate. It will interpret \c MyClass::tr() as meaning just
that, not as \c MyNamespace::MyClass::tr(), even if \c MyClass is
defined in the \c MyNamespace namespace. Runtime translation of
these strings will fail because of that.

\index TRANSLATOR!in Comments
\index Translator Comments
\index Comments!for Translators

You can work around this limitation by putting a \e TRANSLATOR
comment at the beginning of the source files that use \c
MyClass::tr():
\code
    /* TRANSLATOR MyNamespace::MyClass */
\endcode
After the comment, all references to \c MyClass::tr() will be
understood as meaning \c MyNamespace::MyClass::tr().

\section2 Translating Text that is Outside of a QObject subclass

\section3 Using QApplication::translate()

If the quoted text is not in a member function of a QObject subclass,
use either the tr() function of an appropriate class, or the
QApplication::translate() function directly: 

\code
    void some_global_function( LoginWidget *logwid )
    {
        QLabel *label = new QLabel(
                LoginWidget::tr("Password:"), logwid );
    }

    void same_global_function( LoginWidget *logwid )
    {
        QLabel *label = new QLabel(
                qApp->translate("LoginWidget", "Password:"),
                logwid );
    }
\endcode

\section3 Using QT_TR_NOOP() and QT_TRANSLATE_NOOP()

If you need to have translatable text completely outside a function,
there are two macros to help: QT_TR_NOOP() and QT_TRANSLATE_NOOP().
These macros merely mark the text for extraction by \l{lupdate}.
The macros expand to just the text (without the context). 

Example of QT_TR_NOOP(): 
\code
    QString FriendlyConversation::greeting( int greet_type )
    {
        static const char* greeting_strings[] = {
            QT_TR_NOOP( "Hello" ),
            QT_TR_NOOP( "Goodbye" )
        };
        return tr( greeting_strings[greet_type] );
    }
\endcode

Example of QT_TRANSLATE_NOOP(): 
\code
    static const char* greeting_strings[] = {
        QT_TRANSLATE_NOOP( "FriendlyConversation", "Hello" ),
        QT_TRANSLATE_NOOP( "FriendlyConversation", "Goodbye" )
    };

    QString FriendlyConversation::greeting( int greet_type )
    {
        return tr( greeting_strings[greet_type] );
    }

    QString global_greeting( int greet_type )
    {
        return qApp->translate( "FriendlyConversation",
                                greeting_strings[greet_type] );
    }
\endcode

\section1 Tutorials

Three tutorials are presented. The first demonstrates the creation of
a \l QTranslator object. It also shows the simplest use of the \c
tr() function to mark user-visible source text for translation. The
second tutorial explains how to make the application load the
translation file applicable to the current locale. It also shows the
use of the two-argument form of \c tr() which provides additional
information to the translator. The third tutorial explains how
identical source texts can be distinguished even when they occur in
the same context. This tutorial also discusses how the translation
tools help minimize the translator's work when an application is
upgraded.

\section2 Tutorial 1: Loading and Using Translations

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

\include tt1/tt1.pro
\caption \c tt1.pro

\include tt1/main.cpp
\caption \c main.cpp

This example is a reworking of the \link tutorial1-01.html
"hello-world" \endlink example from \link tutorial.html Tutorial
#1\endlink, with a Latin translation. The \e {Tutorial 1 Screenshot,
English version}, above, shows the English version.

\quotefile tt1/main.cpp

\section3 Line by Line Walk-through

\quotefile tt1/main.cpp

\skipto qtranslator
\printline qtranslator

\index QTranslator

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

\skipto QTranslator
\printuntil tor

Creates a \l QTranslator object without a parent.

\printline load

\index tt1_la.qm

Tries to load a file called \c tt1_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.

\index QApplication!installTranslator()
\index installTranslator()!QApplication

\printline installTranslator

Adds the translations from \c tt1_la.qm to the pool of translations used
by the program.

\index Hello World

\printline hello

Creates a push button that displays "Hello world!". If \c tt1_la.qm
was found and contains a translation for "Hello world!", the
translation appears; if not, the source text appears.

\index tr()
\index QObject!tr()

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

\section3 Running the Application in English

\index English Language