|
1 /**************************************************************************** |
|
2 ** |
|
3 ** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). |
|
4 ** All rights reserved. |
|
5 ** Contact: Nokia Corporation (qt-info@nokia.com) |
|
6 ** |
|
7 ** This file is part of the documentation of the Qt Toolkit. |
|
8 ** |
|
9 ** $QT_BEGIN_LICENSE:LGPL$ |
|
10 ** No Commercial Usage |
|
11 ** This file contains pre-release code and may not be distributed. |
|
12 ** You may use this file in accordance with the terms and conditions |
|
13 ** contained in the Technology Preview License Agreement accompanying |
|
14 ** this package. |
|
15 ** |
|
16 ** GNU Lesser General Public License Usage |
|
17 ** Alternatively, this file may be used under the terms of the GNU Lesser |
|
18 ** General Public License version 2.1 as published by the Free Software |
|
19 ** Foundation and appearing in the file LICENSE.LGPL included in the |
|
20 ** packaging of this file. Please review the following information to |
|
21 ** ensure the GNU Lesser General Public License version 2.1 requirements |
|
22 ** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. |
|
23 ** |
|
24 ** In addition, as a special exception, Nokia gives you certain additional |
|
25 ** rights. These rights are described in the Nokia Qt LGPL Exception |
|
26 ** version 1.1, included in the file LGPL_EXCEPTION.txt in this package. |
|
27 ** |
|
28 ** If you have questions regarding the use of this file, please contact |
|
29 ** Nokia at qt-info@nokia.com. |
|
30 ** |
|
31 ** |
|
32 ** |
|
33 ** |
|
34 ** |
|
35 ** |
|
36 ** |
|
37 ** |
|
38 ** $QT_END_LICENSE$ |
|
39 ** |
|
40 ****************************************************************************/ |
|
41 |
|
42 /*! |
|
43 \example linguist/trollprint |
|
44 \title Troll Print Example |
|
45 |
|
46 Troll Print is an example application that lets the user choose |
|
47 printer settings. It comes in two versions: English and |
|
48 Portuguese. |
|
49 |
|
50 \image linguist-trollprint_10_en.png |
|
51 |
|
52 We've included a translation file, \c trollprint_pt.ts, which contains some |
|
53 Portuguese translations for this example. |
|
54 |
|
55 We will consider two releases of the same application: Troll Print |
|
56 1.0 and 1.1. We will learn to reuse the translations created for one |
|
57 release in a subsequent release. (In this tutorial, you need to edit |
|
58 some source files. It's probably best to copy all the files to a new |
|
59 temporary directory and work from there.) |
|
60 |
|
61 See the \l{Qt Linguist manual} for more information about |
|
62 translating Qt application. |
|
63 |
|
64 \section1 Line by Line Walkthrough |
|
65 |
|
66 The \c PrintPanel class is defined in \c printpanel.h. |
|
67 |
|
68 \snippet examples/linguist/trollprint/printpanel.h 0 |
|
69 |
|
70 \c PrintPanel is a QWidget. It needs the \c Q_OBJECT macro for \c |
|
71 tr() to work properly. |
|
72 |
|
73 The implementation file is \c printpanel.cpp. |
|
74 |
|
75 \snippet examples/linguist/trollprint/printpanel.cpp 0 |
|
76 |
|
77 Some of the code is commented out in Troll Print 1.0; you will |
|
78 uncomment it later, for Troll Print 1.1. |
|
79 |
|
80 \snippet examples/linguist/trollprint/printpanel.cpp 1 |
|
81 \snippet examples/linguist/trollprint/printpanel.cpp 2 |
|
82 |
|
83 Notice the two occurrences of \c tr("Enabled") and of \c |
|
84 tr("Disabled") in PrintPanel. Since both "Enabled"s and "Disabled"s |
|
85 appear in the same context \e {Qt Linguist} will only display one |
|
86 occurrence of each and will use the same translations for the |
|
87 duplicates that it doesn't display. Whilst this is a useful |
|
88 timesaver, in some languages, such as Portuguese, the second |
|
89 occurrence requires a separate translation. We will see how \e {Qt |
|
90 Linguist} can be made to display all the occurrences for separate |
|
91 translation shortly. |
|
92 |
|
93 The header file for \c MainWindow, \c mainwindow.h, contains no |
|
94 surprises. In the implementation, \c mainwindow.cpp, we have some |
|
95 user-visible source texts that must be marked for translation. |
|
96 |
|
97 \snippet examples/linguist/trollprint/mainwindow.cpp 0 |
|
98 |
|
99 We must translate the window title. |
|
100 |
|
101 \snippet examples/linguist/trollprint/mainwindow.cpp 1 |
|
102 \snippet examples/linguist/trollprint/mainwindow.cpp 3 |
|
103 |
|
104 We also need to translate the actions and menus. Note that the |
|
105 two argument form of \c tr() is used for the keyboard |
|
106 accelerator, "Ctrl+Q", since the second argument is the only clue |
|
107 the translator has to indicate what function that accelerator |
|
108 will perform. |
|
109 |
|
110 \snippet examples/linguist/trollprint/main.cpp 0 |
|
111 |
|
112 The \c main() function in \c main.cpp is the same as the one in |
|
113 the \l{linguist/arrowpad}{Arrow Pad} example. In particular, it |
|
114 chooses a translation file based on the current locale. |
|
115 |
|
116 \section1 Running Troll Print 1.0 in English and in Portuguese |
|
117 |
|
118 We will use the translations in the \c trollprint_pt.ts file that is provided. |
|
119 |
|
120 Set the \c LANG environment variable to \c pt, and then run \c |
|
121 trollprint. You should still see the English version. Now run \c |
|
122 lrelease, e.g. \c {lrelease trollprint.pro}, and then run the |
|
123 example again. Now you should see the Portuguese edition (Troll |
|
124 Imprimir 1.0): |
|
125 |
|
126 \image linguist-trollprint_10_pt_bad.png |
|
127 |
|
128 Whilst the translation has appeared correctly, it is in fact wrong. In |
|
129 good Portuguese, the second occurrence of "Enabled" should be |
|
130 "Ativadas", not "Ativado" and the ending for the second translation of |
|
131 "Disabled" must change similarly too. |
|
132 |
|
133 If you open \c trollprint_pt.ts using \e {Qt Linguist}, you will see that |
|
134 there is just one occurrence of "Enabled" and of "Disabled" in the |
|
135 translation source file, even though there are two of each in the |
|
136 source code. This is because \e {Qt Linguist} tries to minimize the |
|
137 translator's work by using the same translation for duplicate source |
|
138 texts. In cases such as this where an identical translation is wrong, |
|
139 the programmer must disambiguate the duplicate occurrences. This is |
|
140 easily achieved by using the two argument form of \c tr(). |
|
141 |
|
142 We can easily determine which file must be changed because the |
|
143 translator's "context" is in fact the class name for the class where |
|
144 the texts that must be changed appears. In this case the file is \c |
|
145 printpanel.cpp, where there are four lines to change. Add the |
|
146 second argument "two-sided" in the appropriate \c tr() calls to the |
|
147 first pair of radio buttons: |
|
148 |
|
149 \snippet doc/src/snippets/code/doc_src_examples_trollprint.qdoc 0 |
|
150 |
|
151 and add the second argument "colors" in the appropriate \c tr() calls |
|
152 for the second pair of radio buttons: |
|
153 |
|
154 \snippet doc/src/snippets/code/doc_src_examples_trollprint.qdoc 1 |
|
155 |
|
156 Now run \c lupdate and open \c trollprint_pt.ts with \e {Qt Linguist}. You |
|
157 should now see two changes. |
|
158 |
|
159 First, the translation source file now contains \e three "Enabled", |
|
160 "Disabled" pairs. The first pair is marked "(obs.)" signifying that they |
|
161 are obsolete. This is because these texts appeared in \c tr() calls that |
|
162 have been replaced by new calls with two arguments. The second pair has |
|
163 "two-sided" as their comment, and the third pair has "colors" as their |
|
164 comment. The comments are shown in the \gui {Source text and comments} |
|
165 area in \e {Qt Linguist}. |
|
166 |
|
167 Second, the translation text "Ativado" and "Desativado" have been |
|
168 automatically used as translations for the new "Enabled" and "Disabled" |
|
169 texts, again to minimize the translator's work. Of course in this case |
|
170 these are not correct for the second occurrence of each word, but they |
|
171 provide a good starting point. |
|
172 |
|
173 Change the second "Ativado" into "Ativadas" and the second |
|
174 "Desativado" into "Desativadas", then save and quit. Run \c lrelease |
|
175 to obtain an up-to-date binary \c trollprint_pt.qm file, and run Troll Print |
|
176 (or rather Troll Imprimir). |
|
177 |
|
178 \image linguist-trollprint_10_pt_good.png |
|
179 |
|
180 The second argument to \c tr() calls, called "comments" in \e {Qt |
|
181 Linguist}, distinguish between identical source texts that occur in |
|
182 the same context (class). They are also useful in other cases to give |
|
183 clues to the translator, and in the case of Ctrl key accelerators are |
|
184 the only means of conveying the function performed by the accelerator to |
|
185 the translator. |
|
186 |
|
187 An additional way of helping the translator is to provide information on |
|
188 how to navigate to the particular part of the application that contains |
|
189 the source texts they must translate. This helps them see the context |
|
190 in which the translation appears and also helps them to find and test |
|
191 the translations. This can be achieved by using a \c TRANSLATOR comment |
|
192 in the source code: |
|
193 |
|
194 \snippet doc/src/snippets/code/doc_src_examples_trollprint.qdoc 2 |
|
195 |
|
196 Try adding these comments to some source files, particularly to |
|
197 dialog classes, describing the navigation necessary to reach the |
|
198 dialogs. You could also add them to the example files, e.g. \c |
|
199 mainwindow.cpp and \c printpanel.cpp are appropriate files. Run \c |
|
200 lupdate and then start \e {Qt Linguist} and load in \c trollprint_pt.ts. |
|
201 You should see the comments in the \gui {Source text and comments} area |
|
202 as you browse through the list of source texts. |
|
203 |
|
204 Sometimes, particularly with large programs, it can be difficult for |
|
205 the translator to find their translations and check that they're |
|
206 correct. Comments that provide good navigation information can save |
|
207 them time: |
|
208 |
|
209 \snippet doc/src/snippets/code/doc_src_examples_trollprint.qdoc 3 |
|
210 |
|
211 \section1 Troll Print 1.1 |
|
212 |
|
213 We'll now prepare release 1.1 of Troll Print. Start your favorite text |
|
214 editor and follow these steps: |
|
215 |
|
216 \list |
|
217 \o Uncomment the two lines that create a QLabel with the text |
|
218 "\<b\>TROLL PRINT\</b\>" in \c printpanel.cpp. |
|
219 \o Word-tidying: Replace "2-sided" by "Two-sided" in \c printpanel.cpp. |
|
220 \o Replace "1.0" with "1.1" everywhere it occurs in \c mainwindow.cpp. |
|
221 \o Update the copyright year to 1999-2000 in \c mainwindow.cpp. |
|
222 \endlist |
|
223 |
|
224 (Of course the version number and copyright year would be consts or |
|
225 #defines in a real application.) |
|
226 |
|
227 Once finished, run \c lupdate, then open \c trollprint_pt.ts in \e {Qt |
|
228 Linguist}. The following items are of special interest: |
|
229 |
|
230 \list |
|
231 \o \c MainWindow |
|
232 \list |
|
233 \o Troll Print 1.0 - marked "(obs.)", obsolete |
|
234 \o About Troll Print 1.0 - marked "(obs.)", obsolete |
|
235 \o Troll Print 1.0. Copyright 1999 Software, Inc. - |
|
236 marked obsolete |
|
237 \o Troll Print 1.1 - automatically translated as |
|
238 "Troll Imprimir 1.1" |
|
239 \o About Troll Print 1.1 - automatically translated as |
|
240 "Troll Imprimir 1.1" |
|
241 \o Troll Print 1.1. Copyright 1999-2000 Software, |
|
242 Inc. - automatically translated as "Troll Imprimir 1.1. |
|
243 Copyright 1999-2000 Software, Inc." |
|
244 \endlist |
|
245 \o \c PrintPanel |
|
246 \list |
|
247 \o 2-sided - marked "(obs.)", obsolete |
|
248 \o \<b\>TROLL PRINT\</b\> - unmarked, i.e. untranslated |
|
249 \o Two-sided - unmarked, i.e. untranslated. |
|
250 \endlist |
|
251 \endlist |
|
252 |
|
253 Notice that \c lupdate works hard behind the scenes to make revisions |
|
254 easier, and it's pretty smart with numbers. |
|
255 |
|
256 Go over the translations in \c MainWindow and mark these as "done". |
|
257 Translate "\<b\>TROLL PRINT\</b\>" as "\<b\>TROLL IMPRIMIR\</b\>". |
|
258 When you're translating "Two-sided", press the \gui {Guess Again} |
|
259 button to translate "Two-sided", but change the "2" into "Dois". |
|
260 |
|
261 Save and quit, then run \c lrelease. The Portuguese version |
|
262 should look like this: |
|
263 |
|
264 \image linguist-trollprint_11_pt.png |
|
265 |
|
266 Choose \gui{Ajuda|Sobre} (\gui{Help|About}) to see the about box. |
|
267 |
|
268 If you choose \gui {Ajuda|Sobre Qt} (\gui {Help|About Qt}), you'll get |
|
269 an English dialog. Oops! Qt itself needs to be translated. See |
|
270 \l{Internationalization with Qt} for details. |
|
271 |
|
272 Now set \c LANG=en to get the original English version: |
|
273 |
|
274 \image linguist-trollprint_11_en.png |
|
275 */ |