|
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/arrowpad |
|
44 \title Arrow Pad Example |
|
45 |
|
46 This example is a slightly more involved and introduces a key \e |
|
47 {Qt Linguist} concept: "contexts". It also shows how to use two |
|
48 or more languages. |
|
49 |
|
50 \image linguist-arrowpad_en.png |
|
51 |
|
52 We will use two translations, French and Dutch, although there is no |
|
53 effective limit on the number of possible translations that can be used |
|
54 with an application. The relevant lines of \c arrowpad.pro are |
|
55 |
|
56 \snippet examples/linguist/arrowpad/arrowpad.pro 0 |
|
57 \codeline |
|
58 \snippet examples/linguist/arrowpad/arrowpad.pro 1 |
|
59 |
|
60 Run \c lupdate; it should produce two identical message files |
|
61 \c arrowpad_fr.ts and \c arrowpad_nl.ts. These files will contain all the source |
|
62 texts marked for translation with \c tr() calls and their contexts. |
|
63 |
|
64 See the \l{Qt Linguist manual} for more information about |
|
65 translating Qt application. |
|
66 |
|
67 \section1 Line by Line Walkthrough |
|
68 |
|
69 In \c arrowpad.h we define the \c ArrowPad subclass which is a |
|
70 subclass of QWidget. In the screenshot above, the central |
|
71 widget with the four buttons is an \c ArrowPad. |
|
72 |
|
73 \snippet examples/linguist/arrowpad/arrowpad.h 0 |
|
74 \snippet examples/linguist/arrowpad/arrowpad.h 1 |
|
75 \snippet examples/linguist/arrowpad/arrowpad.h 2 |
|
76 |
|
77 When \c lupdate is run it not only extracts the source texts but it |
|
78 also groups them into contexts. A context is the name of the class in |
|
79 which the source text appears. Thus, in this example, "ArrowPad" is a |
|
80 context: it is the context of the texts in the \c ArrowPad class. |
|
81 The \c Q_OBJECT macro defines \c tr(x) in \c ArrowPad like this: |
|
82 |
|
83 \snippet doc/src/snippets/code/doc_src_examples_arrowpad.qdoc 0 |
|
84 |
|
85 Knowing which class each source text appears in enables \e {Qt |
|
86 Linguist} to group texts that are logically related together, e.g. |
|
87 all the text in a dialog will have the context of the dialog's class |
|
88 name and will be shown together. This provides useful information for |
|
89 the translator since the context in which text appears may influence how |
|
90 it should be translated. For some translations keyboard |
|
91 accelerators may need to be changed and having all the source texts in a |
|
92 particular context (class) grouped together makes it easier for the |
|
93 translator to perform any accelerator changes without introducing |
|
94 conflicts. |
|
95 |
|
96 In \c arrowpad.cpp we implement the \c ArrowPad class. |
|
97 |
|
98 \snippet examples/linguist/arrowpad/arrowpad.cpp 0 |
|
99 \snippet examples/linguist/arrowpad/arrowpad.cpp 1 |
|
100 \snippet examples/linguist/arrowpad/arrowpad.cpp 2 |
|
101 \snippet examples/linguist/arrowpad/arrowpad.cpp 3 |
|
102 |
|
103 We call \c ArrowPad::tr() for each button's label since the labels are |
|
104 user-visible text. |
|
105 |
|
106 \image linguist-arrowpad_en.png |
|
107 |
|
108 \snippet examples/linguist/arrowpad/mainwindow.h 0 |
|
109 \snippet examples/linguist/arrowpad/mainwindow.h 1 |
|
110 |
|
111 In the screenshot above, the whole window is a \c MainWindow. |
|
112 This is defined in the \c mainwindow.h header file. Here too, we |
|
113 use \c Q_OBJECT, so that \c MainWindow will become a context in |
|
114 \e {Qt Linguist}. |
|
115 |
|
116 \snippet examples/linguist/arrowpad/mainwindow.cpp 0 |
|
117 |
|
118 In the implementation of \c MainWindow, \c mainwindow.cpp, we create |
|
119 an instance of our \c ArrowPad class. |
|
120 |
|
121 \snippet examples/linguist/arrowpad/mainwindow.cpp 1 |
|
122 |
|
123 We also call \c MainWindow::tr() twice, once for the action and |
|
124 once for the shortcut. |
|
125 |
|
126 Note the use of \c tr() to support different keys in other |
|
127 languages. "Ctrl+Q" is a good choice for Quit in English, but a |
|
128 Dutch translator might want to use "Ctrl+A" (for Afsluiten) and a |
|
129 German translator "Strg+E" (for Beenden). When using \c tr() for |
|
130 \key Ctrl key accelerators, the two argument form should be used |
|
131 with the second argument describing the function that the |
|
132 accelerator performs. |
|
133 |
|
134 Our \c main() function is defined in \c main.cpp as usual. |
|
135 |
|
136 \snippet examples/linguist/arrowpad/main.cpp 2 |
|
137 \snippet examples/linguist/arrowpad/main.cpp 3 |
|
138 |
|
139 We choose which translation to use according to the current locale. |
|
140 QLocale::system() can be influenced by setting the \c LANG |
|
141 environment variable, for example. Notice that the use of a naming |
|
142 convention that incorporates the locale for \c .qm message files, |
|
143 (and TS files), makes it easy to implement choosing the |
|
144 translation file according to locale. |
|
145 |
|
146 If there is no QM message file for the locale chosen the original |
|
147 source text will be used and no error raised. |
|
148 |
|
149 \section1 Translating to French and Dutch |
|
150 |
|
151 We'll begin by translating the example application into French. Start |
|
152 \e {Qt Linguist} with \c arrowpad_fr.ts. You should get the seven source |
|
153 texts ("\&Up", "\&Left", etc.) grouped in two contexts ("ArrowPad" |
|
154 and "MainWindow"). |
|
155 |
|
156 Now, enter the following translations: |
|
157 |
|
158 \list |
|
159 \o \c ArrowPad |
|
160 \list |
|
161 \o \&Up - \&Haut |
|
162 \o \&Left - \&Gauche |
|
163 \o \&Right - \&Droite |
|
164 \o \&Down - \&Bas |
|
165 \endlist |
|
166 \o \c MainWindow |
|
167 \list |
|
168 \o E\&xit - \&Quitter |
|
169 \o Ctrl+Q - Ctrl+Q |
|
170 \o \&File - \&Fichier |
|
171 \endlist |
|
172 \endlist |
|
173 |
|
174 It's quickest to press \key{Alt+D} (which clicks the \gui {Done \& Next} |
|
175 button) after typing each translation, since this marks the |
|
176 translation as done and moves on to the next source text. |
|
177 |
|
178 Save the file and do the same for Dutch working with \c arrowpad_nl.ts: |
|
179 |
|
180 \list |
|
181 \o \c ArrowPad |
|
182 \list |
|
183 \o \&Up - \&Omhoog |
|
184 \o \&Left - \&Links |
|
185 \o \&Right - \&Rechts |
|
186 \o \&Down - Omlaa\&g |
|
187 \endlist |
|
188 \o \c MainWindow |
|
189 \list |
|
190 \o E\&xit - \&Afsluiten |
|
191 \o Ctrl+Q - Ctrl+A |
|
192 \o File - \&Bestand |
|
193 \endlist |
|
194 \endlist |
|
195 |
|
196 We have to convert the \c tt1_fr.ts and \c tt1_nl.ts translation source |
|
197 files into QM files. We could use \e {Qt Linguist} as we've done |
|
198 before; however using the command line tool \c lrelease ensures that |
|
199 \e all the QM files for the application are created without us |
|
200 having to remember to load and \gui File|Release each one |
|
201 individually from \e {Qt Linguist}. |
|
202 |
|
203 Type |
|
204 |
|
205 \snippet doc/src/snippets/code/doc_src_examples_arrowpad.qdoc 1 |
|
206 |
|
207 This should create both \c arrowpad_fr.qm and \c arrowpad_nl.qm. Set the \c |
|
208 LANG environment variable to \c fr. In Unix, one of the two following |
|
209 commands should work |
|
210 |
|
211 \snippet doc/src/snippets/code/doc_src_examples_arrowpad.qdoc 2 |
|
212 |
|
213 In Windows, either modify \c autoexec.bat or run |
|
214 |
|
215 \snippet doc/src/snippets/code/doc_src_examples_arrowpad.qdoc 3 |
|
216 |
|
217 When you run the program, you should now see the French version: |
|
218 |
|
219 \image linguist-arrowpad_fr.png |
|
220 |
|
221 Try the same with Dutch, by setting \c LANG=nl. Now the Dutch |
|
222 version should appear: |
|
223 |
|
224 \image linguist-arrowpad_nl.png |
|
225 |
|
226 \section1 Exercises |
|
227 |
|
228 Mark one of the translations in \e {Qt Linguist} as not done, i.e. |
|
229 by unchecking the "done" checkbox; run \c lupdate, then \c lrelease, |
|
230 then the example. What effect did this change have? |
|
231 |
|
232 Set \c LANG=fr_CA (French Canada) and run the example program again. |
|
233 Explain why the result is the same as with \c LANG=fr. |
|
234 |
|
235 Change one of the accelerators in the Dutch translation to eliminate the |
|
236 conflict between \e \&Bestand and \e \&Boven. |
|
237 */ |