|
1 /**************************************************************************** |
|
2 ** |
|
3 ** Copyright (C) 2010 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/hellotr |
|
44 \title Hello tr() Example |
|
45 |
|
46 This example is a small Hello World program with a Latin translation. The |
|
47 screenshot below shows the English version. |
|
48 |
|
49 \image linguist-hellotr_en.png |
|
50 |
|
51 See the \l{Qt Linguist manual} for more information about |
|
52 translating Qt application. |
|
53 |
|
54 \section1 Line by Line Walkthrough |
|
55 |
|
56 |
|
57 \snippet examples/linguist/hellotr/main.cpp 0 |
|
58 |
|
59 This line includes the definition of the QTranslator class. |
|
60 Objects of this class provide translations for user-visible text. |
|
61 |
|
62 \snippet examples/linguist/hellotr/main.cpp 5 |
|
63 |
|
64 Creates a QTranslator object without a parent. |
|
65 |
|
66 \snippet examples/linguist/hellotr/main.cpp 6 |
|
67 |
|
68 Tries to load a file called \c hellotr_la.qm (the \c .qm file extension is |
|
69 implicit) that contains Latin translations for the source texts used in |
|
70 the program. No error will occur if the file is not found. |
|
71 |
|
72 \snippet examples/linguist/hellotr/main.cpp 7 |
|
73 |
|
74 Adds the translations from \c hellotr_la.qm to the pool of translations used |
|
75 by the program. |
|
76 |
|
77 \snippet examples/linguist/hellotr/main.cpp 8 |
|
78 |
|
79 Creates a push button that displays "Hello world!". If \c hellotr_la.qm |
|
80 was found and contains a translation for "Hello world!", the |
|
81 translation appears; if not, the source text appears. |
|
82 |
|
83 All classes that inherit QObject have a \c tr() function. Inside |
|
84 a member function of a QObject class, we simply write \c tr("Hello |
|
85 world!") instead of \c QPushButton::tr("Hello world!") or \c |
|
86 QObject::tr("Hello world!"). |
|
87 |
|
88 \section1 Running the Application in English |
|
89 |
|
90 Since we haven't made the translation file \c hellotr_la.qm, the source text |
|
91 is shown when we run the application: |
|
92 |
|
93 \image linguist-hellotr_en.png |
|
94 |
|
95 \section1 Creating a Latin Message File |
|
96 |
|
97 The first step is to create a project file, \c hellotr.pro, that lists |
|
98 all the source files for the project. The project file can be a qmake |
|
99 project file, or even an ordinary makefile. Any file that contains |
|
100 |
|
101 \snippet examples/linguist/hellotr/hellotr.pro 0 |
|
102 \snippet examples/linguist/hellotr/hellotr.pro 1 |
|
103 |
|
104 will work. \c TRANSLATIONS specifies the message files we want to |
|
105 maintain. In this example, we just maintain one set of translations, |
|
106 namely Latin. |
|
107 |
|
108 Note that the file extension is \c .ts, not \c .qm. The \c .ts |
|
109 translation source format is designed for use during the |
|
110 application's development. Programmers or release managers run |
|
111 the \c lupdate program to generate and update TS files with |
|
112 the source text that is extracted from the source code. |
|
113 Translators read and update the TS files using \e {Qt |
|
114 Linguist} adding and editing their translations. |
|
115 |
|
116 The TS format is human-readable XML that can be emailed directly |
|
117 and is easy to put under version control. If you edit this file |
|
118 manually, be aware that the default encoding for XML is UTF-8, not |
|
119 Latin1 (ISO 8859-1). One way to type in a Latin1 character such as |
|
120 '\oslash' (Norwegian o with slash) is to use an XML entity: |
|
121 "\ø". This will work for any Unicode 4.0 character. |
|
122 |
|
123 Once the translations are complete the \c lrelease program is used to |
|
124 convert the TS files into the QM Qt message file format. The |
|
125 QM format is a compact binary format designed to deliver very |
|
126 fast lookup performance. Both \c lupdate and \c lrelease read all the |
|
127 project's source and header files (as specified in the HEADERS and |
|
128 SOURCES lines of the project file) and extract the strings that |
|
129 appear in \c tr() function calls. |
|
130 |
|
131 \c lupdate is used to create and update the message files (\c hellotr_la.ts |
|
132 in this case) to keep them in sync with the source code. It is safe to |
|
133 run \c lupdate at any time, as \c lupdate does not remove any |
|
134 information. For example, you can put it in the makefile, so the TS |
|
135 files are updated whenever the source changes. |
|
136 |
|
137 Try running \c lupdate right now, like this: |
|
138 |
|
139 \snippet doc/src/snippets/code/doc_src_examples_hellotr.qdoc 0 |
|
140 |
|
141 (The \c -verbose option instructs \c lupdate to display messages that |
|
142 explain what it is doing.) You should now have a file \c hellotr_la.ts in |
|
143 the current directory, containing this: |
|
144 |
|
145 \snippet doc/src/snippets/code/doc_src_examples_hellotr.qdoc 1 |
|
146 |
|
147 You don't need to understand the file format since it is read and |
|
148 updated using tools (\c lupdate, \e {Qt Linguist}, \c lrelease). |
|
149 |
|
150 \section1 Translating to Latin with Qt Linguist |
|
151 |
|
152 We will use \e {Qt Linguist} to provide the translation, although |
|
153 you can use any XML or plain text editor to enter a translation into a |
|
154 TS file. |
|
155 |
|
156 To start \e {Qt Linguist}, type |
|
157 |
|
158 \snippet doc/src/snippets/code/doc_src_examples_hellotr.qdoc 2 |
|
159 |
|
160 You should now see the text "QPushButton" in the top left pane. |
|
161 Double-click it, then click on "Hello world!" and enter "Orbis, te |
|
162 saluto!" in the \gui Translation pane (the middle right of the |
|
163 window). Don't forget the exclamation mark! |
|
164 |
|
165 Click the \gui Done checkbox and choose \gui File|Save from the |
|
166 menu bar. The TS file will no longer contain |
|
167 |
|
168 \snippet doc/src/snippets/code/doc_src_examples_hellotr.qdoc 3 |
|
169 |
|
170 but instead will have |
|
171 |
|
172 \snippet doc/src/snippets/code/doc_src_examples_hellotr.qdoc 4 |
|
173 |
|
174 \section1 Running the Application in Latin |
|
175 |
|
176 To see the application running in Latin, we have to generate a QM |
|
177 file from the TS file. Generating a QM file can be achieved |
|
178 either from within \e {Qt Linguist} (for a single TS file), or |
|
179 by using the command line program \c lrelease which will produce one |
|
180 QM file for each of the TS files listed in the project file. |
|
181 Generate \c hellotr_la.qm from \c hellotr_la.ts by choosing |
|
182 \gui File|Release from \e {Qt Linguist}'s menu bar and pressing |
|
183 \gui Save in the file save dialog that pops up. Now run the \c hellotr |
|
184 program again. This time the button will be labelled "Orbis, te |
|
185 saluto!". |
|
186 |
|
187 \image linguist-hellotr_la.png |
|
188 */ |