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
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"><html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Qt Toolkit - Internationalization with Qt</title><style type="text/css"><!--
h3.fn,span.fn { margin-left: 1cm; text-indent: -1cm; }
a:link { color: #004faf; text-decoration: none }
a:visited { color: #672967; text-decoration: none }body { background: white; color: black; }
--></style></head><body bgcolor="#ffffff">
<p>
<table width="100%">
<tr><td><a href="index.html">
<img width="100" height="100" src="qtlogo.png"
alt="Home" border="0"><img width="100"
height="100" src="face.png" alt="Home" border="0">
</a><td valign=top><div align=right><img src="dochead.png" width="472" height="27"><br>
<a href="classes.html"><b>Classes</b></a>
-<a href="annotated.html">Annotated</a>
- <a href="hierarchy.html">Tree</a>
-<a href="functions.html">Functions</a>
-<a href="index.html">Home</a>
-<a href="topicals.html"><b>Structure</b></a>
</div>
</table>
<h1 align=center> Internationalization with Qt</h1><br clear="all">
Internationalization of software is the process of allowing the
software to be used efficiently by all people of the world. This
means adapting to user and locality preferences such as language,
input techniques, character encodings, and presentation conventions.
<p>
<h2>Step by Step</h2>
<p>
Writing cross-platform international software with Qt is a gentle,
incremental process. Your software can become internationalized in
the following stages:
<p>
<ol>
<li><b>Use QString for all user-visible text.</b>
<p>
Since QString uses the Unicode encoding internally, all the
languages of the world can be processed transparently using
familiar text processing operations. Also, since all Qt
functions that present text to the user take a QString as a
parameter, there is no char* to QString conversion time.
<p>
Strings that are in "programmer space" (such as QObject names
and file format texts) need not use QString; the traditional
char* or the QCString class will suffice.
<p>
You're unlikely to notice that you are using Unicode -
QString, and QChar are just like easier versions of the clumsy
const char* and char from traditional C.
</p>
<li><b>Use <a href="qobject.html#2418a9">tr()</a> for all literal text.</b>
<p>
Where your program uses <tt>"quoted text"</tt> for text
that will be presented to the user, ensure it goes through
the <a href="qapplication.html#35f6de">QApplication::translate()</a> function, usually this
simply means using <a href="qobject.html#2418a9">QObject::tr()</a>.
For example, assuming <tt>LoginWidget</tt> is a subclass of
QWidget:
<pre> LoginWidget::LoginWidget()
{
<a href="qlabel.html">QLabel</a> *label = new <a href="qlabel.html">QLabel</a>( tr("Password:"), this );
...
}
</pre>
<p>
This is 99% of the user-visible strings you're likely to
write.
<p>
If the quoted text is <em>not</em> in a member function of a
QObject/QWidget subclass, use either the tr() function of an
appropriate class, or the QApplication::translate() function
directly:
<pre> void some_global_function( LoginWidget * logwid )
{
<a href="qlabel.html">QLabel</a> *label = new <a href="qlabel.html">QLabel</a>(
LoginWidget::tr("Password:"), logwid );
}
void same_global_function( LoginWidget * logwid )
{
<a href="qlabel.html">QLabel</a> *label = new <a href="qlabel.html">QLabel</a>(
qApp->translate("LoginWidget", "Password:"),
logwid );
}
</pre>
<p>
Finally, if you need to have translatable text completely
outside a function, there are two macros to help: QT_TR_NOOP()
and QT_TRANSLATE_NOOP(). They merely mark the text for
extraction by the <tt>lupdate</tt> utility described below -
the macros expand to just the text (without the scope).
Example usages are shown below.
<p>
<pre> <a href="qstring.html">QString</a> FriendlyConversation::greeting( int greet_type )
{
static const char* greeting_strings[] = {
QT_TR_NOOP( "Hello" ),
QT_TR_NOOP( "Goodbye" )
};
return tr( greeting_strings[greet_type] );
}
static const char* greeting_strings[] = {
QT_TRANSLATE_NOOP( "FriendlyConversation", "Hello" ),
QT_TRANSLATE_NOOP( "FriendlyConversation", "Goodbye" )
};
<a href="qstring.html">QString</a> FriendlyConversation::greeting( int greet_type )
{
return tr( greeting_strings[greet_type] );
}
</pre>
<p>
If you disable the const char* to QString automatic conversion
by compiling your software with the macro QT_NO_CAST_ASCII
defined, you'll be very likely to catch any strings you are
missing. See QString::fromLatin1() for more details. Disabling
the conversion can make programming cumbersome.
</p>
<li><b>Use QString::arg() for simple arguments.</b>
<p>
The printf() style of inserting arguments in strings
is a poor choice for internationalized text, as it is
sometimes necessary to change the order of arguments when
translating. The <a href="qstring.html#8bd12a">QString::arg()</a>
functions offer a simple means for substituting arguments:
<pre> void FileCopier::showProgress( int done, int total,
const QString& current_file )
{
label.setText( tr("%1 of %2 files copied.\nCopying: %3")
.arg(done)
.arg(total)
.arg(current_file)
);
}
</pre>
<p>
</p>
<li><b>Produce translation.</b>
<p>
The following requires the Qt Linguist and it's tools.
<tt>lupdate</tt> and <tt>lrelease</tt> are parts of this
package.
A prerelease version of the Linguist is available from
<a href="http://www.trolltech.com/company/announce/linguistpre.html">
http://www.trolltech.com/company/announce/linguistpre.html</a>.
<p>
Once you are using tr() sufficiently, you can start producing
translations of the user-visible text in your program.
<p>
Translation of a Qt application is a three-step process:
<p>
<ol>
<li> Run <tt>lupdate</tt> to extract translatable text from
the C++ source code of the Qt application, resulting in a
message file for translators (a .ts file). The utility
recognizes the tr() construct described above and creates
a certain number of .ts files (usually one per language).
<li> Provide translations for the source texts in the .ts
file, using Qt Linguist. Since .ts files are in XML
format, you can also edit them by hand.
<li> Run <tt>lrelease</tt> to obtain a light-weight message
file (a .qm file) from the .ts file, suitable only for end
use. You can see the .ts files as "source files", and .qm
as "object files". The translator edits the .ts files, but
the users of your application only need the .qm files. Both
kinds of files are platform and locale independent.
</ol>
<p>
Typically, you will repeat these steps for every release of
your application. The <tt>lupdate</tt> utility does its best
to reuse the translations from the previous release.
<p>
Before you run <tt>lupdate</tt>, you should prepare a project
file. Here's an example project file (or .pro file):
<p>
<pre>
HEADERS = funnydialog.h \
wackywidget.h \
SOURCES = funnydialog.cpp \
main.cpp \
wackywidget.cpp
TRANSLATIONS = superapp_dk.ts \
superapp_fi.ts \
superapp_no.ts \
superapp_se.ts
</pre>
<p>
When you invoke <tt>lupdate</tt> or <tt>lrelease</tt>, you
have to give the name of the project file as a command-line
argument.
<p>
In this example, four exotic languages are supported: Danish,
Finnish, Norwegian and Swedish. If you use tmake, you don't
need an extra project file for lupdate; your tmake project
file will do, if you add the TRANSLATIONS lines.
<p>
In your application, you have to <a href="qtranslator.html#4053d1">QTranslator::load()</a>
the translation files appropriate for the user's language, and
to install them using <a href="qapplication.html#e8df5e">QApplication::installTranslator()</a>.
<p>
If you have been using the old Qt tools (findtr, msg2qm and
mergetr), you can use <tt>qm2ts</tt> to convert your old
.qm files.
<p>
To get started, you should read at least the first chapter of
the translation tutorial.
<p>
While these utilities offer a convenient way to create .qm
files, any system that writes .qm files is sufficient. You
could make an application that adds translations to a
QTranslator with QTranslator::insert() and then writes a .qm
file with QTranslator::save(). This way the translations can
come from any source you choose.
<p>
Qt itself contains a small number of strings that will also
need to be translated to the languages that you are
targeting. In the near future Qt will ship with translations
for some languages. We recommend that if you need to
translate the Qt strings now, put the translations in separate
.ts and .qm files. This will simplify transition to the
official Qt translations.
<p>
</p>
<li><b>Support encodings.</b>
<p>
The QTextCodec class and the facilities in QTextStream
make it easy to support many input and
output encodings for your users' data. When the application
starts, the locale of the machine will determine the 8-bit
encoding used when dealing with 8-bit data - such as for
font selection, text display, 8-bit text I/O, and character input.
<p>
The application may occasionally have need for encodings other
than the default local 8-bit encoding. For example, an application
in a Cyrillic KOI8-R locale (the defacto-standard locale in Russia)
might need to output Cyrillic in the ISO 8859-5 encoding. Code for
this would be:
<p>
<pre> <a href="qstring.html">QString</a> string = ...; // Some Unicode text.
<a href="qtextcodec.html">QTextCodec</a>* codec = QTextCodec::codecForName("ISO 8859-5");
<a href="qcstring.html">QCString</a> encoded_string = codec-><a href="qtextcodec.html#ec806f">fromUnicode</a>(string);
...; // Use encoded_string in 8-bit operations
</pre>
<p>
For converting Unicode to local 8-bit encodings,
a shortcut is available: the
<a href="qstring.html#85c213">local8Bit()</a> method of
QString returns such 8-bit data. Another useful shortcut
is the <a href="qstring.html#011d3d">utf8()</a> method, which
returns text in the 8-bit UTF-8 encoding - interesting in
that it perfectly preserves Unicode information while looking
like plain US-ASCII if the Unicode is wholly US-ASCII.
<p>
For converting the other way, there are the
<a href="qstring.html#9465e8">QString::fromUtf8()</a> and
<a href="qstring.html#47169a">QString::fromLocal8Bit()</a>
convenience functions, or the general code, demonstrated by
this conversion from ISO 8859-5 Cyrillic to Unicode conversion:
<p>
<pre> <a href="qcstring.html">QCString</a> encoded_string = ...; // Some ISO 8859-5 encoded text.
<a href="qtextcodec.html">QTextCodec</a>* codec = QTextCodec::codecForName("ISO 8859-5");
<a href="qstring.html">QString</a> string = codec-><a href="qtextcodec.html#32c727">toUnicode</a>(encoded_string);
...; // Use string in all of Qt's QString operations.
</pre>
<p>
Ideally Unicode I/O should be used as this maximizes the portability
of documents between users around the world, but in reality
it is useful to support all the appropriate encodings that
your users' will need to process existing documents. In general,
Unicode (UTF16 or UTF8) is the best for information transferred
between arbitrary people, while within a language or national group,
a local standard is often more appropriate. The most important
encoding to support is the one returned by
<a href="qtextcodec.html#615e15">QTextCodec::codecForLocale()</a>,
as this is the one the user is most likely to need for communicating
with other people and applications (this is the codec used by
local8Bit()).
<p>
Since most Unix systems do not have built-in support for converting
between local 8-bit encodings and Unicode, it may be necessary to
write your own QTextCodec subclass. Depending on the urgency, it
may be useful to contact Trolltech technical support or ask on
the qt-interest mailing list to see if someone else is already working
on supporting the encoding. A useful interim measure can be to
use the QTextCodec::loadCharmapFile() function to build a data-driven
codec; this has a memory and speed penalty, especially with
dynamically loaded libraries. For details of writing your own
QTextCodec, see the mail QTextCodec class documentation.
<p>
</p>
<li><b>Localization.</b>
<p>
Localization is the process of adapting to local conventions
such as date and time presentations. Such localizations can be
accomplished using appropriate tr() strings, even "magic" words,
as this somewhat contrived example shows:
<pre> void Clock::setTime(const QTime& t)
{
if ( tr("AMPM") == "AMPM" ) {
// 12-hour clock
} else {
// 24-hour clock
}
}
</pre>
<p>
</p>
<p>
In general, it is recommended that you do <em>not</em> attempt
to localize images - choose clear icons that are appropriate
for all localities, rather than relying on local puns or
stretched metaphors.
</ol>
<p>
<h2>System Support</h2>
<p>
Operating systems and window systems supporting Unicode are still in
the early stages of development. The level of support
available in the underlying system influences the support Qt provides
on that platform, but applications written with Qt need not generally
be too concerned with the actual limitations.
<dl compact>
<dt>Unix/X11
<dd><ul>
<li>Locale-oriented fonts and input methods. Qt hides these and
provides Unicode input and output.
<li>Filesystem conventions such as
<a class="r" href="http://www.ietf.org/rfc/rfc2279.txt">UTF-8</a>
are under development
in some Unix variants. All Qt file functions allow Unicode,
but convert all filenames to the local 8-bit encoding, as
this is the Unix convention
(see <a href="qfile.html#a34c1e">QFile::setEncodingFunction()</a>
if you are interested in exploring alternative encodings).
<li>File I/O defaults to the local 8-bit encoding,
with Unicode options in QTextStream.
</ul>
<dt>Windows 95/98/NT
<dd><ul>
<li>Qt provides full Unicode support, including input methods, fonts,
clipboard, drag-and-drop, and file names.
<li>File I/O defaults to Latin-1, with Unicode options in QTextStream.
Note that some Windows programs do not understand big-endian
Unicode text files even though that is the order prescribed by
the Unicode Standard in the absence of higher-level protocols.
<li>Note that unlike programs written with MFC or plain winlib, Qt programs
are portable between Windows 95/98 and Windows NT -
<em>you do not need different binaries to support Unicode</em>.
</ul>
</dl>
<p>
<h2>Supporting more Input Methods</h2>
<p>
While Trolltech doesn't have the resources or expertise in all the
languages of the world to immediately include support in Qt, we are
very keen to work with people who <em>do</em> have the expertise.
Over the next few minor version numbers, we hope to add support for
<em>your</em> language of choice, until everyone can use Qt and all
the programs developed with Qt, regardless of their language.
<p>
Initially, languages with uni-directional single-byte encodings
(European Latin-1 and KOI8-R, etc.) and the uni-directional
multi-byte encodings (East Asian EUC-JP, etc.) will be supported.
Later, support for the "complex" encodings - those requiring
right-to-left input or complex character composition (eg. Arabic,
Hebrew, and Thai script) will be implemented. The current state of
activity is:
<dl compact>
<dt><b>All encodings on Windows</b>
<dd>On Windows, the local encoding is always supported.
<dt><b>ISO standard encodings
ISO 8859-1,
ISO 8859-2,
ISO 8859-3,
ISO 8859-4,
ISO 8859-5,
ISO 8859-7,
ISO 8859-9, and
ISO 8859-15
</b>
<dd>Fully supported.
The Arabic (ISO 8859-6-I) and Hebrew (ISO 8859-8-I) encodings
are not supported, but are under development externally.
<dt><b>KOI8-R</b>
<dd>Fully supported.
<dt><b>eucJP, JIS, and ShiftJIS</b>
<dd>Fully supported. Uses eucJP with the XIM protocol on X11,
and the IME Windows NT in Japanese Windows NT.
Serika Kurusugawa and other are assisting with this effort.
<a href="ftp://ftp.sra.co.jp/pub/x11/kinput2/">kinput2</a>
is the tested input method for X11.
<dt><b>eucKR</b>
<dd>Under external development,
Mizi Research are assisting with this effort.
<a class="r" href="http://www.mizi.com">hanIM</a>
is the tested input method.
<dt><b>Big5</b>
<dd>Qt contains a Big5 codec developed by Ming Che-Chuang.
Testing is underway with the xcin (2.5.x) XIM server.
<dt><b>eucTW</b>
<dd>Under external development.
</dl>
<p>
If you are interested in contributing to existing efforts, or
supporting new encodings beyond the more standard ones above, your
work can be considered for inclusion in the official Qt distribution,
or just included with your application.
<p>
Eventually, we hope to help Unix become as Unicode-oriented as
Windows NT is becoming. This means better font support in the font servers,
with new developments like the True Type font servers
<a class="r" href="http://www.dcs.ed.ac.uk/home/jec/programs/xfsft/">xfsft</a>,
<a href="ftp://sunsite.unc.edu/pub/Linux/X11/fonts/">xfstt</a>,
and x-tt, as well as
<a href="http://www.ietf.org/rfc/rfc2279.txt">UTF-8</a>
(a Unicode encoding) filenames such as with the
<a href="http://www.sun.com/software/white-papers/wp-unicode/">Unicode
support in Solaris<sup class="tm"><font size="-1">TM</font></sup> 7</a>.
<p>
<h2>Notes about locales on X11</h2>
<p>
Many Unix distributions contain only partial support for some locales -
for example, if you have a <tt>/usr/share/locale/ja_JP.EUC</tt>
directory, this does not necessarily mean you can display Japanese text
- you also need JIS encoded fonts (or Unicode fonts), and that
<tt>/usr/share/locale/ja_JP.EUC</tt> directory needs to be complete.
For best results, use complete locales from your OS vendor.
<p><address><hr><div align="center">
<table width="100%" cellspacing="0" border="0"><tr>
<td>Copyright 2001 Trolltech<td><a href="http://www.trolltech.com/trademarks.html">Trademarks</a>
<td align="right"><div align="right">Qt version 2.3.2</div>
</table></div></address></body></html>
|
