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
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
|
/****************************************************************************
**
** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies).
** Contact: http://www.qt-project.org/legal
**
** 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 Digia. For licensing terms and
** conditions see http://qt.digia.com/licensing. For further information
** use the contact form at http://qt.digia.com/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$
**
****************************************************************************/
/*!
\page qtquick-internationalization.html howto
\ingroup qml-features
\title Internationalization and Localization with Qt Quick
\brief Following these steps, you can write your Qt Quick application so it can be localized for multiple languages
\section1 Internationalizing your Application
The following sections describe various aspects of internationalizing your QML
source code. If you follow these guides for all the user interface elements in
your application, it becomes possible to localize every aspect of your
application for different languages and local cultural conventions such as the
way dates and numbers are formatted.
\section2 1. Use qsTr() for all Literal User Interface Strings
Strings in QML can be marked for translation using the qsTr(), qsTranslate(),
qsTrId(), QT_TR_NOOP(), QT_TRANSLATE_NOOP(), and QT_TRID_NOOP() functions. The
most common way of marking strings is with the qsTr() function. For example:
\code
Text {
id: txt1;
text: qsTr("Back");
}
\endcode
This code makes "Back" a key entry in the translation files. At runtime, the
translation system looks up the keyword "Back" and then gets the corresponding
translation value for the current system locale. The result is returned to the
\c text property and the user interface will show the appropriate translation of
"Back" for the current locale.
\section2 2. Add Context for the Translator
User interface strings are often short so you need to help the person
translating the text understand the context of the text. You can add context
information in the source code as extra descriptive text before the string to be
translated. These extra descriptions are included in the .ts translation files
delivered to the translator.
\note The .ts files are XML files with the source texts and a place for the
translated text. The updated .ts files are converted into binary translation
files and included as part of the final application.
In the following code snippet, the text on the \c {//:} line is the main comment
for the translator.
The text on the \c{//~} line is optional extra information. The first word of
the text is used as an additional identifier in the XML element in the .ts file
so make sure the first word is not part of the sentence. For example, the
comment "Context Not related to that" is converted to "<extra-Context>Not
related to that" in the .ts file.
\code
Text {
id: txt1;
// This user interface string is only used here
//: The back of the object, not the front
//~ Context Not related to back-stepping
text: qsTr("Back");
}
\endcode
\section2 3. Disambiguate Identical Texts
The translation system consolidates the user interface text strings into unique
items. This consolidation saves the person doing the translation work having to
translate the same text multiple times. However, in some cases, the text is
identical but has a different meaning. For example, in English, "back" means
take a step backward and also means the part of an object opposite to the front.
You need to tell the translation system about these two separate meanings so the
translator can create two separate translations.
Differentiate between identical texts by adding some id text as the second
parameter of the qsTr() function.
In the following code snippet, the \c {not front} text is an id to differentiate
this "Back" text from the backstepping "Back" text:
\code
Text {
id: txt1;
// This user interface string is used only here
//: The back of the object, not the front
//~ Context Not related to back-stepping
text: qsTr("Back", "not front");
}
\endcode
\section2 4. Use \c %x to Insert Parameters into a String
Different languages put words together in different orders so it is not a good
idea to create sentences by concatenating words and data. Instead, use \c % to
insert parameters into strings. For example, the following snippet has a string
with two number parameters \c %1 and \c %2. These parameters are inserted with
the \c .arg() functions.
\code
Text {
text: qsTr("File %1 of %2").arg(counter).arg(total)
}
\endcode
%1 refers to the first parameter and \c %2 refers to the second parameter so this
code produces output like: "File 2 of 3".
\section2 5. Use %Lx so Numbers are Localized
If you include the \c %L modifier when you specify a parameter, the number is
localized according to the current regional settings. For example, in the
following code snippet, \c %L1 means to format the first parameters according to
the number formatting conventions of the currently selected locale (geographical
region):
\code
Text {
text: qsTr("%L1").arg(total)
}
\endcode
Then, with the above code, if \c total is the number "4321.56" (four thousand
three hundred and twenty one point fifty six); with English regional settings,
(locale) the output is "4,321.56"; with German regional settings, the output is
"4.321,56".
\section2 6. Internationalize Dates, Times and Currencies
There are no special in-string modifiers for formatting dates and times.
Instead, you need to query the current locale (geographical region) and use the
methods of \l {QtQuick2::Date}{Date} to format the string.
\c Qt.locale() returns a \l {QtQuick2::Locale}{Locale} object which contains all
kinds of information about the locale. In particular, the \l
{QtQuick2::Locale::name}{Locale.name} property contains the language and country
information for the current locale. You can use the value as is, or you can
parse it to determine the appropriate content for the current locale.
The following snippet gets the current date and time with Date(), then converts
that to a string for the current locale. Then it inserts the date string into
the %1 parameter for the appropriate translation.
\code
Text {
text: qsTr("Date %1").arg(Date().toLocaleString(Qt.locale()))
}
\endcode
To make sure currency numbers are localized, use the \l
{QtQuick2::Number}{Number} type. This type has similar functions as the Date
type for converting numbers into localized currency strings.
\section2 7. Use QT_TR_NOOP() for Translatable Data Text Strings
If the user changes the system language without a reboot, depending on the
system, the strings in arrays and list models and other data structures might
not be refreshed automatically. To force the texts to be refreshed when they are
displayed in the user interface, you need declare the strings with the
QT_TR_NOOP() macro. Then, when you populate the objects for display, you need to
explicitly retrieve the translation for each text. For example:
\code
ListModel {
id: myListModel;
ListElement {
//: Capital city of Finland
name: QT_TR_NOOP("Helsinki");
}
}
...
Text {
text: qsTr(myListModel.get(0).name); // get the translation of the name property in element 0
}
\endcode
\section2 8. Use Locale to Extend Localization Features
If you want different graphics or audio for different geographical regions, you
can use Qt.locale() to get the current locale. Then you choose appropriate
graphics or audio for that locale.
The following code snippet shows how you could select an appropriate icon
that represents the language of the current locale.
\code
Component.onCompleted: {
switch (Qt.locale().name.substring(0,2)) {
case "en": // show the English-language icon
languageIcon = "../images/language-icon_en.png";
break;
case "fi": // show the Finnish language icon
languageIcon = "../images/language-icon_fi.png";
break;
default: // show a default language icon
languageIcon = "../images/language-icon_default.png";
}
}
\endcode
\section1 Localizing your Application
Qt Quick applications use the same underlying localization system as Qt C++
applications (lupdate, lrelease and .ts files). You use the same tools as
described in the \l {Qt Linguist Manual: Release Manager}{Qt Linguist Manual}.
You can even have user interface strings in C++ and QML source in the same
application. The system will create a single combined translation file and the
strings are accessible from QML and C++.
\section2 Use a Conditional to Hide QML Source From the Compiler
The \c lupdate tool extracts user interface strings from your application.
lupdate reads your application's .pro file to identify which source files
contain texts to be translated. This means your source files must be listed in
the \c SOURCES or \c HEADERS entry in the .pro file. If your files are not
listed the texts in them will not be found.
However, the SOURCES variable is intended for C++ source files. If you list QML
or JavaScript source files there, the compiler tries to build them as though
they are C++ files. As a workaround, you can use an \c lupdate_only{...}
conditional statement so the \c lupdate tool sees the .qml files but the C++
compiler ignores them.
For example, the following .pro file snippet specifies two .qml files in
the application.
\code
lupdate_only{
SOURCES = main.qml \
MainPage.qml
}
\endcode
You can also specify the .qml source files with a wildcard match. The
search is not recursive so you need to specify each directory where there are
user interface strings in the source code:
\code
lupdate_only{
SOURCES = *.qml \
*.js \
content/*.qml \
content/*.js
}
\endcode
See the \l {Qt Linguist Manual} for more details about Qt localization.
*/
|
