source: trunk/doc/src/examples/hellotr.qdoc

Last change on this file was 846, checked in by Dmitry A. Kuminov, 14 years ago

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