1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
|
/****************************************************************************
**
** Copyright (C) 2015 The Qt Company Ltd.
** Contact: http://www.qt.io/licensing/
**
** This file is part of the documentation of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:FDL$
** Commercial License Usage
** Licensees holding valid commercial Qt licenses may use this file in
** accordance with the commercial license agreement provided with the
** Software or, alternatively, in accordance with the terms contained in
** a written agreement between you and The Qt Company. For licensing terms
** and conditions see http://www.qt.io/terms-conditions. For further
** information use the contact form at http://www.qt.io/contact-us.
**
** GNU Free Documentation License Usage
** 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. Please review the following information to ensure
** the GNU Free Documentation License version 1.3 requirements
** will be met: http://www.gnu.org/copyleft/fdl.html.
** $QT_END_LICENSE$
**
****************************************************************************/
/*!
\example linguist/trollprint
\title Troll Print Example
\brief Troll Print is an example application that lets the user choose
printer settings. It comes in two versions: English and
Portuguese.
\image linguist-trollprint_10_en.png
We've included a translation file, \c trollprint_pt.ts, which contains some
Portuguese translations for this example.
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.)
See the \l{Qt Linguist manual} for more information about
translating Qt application.
\section1 Line by Line Walkthrough
The \c PrintPanel class is defined in \c printpanel.h.
\snippet examples/linguist/trollprint/printpanel.h 0
\c PrintPanel is a QWidget. It needs the \c Q_OBJECT macro for \c
tr() to work properly.
The implementation file is \c printpanel.cpp.
\snippet examples/linguist/trollprint/printpanel.cpp 0
Some of the code is commented out in Troll Print 1.0; you will
uncomment it later, for Troll Print 1.1.
\snippet examples/linguist/trollprint/printpanel.cpp 1
\snippet examples/linguist/trollprint/printpanel.cpp 2
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.
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.
\snippet examples/linguist/trollprint/mainwindow.cpp 0
We must translate the window title.
\snippet examples/linguist/trollprint/mainwindow.cpp 1
\snippet examples/linguist/trollprint/mainwindow.cpp 3
We also need to translate the actions and menus. 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.
\snippet examples/linguist/trollprint/main.cpp 0
The \c main() function in \c main.cpp is the same as the one in
the \l{linguist/arrowpad}{Arrow Pad} example. In particular, it
chooses a translation file based on the current locale.
\section1 Running Troll Print 1.0 in English and in Portuguese
We will use the translations in the \c trollprint_pt.ts file that is provided.
Set the \c LANG environment variable to \c pt, and then run \c
trollprint. You should still see the English version. Now run \c
lrelease, e.g. \c {lrelease trollprint.pro}, and then run the
example again. Now you should see the Portuguese edition (Troll
Imprimir 1.0):
\image linguist-trollprint_10_pt_bad.png
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 trollprint_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 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:
\snippet doc/src/snippets/code/doc_src_examples_trollprint.cpp 0
and add the second argument "colors" in the appropriate \c tr() calls
for the second pair of radio buttons:
\snippet doc/src/snippets/code/doc_src_examples_trollprint.cpp 1
Now run \c lupdate and open \c trollprint_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 \gui {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 \c lrelease
to obtain an up-to-date binary \c trollprint_pt.qm file, and run Troll Print
(or rather Troll Imprimir).
\image linguist-trollprint_10_pt_good.png
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.
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 \c TRANSLATOR comment
in the source code:
\snippet doc/src/snippets/code/doc_src_examples_trollprint.cpp 2
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 \c
lupdate and then start \e {Qt Linguist} and load in \c trollprint_pt.ts.
You should see the comments in the \gui {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:
\snippet doc/src/snippets/code/doc_src_examples_trollprint.cpp 3
\section1 Troll Print 1.1
We'll now prepare release 1.1 of Troll Print. Start your favorite text
editor and follow these steps:
\list
\o Uncomment the two lines that create a QLabel with the text
"\<b\>TROLL PRINT\</b\>" in \c printpanel.cpp.
\o Word-tidying: Replace "2-sided" by "Two-sided" in \c printpanel.cpp.
\o Replace "1.0" with "1.1" everywhere it occurs in \c mainwindow.cpp.
\o 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 \c lupdate, then open \c trollprint_pt.ts in \e {Qt
Linguist}. The following items are of special interest:
\list
\o \c MainWindow
\list
\o Troll Print 1.0 - marked "(obs.)", obsolete
\o About Troll Print 1.0 - marked "(obs.)", obsolete
\o Troll Print 1.0. Copyright 1999 Software, Inc. -
marked obsolete
\o Troll Print 1.1 - automatically translated as
"Troll Imprimir 1.1"
\o About Troll Print 1.1 - automatically translated as
"Troll Imprimir 1.1"
\o Troll Print 1.1. Copyright 1999-2000 Software,
Inc. - automatically translated as "Troll Imprimir 1.1.
Copyright 1999-2000 Software, Inc."
\endlist
\o \c PrintPanel
\list
\o 2-sided - marked "(obs.)", obsolete
\o \<b\>TROLL PRINT\</b\> - unmarked, i.e. untranslated
\o Two-sided - unmarked, i.e. untranslated.
\endlist
\endlist
Notice that \c 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 \gui {Guess Again}
button to translate "Two-sided", but change the "2" into "Dois".
Save and quit, then run \c lrelease. The Portuguese version
should look like this:
\image linguist-trollprint_11_pt.png
Choose \gui{Ajuda|Sobre} (\gui{Help|About}) to see the about box.
If you choose \gui {Ajuda|Sobre Qt} (\gui {Help|About Qt}), you'll get
an English dialog. Oops! Qt itself needs to be translated. See
\l{Internationalization with Qt} for details.
Now set \c LANG=en to get the original English version:
\image linguist-trollprint_11_en.png
*/
|
