linguist-programmer.leaf

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

    setenv LANG fr
\endcode

\index

\index autoexec.bat
\index set!Windows Command

In Windows, either modify \c autoexec.bat or run

\code
    set LANG=fr
\endcode

When you run the program, you should now see the French version:

\img tt2_fr.png
\caption Tutorial 2 Screenshot, French version

Try the same with Dutch, by setting \c LANG=nl. Now the Dutch
version should appear:

\img tt2_nl.png
\caption Tutorial 2 Screenshot, Dutch version

\section3 Exercises

Mark one of the translations in \e {Qt Linguist} as not done, i.e.
by unchecking the "done" checkbox; run \l lupdate, then \l lrelease,
then the example. What effect did this change have?

\index Canada
\index French Canada

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.


\section2 Tutorial 3: Disambiguating Identical Strings

\img tt3_10_en.png
\caption Tutorial 3 Screenshot, "Troll Print 1.0", English version

\include tt3/tt3.pro
\caption \c tt3.pro

\index Portuguese Language
\index Brazilian Language

We've included a translation file, \c tt3_pt.ts, which contains some
Portuguese translations for this example.

\index Troll Print

We will consider two releases of the same application: Troll Print
1.0 and 1.1. We will learn to reuse the translations created for one
release in a subsequent release. (In this tutorial, you need to edit
some source files. It's probably best to copy all the files to a new
temporary directory and work from there.)

Troll Print is a toy example application that lets the user choose
printer settings. It comes in two versions: English and Portuguese.

Version 1.0 consists of these files:

\index tt3.pro
\index tt3_pt.ts

\list
\i \c printpanel.h contains the definition of PrintPanel;
\i \c printpanel.cpp contains the implementation of PrintPanel;
\i \c mainwindow.h contains the definition of \c MainWindow;
\i \c mainwindow.cpp contains the implementation of \c MainWindow;
\i \c main.cpp contains main();
\i \c tt3.pro is the \e qmake project file.
\i \c tt3_pt.ts is the Portuguese message file.
\endlist

\section3 Line by Line Walk-through

The PrintPanel is defined in \c printpanel.h.

\quotefile tt3/printpanel.h
\skipto QVBox
\printline QVBox
\printuntil Q_OBJECT

\index Q_OBJECT

\index PrintPanel!in Translation Tutorial

PrintPanel is a \l QWidget. It needs the \c Q_OBJECT macro for \c
tr() to work properly.

The implementation file is \c printpanel.cpp.

\quotefile tt3/printpanel.cpp
\skipto setSpacing
\skipto /
\printline /
\printline
\printline
\printline

\index Troll Print

Some of the code is commented out in Troll Print 1.0; you will uncomment
it later, for Troll Print 1.1.

\quotefile tt3/printpanel.cpp
\skipto twoSided
\printline twoSided
\printuntil toggle
\printline
\printuntil toggle

Notice the two occurrences of \c tr("Enabled") and of \c
tr("Disabled") in PrintPanel. Since both "Enabled"s and "Disabled"s
appear in the same context \e {Qt Linguist} will only display one
occurrence of each and will use the same translations for the
duplicates that it doesn't display. Whilst this is a useful
timesaver, in some languages, such as Portuguese, the second
occurrence requires a separate translation. We will see how \e {Qt
Linguist} can be made to display all the occurrences for separate
translation shortly.

\index MainWindow!in Translation Tutorial

The header file for \c MainWindow, \c mainwindow.h, contains no
surprises. In the implementation, \c mainwindow.cpp, we have some
user-visible source texts that must be marked for translation.

\quotefile tt3/mainwindow.cpp
\skipto setCaption
\printline setCaption

We must translate the window's caption.

\skipto quit
\printline quit
\printuntil Help

We also need to translate the menu items. Note that the two argument
form of \c tr() is used for the keyboard accelerator, "Ctrl+Q", since
the second argument is the only clue the translator has to indicate
what function that accelerator will perform.

\quotefile tt3/main.cpp
\skipto QTranslator
\printuntil installTranslator

\index main()

The \c main() function in \c main.cpp is the same as the one in \link
{Tutorial 2...} Tutorial 2 \endlink. In particular it chooses a
translation file based on the current locale.

\section3 Running Troll Print 1.0 in English and in Portuguese

We will use the translations in the \c tt3_pt.ts file that is provided.

Set the \c LANG environment variable to \c pt, and then run \c tt3. 
You should still see the English version, as shown in the \e
{Tutorial 3 Screenshot, "Troll Print 1.0", English version}, above.
Now run \l lrelease, e.g. \c {lrelease tt3.pro}, and then run the
example again. Now you should see the Portuguese edition (Troll
Imprimir 1.0):

\img tt3_10_pt_bad.png
\caption Tutorial 3 Screenshot, "Troll Imprimir 1.0", (Bad) Portuguese version

Whilst the translation has appeared correctly, it is in fact wrong. In
good Portuguese, the second occurrence of "Enabled" should be
"Ativadas", not "Ativado" and the ending for the second translation of
"Disabled" must change similarly too.

If you open \c tt3_pt.ts using \e {Qt Linguist}, you will see that
there is just one occurrence of "Enabled" and of "Disabled" in the
translation source file, even though there are two of each in the
source code. This is because \e {Qt Linguist} tries to minimize the
translator's work by using the same translation for duplicate source
texts. In cases such as this where an identical translation is wrong,
the programmer must disambiguate the duplicate occurrences. This is
easily achieved by using the two argument form of \c tr().

We can easily determine which file must be changed because the
translator's "context" is in fact the class name for the class where
the texts that must be changed appears. In this case the file is \c
printpanel.cpp, where the there are four lines to change. Add the
second argument "two-sided" in the appropriate \c tr() calls to the
first pair of radio buttons:

\code
    but = new QRadioButton( tr("Enabled", "two-sided"), twoSided );
    but = new QRadioButton( tr("Disabled", "two-sided"), twoSided );
\endcode

and add the second argument "colors" in the appropriate \c tr() calls
for the second pair of radio buttons:

\code
    but = new QRadioButton( tr("Enabled", "colors"), colors );
    but = new QRadioButton( tr("Disabled", "colors"), colors );
\endcode

\index lupdate
\index tt3_pt.ts

Now run \l lupdate and open \c tt3_pt.ts with \e {Qt Linguist}. You
should now see two changes.

First, the translation source file now contains \e three "Enabled",
"Disabled" pairs. The first pair is marked "(obs.)" signifying that they
are obsolete. This is because these texts appeared in \c tr() calls that
have been replaced by new calls with two arguments. The second pair has
"two-sided" as their comment, and the third pair has "colors" as their
comment. The comments are shown in the \e {Source text and comments}
area in \e {Qt Linguist}.

Second, the translation text "Ativado" and "Desativado" have been
automatically used as translations for the new "Enabled" and "Disabled"
texts, again to minimize the translator's work. Of course in this case
these are not correct for the second occurrence of each word, but they
provide a good starting point.

Change the second "Ativado" into "Ativadas" and the second
"Desativado" into "Desativadas", then save and quit. Run \l lrelease
to obtain an up-to-date binary \c tt3_pt.qm file, and run Troll Print
(or rather Troll Imprimir).

\img tt3_10_pt_good.png
\caption Tutorial 3 Screenshot, "Troll Imprimir 1.0", (Good) Portuguese version

\index Translator Comments
\index Comments!for Translators

The second argument to \c tr() calls, called "comments" in \e {Qt
Linguist}, distinguish between identical source texts that occur in
the same context (class). They are also useful in other cases to give
clues to the translator, and in the case of Ctrl key accelerators are
the only means of conveying the function performed by the accelerator to
the translator.

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

An additional way of helping the translator is to provide information on
how to navigate to the particular part of the application that contains
the source texts they must translate. This helps them see the context
in which the translation appears and also helps them to find and test
the translations. This can be achieved by using a \e TRANSLATOR comment
in the source code:
\code
    /* TRANSLATOR MainWindow

       In this application the whole application is a MainWindow.
       Choose Help|About from the menu bar to see some text
       belonging to MainWindow.
    */
\endcode

Try adding these comments to some source files, particularly to
dialog classes, describing the navigation necessary to reach the
dialogs. You could also add them to the example files, e.g. \c
mainwindow.cpp and \c printpanel.cpp are appropriate files. Run \l
lupdate and then start \e {Qt Linguist} and load in \c tt3_pt.ts. 
You should see the comments in the \e {Source text and comments} area
as you browse through the list of source texts.

Sometimes, particularly with large programs, it can be difficult for
the translator to find their translations and check that they're
correct. Comments that provide good navigation information can save
them time:

\code
    /* TRANSLATOR ZClientErrorDialog

	Choose Client|Edit to reach the Client Edit dialog, then choose
	Client Specification from the drop down list at the top and pick
	client Bartel Leendert van der Waerden. Now check the Profile
	checkbox and then click the Start Processing button. You should
	now see a pop up window with the text "Error: Name too long!".
	This window is a ZClientErrorDialog.
    */
\endcode


\section3 Troll Print 1.1

We'll now prepare release 1.1 of Troll Print. Start your favorite text
editor and follow these steps:

\list
\i Uncomment the two lines that create a \l QLabel with the text
     "\<b\>TROLL PRINT\</b\>" in \c printpanel.cpp.
\i Word-tidying: Replace "2-sided" by "Two-sided" in \c printpanel.cpp.
\i Replace "1.0" with "1.1" everywhere it occurs in \c mainwindow.cpp.
\i Update the copyright year to 1999-2000 in \c mainwindow.cpp.
\endlist

(Of course the version number and copyright year would be consts or
#defines in a real application.)

Once finished, run \l lupdate, then open \c tt3_pt.ts in \e {Qt
Linguist}. The following items are of special interest:

\list
\i \c MainWindow
     \list
     \i Troll Print 1.0 - marked "(obs.)", obsolete
     \i About Troll Print 1.0 - marked "(obs.)", obsolete
     \i Troll Print 1.0. Copyright 1999 Macroshaft, Inc. -
	  marked "(obs.)", obsolete
     \i Troll Print 1.1 - automatically translated as
	  "Troll Imprimir 1.1"
     \i About Troll Print 1.1 - automatically translated as
	  "Troll Imprimir 1.1"
     \i Troll Print 1.1. Copyright 1999-2000 Macroshaft,
	  Inc. - automatically translated as "Troll Imprimir 1.1.
	  Copyright 1999-2000 Macroshaft, Inc."
     \endlist
\i \c PrintPanel
     \list
     \i 2-sided - marked "(obs.)", obsolete
     \i \<b\>TROLL PRINT\</b\> - unmarked, i.e. untranslated
     \i Two-sided - unmarked, i.e. untranslated.
     \endlist
\endlist

Notice that \l lupdate works hard behind the scenes to make revisions
easier, and it's pretty smart with numbers.

Go over the translations in \c MainWindow and mark these as "done".
Translate "\<b\>TROLL PRINT\</b\>" as "\<b\>TROLL IMPRIMIR\</b\>".
When you're translating "Two-sided", press the \e {Guess Again}
button to translate "Two-sided", but change the "2" into "Dois".

Save and quit, then run \l lrelease. The Portuguese version
should look like this:

\img tt3_11_pt.png
\caption Tutorial 3 Screenshot, "Troll Imprimir 1.1", Portuguese version

Choose \e{Ajuda|Sobre}, (\e{Help|About}), to see the about box

\img tt3_11_about_pt.png
\caption Tutorial 3 Screenshot, About box, Portuguese version

\index English Language
\index Translating Qt
\index Qt!Translating Qt

If you choose \e {Ajuda|Sobre Qt}, (\e {Help|About Qt}), you'll get
an English dialog. Oops! Qt itself needs to be translated. See the
document \link i18n.html#qt-itself Internationalization with Qt
\endlink for details.

Now set \c LANG=en to get the original English version:

\img tt3_11_en.png
\caption Tutorial 3 Screenshot, "Troll Print 1.1", English version

\section2 Summary

These tutorials cover all that you need to know to prepare your Qt
applications for translation.

At the beginning of a project add the translation source files to be
used to the project file and add calls to \l lupdate and \l lrelease to
the make file.

During the project all the programmer must do is wrap any user-visible
text in \c tr() calls. They should also use the two argument form for
Ctrl key accelerators, or when asked by the translator for the cases
where the same text translates into two different forms in the same
context. The programmer should also include \e TRANSLATION comments to
help the translator navigate the application.