← Back to branch summary

~oif-team/ubuntu/natty/qt4-x11/xi2.1

« back to all changes in this revision

Viewing changes to doc/src/i18n.qdoc

  • Committer: Bazaar Package Importer
  • Author(s): Alessandro Ghersi
  • Date: 2009-11-02 18:30:08 UTC
  • mfrom: (1.2.2 upstream)
  • mto: (15.2.5 experimental)
  • mto: This revision was merged to the branch mainline in revision 88.
  • Revision ID: james.westby@ubuntu.com-20091102183008-b6a4gcs128mvfb3m
Tags: upstream-4.6.0~beta1
Import upstream version 4.6.0~beta1

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/src/i18n.qdoc
1
 
/****************************************************************************
2
 
**
3
 
** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
4
 
** Contact: Nokia Corporation (qt-info@nokia.com)
5
 
**
6
 
** This file is part of the documentation of the Qt Toolkit.
7
 
**
8
 
** $QT_BEGIN_LICENSE:LGPL$
9
 
** Commercial Usage
10
 
** Licensees holding valid Qt Commercial licenses may use this file in
11
 
** accordance with the Qt Commercial License Agreement provided with the
12
 
** Software or, alternatively, in accordance with the terms contained in
13
 
** a written agreement between you and Nokia.
14
 
**
15
 
** GNU Lesser General Public License Usage
16
 
** Alternatively, this file may be used under the terms of the GNU Lesser
17
 
** General Public License version 2.1 as published by the Free Software
18
 
** Foundation and appearing in the file LICENSE.LGPL included in the
19
 
** packaging of this file.  Please review the following information to
20
 
** ensure the GNU Lesser General Public License version 2.1 requirements
21
 
** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
22
 
**
23
 
** In addition, as a special exception, Nokia gives you certain
24
 
** additional rights. These rights are described in the Nokia Qt LGPL
25
 
** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this
26
 
** package.
27
 
**
28
 
** GNU General Public License Usage
29
 
** Alternatively, this file may be used under the terms of the GNU
30
 
** General Public License version 3.0 as published by the Free Software
31
 
** Foundation and appearing in the file LICENSE.GPL included in the
32
 
** packaging of this file.  Please review the following information to
33
 
** ensure the GNU General Public License version 3.0 requirements will be
34
 
** met: http://www.gnu.org/copyleft/gpl.html.
35
 
**
36
 
** If you are unsure which license is appropriate for your use, please
37
 
** contact the sales department at http://www.qtsoftware.com/contact.
38
 
** $QT_END_LICENSE$
39
 
**
40
 
****************************************************************************/
41
 
 
42
 
/*!
43
 
    \group i18n
44
 
    \title Internationalization with Qt
45
 
    \ingroup topics
46
 
 
47
 
    \brief Information about Qt's support for internationalization and multiple languages.
48
 
 
49
 
    \keyword internationalization
50
 
    \keyword i18n
51
 
 
52
 
    The internationalization of an application is the process of making
53
 
    the application usable by people in countries other than one's own.
54
 
 
55
 
    \tableofcontents
56
 
 
57
 
    In some cases internationalization is simple, for example, making a US
58
 
    application accessible to Australian or British users may require
59
 
    little more than a few spelling corrections. But to make a US
60
 
    application usable by Japanese users, or a Korean application usable
61
 
    by German users, will require that the software operate not only in
62
 
    different languages, but use different input techniques, character
63
 
    encodings and presentation conventions.
64
 
 
65
 
    Qt tries to make internationalization as painless as possible for
66
 
    developers. All input widgets and text drawing methods in Qt offer
67
 
    built-in support for all supported languages. The built-in font engine
68
 
    is capable of correctly and attractively rendering text that contains
69
 
    characters from a variety of different writing systems at the same
70
 
    time.
71
 
 
72
 
    Qt supports most languages in use today, in particular:
73
 
    \list
74
 
    \o All East Asian languages (Chinese, Japanese and Korean)
75
 
    \o All Western languages (using Latin script)
76
 
    \o Arabic
77
 
    \o Cyrillic languages (Russian, Ukrainian, etc.)
78
 
    \o Greek
79
 
    \o Hebrew
80
 
    \o Thai and Lao
81
 
    \o All scripts in Unicode 4.0 that do not require special processing
82
 
    \endlist
83
 
 
84
 
    On Windows, Unix/X11 with FontConfig (client side font support)
85
 
    and Qt for Embedded Linux the following languages are also supported:
86
 
    \list
87
 
    \o Bengali
88
 
    \o Devanagari
89
 
    \o Dhivehi (Thaana)
90
 
    \o Gujarati
91
 
    \o Gurmukhi
92
 
    \o Kannada
93
 
    \o Khmer
94
 
    \o Malayalam
95
 
    \o Myanmar
96
 
    \o Syriac
97
 
    \o Tamil
98
 
    \o Telugu
99
 
    \o Tibetan
100
 
    \endlist
101
 
 
102
 
    Many of these writing systems exhibit special features:
103
 
 
104
 
    \list
105
 
 
106
 
    \o \bold{Special line breaking behavior.} Some of the Asian languages are
107
 
    written without spaces between words. Line breaking can occur either
108
 
    after every character (with exceptions) as in Chinese, Japanese and
109
 
    Korean, or after logical word boundaries as in Thai.
110
 
 
111
 
    \o \bold{Bidirectional writing.} Arabic and Hebrew are written from right to
112
 
    left, except for numbers and embedded English text which is written
113
 
    left to right. The exact behavior is defined in the
114
 
    \l{http://www.unicode.org/unicode/reports/tr9/}{Unicode Technical Annex #9}.
115
 
 
116
 
    \o \bold{Non-spacing or diacritical marks (accents or umlauts in European
117
 
    languages).} Some languages such as Vietnamese make extensive use of
118
 
    these marks and some characters can have more than one mark at the
119
 
    same time to clarify pronunciation.
120
 
 
121
 
    \o \bold{Ligatures.} In special contexts, some pairs of characters get
122
 
    replaced by a combined glyph forming a ligature. Common examples are
123
 
    the fl and fi ligatures used in typesetting US and European books.
124
 
 
125
 
    \endlist
126
 
 
127
 
    Qt tries to take care of all the special features listed above. You
128
 
    usually don't have to worry about these features so long as you use
129
 
    Qt's input widgets (e.g. QLineEdit, QTextEdit, and derived classes)
130
 
    and Qt's display widgets (e.g. QLabel).
131
 
 
132
 
    Support for these writing systems is transparent to the
133
 
    programmer and completely encapsulated in \l{rich text
134
 
    processing}{Qt's text engine}. This means that you don't need to
135
 
    have any knowledge about the writing system used in a particular
136
 
    language, except for the following small points:
137
 
 
138
 
    \list
139
 
 
140
 
    \o QPainter::drawText(int x, int y, const QString &str) will always
141
 
    draw the string with its left edge at the position specified with
142
 
    the x, y parameters. This will usually give you left aligned strings.
143
 
    Arabic and Hebrew application strings are usually right
144
 
    aligned, so for these languages use the version of drawText() that
145
 
    takes a QRect since this will align in accordance with the language.
146
 
 
147
 
    \o When you write your own text input controls, use \l
148
 
    QFontMetrics::charWidth() to determine the width of a character in a
149
 
    string. In some languages (e.g. Arabic or languages from the Indian
150
 
    subcontinent), the width and shape of a glyph changes depending on the
151
 
    surrounding characters. Writing input controls usually requires a
152
 
    certain knowledge of the scripts it is going to be used in. Usually
153
 
    the easiest way is to subclass QLineEdit or QTextEdit.
154
 
 
155
 
    \endlist
156
 
 
157
 
    The following sections give some information on the status of the
158
 
    internationalization (i18n) support in Qt. See also the \l{Qt
159
 
    Linguist manual}.
160
 
 
161
 
    \section1 Step by Step
162
 
 
163
 
    Writing cross-platform international software with Qt is a gentle,
164
 
    incremental process. Your software can become internationalized in
165
 
    the following stages:
166
 
 
167
 
    \section2 Use QString for All User-Visible Text
168
 
 
169
 
    Since QString uses the Unicode 4.0 encoding internally, every
170
 
    language in the world can be processed transparently using
171
 
    familiar text processing operations. Also, since all Qt functions
172
 
    that present text to the user take a QString as a parameter,
173
 
    there is no \c{char *} to QString conversion overhead.
174
 
 
175
 
    Strings that are in "programmer space" (such as QObject names
176
 
    and file format texts) need not use QString; the traditional
177
 
    \c{char *} or the QByteArray class will suffice.
178
 
 
179
 
    You're unlikely to notice that you are using Unicode;
180
 
    QString, and QChar are just like easier versions of the crude
181
 
    \c{const char *} and char from traditional C.
182
 
 
183
 
    \section2 Use tr() for All Literal Text
184
 
 
185
 
    Wherever your program uses "quoted text" for text that will
186
 
    be presented to the user, ensure that it is processed by the \l
187
 
    QCoreApplication::translate() function. Essentially all that is necessary
188
 
    to achieve this is to use QObject::tr(). For example, assuming the
189
 
    \c LoginWidget is a subclass of QWidget:
190
 
 
191
 
    \snippet doc/src/snippets/code/doc_src_i18n.qdoc 0
192
 
 
193
 
    This accounts for 99% of the user-visible strings you're likely to
194
 
    write.
195
 
 
196
 
    If the quoted text is not in a member function of a
197
 
    QObject subclass, use either the tr() function of an
198
 
    appropriate class, or the QCoreApplication::translate() function
199
 
    directly:
200
 
 
201
 
    \snippet doc/src/snippets/code/doc_src_i18n.qdoc 1
202
 
 
203
 
    If you need to have translatable text completely
204
 
    outside a function, there are two macros to help: QT_TR_NOOP()
205
 
    and QT_TRANSLATE_NOOP(). They merely mark the text for
206
 
    extraction by the \c lupdate utility described below.
207
 
    The macros expand to just the text (without the context).
208
 
 
209
 
    Example of QT_TR_NOOP():
210
 
 
211
 
    \snippet doc/src/snippets/code/doc_src_i18n.qdoc 2
212
 
 
213
 
    Example of QT_TRANSLATE_NOOP():
214
 
 
215
 
    \snippet doc/src/snippets/code/doc_src_i18n.qdoc 3
216
 
 
217
 
    If you disable the \c{const char *} to QString automatic
218
 
    conversion by compiling your software with the macro \c
219
 
    QT_NO_CAST_FROM_ASCII defined, you'll be very likely to catch any
220
 
    strings you are missing. See QString::fromLatin1() for more
221
 
    information. Disabling the conversion can make programming a bit
222
 
    cumbersome.
223
 
 
224
 
    If your source language uses characters outside Latin1, you
225
 
    might find QObject::trUtf8() more convenient than
226
 
    QObject::tr(), as tr() depends on the
227
 
    QTextCodec::codecForTr(), which makes it more fragile than
228
 
    QObject::trUtf8().
229
 
 
230
 
    \section2 Use QKeySequence() for Accelerator Values
231
 
 
232
 
    Accelerator values such as Ctrl+Q or Alt+F need to be translated
233
 
    too. If you hardcode Qt::CTRL + Qt::Key_Q for "quit" in your
234
 
    application, translators won't be able to override it. The
235
 
    correct idiom is
236
 
 
237
 
    \snippet examples/mainwindows/application/mainwindow.cpp 20
238
 
 
239
 
    \section2 Use QString::arg() for Dynamic Text
240
 
 
241
 
    The QString::arg() functions offer a simple means for substituting
242
 
    arguments:
243
 
    \snippet doc/src/snippets/code/doc_src_i18n.qdoc 4
244
 
 
245
 
    In some languages the order of arguments may need to change, and this
246
 
    can easily be achieved by changing the order of the % arguments. For
247
 
    example:
248
 
 
249
 
    \snippet doc/src/snippets/code/doc_src_i18n.qdoc 5
250
 
 
251
 
    produces the correct output in English and Norwegian:
252
 
    \snippet doc/src/snippets/code/doc_src_i18n.qdoc 6
253
 
 
254
 
    \section2 Produce Translations
255
 
 
256
 
    Once you are using tr() throughout an application, you can start
257
 
    producing translations of the user-visible text in your program.
258
 
 
259
 
    The \l{Qt Linguist manual} provides further information about
260
 
    Qt's translation tools, \e{Qt Linguist}, \c lupdate and \c
261
 
    lrelease.
262
 
 
263
 
    Translation of a Qt application is a three-step process:
264
 
 
265
 
    \list 1
266
 
 
267
 
    \o Run \c lupdate to extract translatable text from the C++
268
 
    source code of the Qt application, resulting in a message file
269
 
    for translators (a \c .ts file). The utility recognizes the tr()
270
 
    construct and the \c{QT_TR*_NOOP()} macros described above and
271
 
    produces \c .ts files (usually one per language).
272
 
 
273
 
    \o Provide translations for the source texts in the \c .ts file, using
274
 
    \e{Qt Linguist}. Since \c .ts files are in XML format, you can also
275
 
    edit them by hand.
276
 
 
277
 
    \o Run \c lrelease to obtain a light-weight message file (a \c .qm
278
 
    file) from the \c .ts file, suitable only for end use. Think of the \c
279
 
    .ts files as "source files", and \c .qm files as "object files". The
280
 
    translator edits the \c .ts files, but the users of your application
281
 
    only need the \c .qm files. Both kinds of files are platform and
282
 
    locale independent.
283
 
 
284
 
    \endlist
285
 
 
286
 
    Typically, you will repeat these steps for every release of your
287
 
    application. The \c lupdate utility does its best to reuse the
288
 
    translations from previous releases.
289
 
 
290
 
    Before you run \c lupdate, you should prepare a project file. Here's
291
 
    an example project file (\c .pro file):
292
 
 
293
 
    \snippet doc/src/snippets/code/doc_src_i18n.qdoc 7
294
 
 
295
 
    When you run \c lupdate or \c lrelease, you must give the name of the
296
 
    project file as a command-line argument.
297
 
 
298
 
    In this example, four exotic languages are supported: Danish,
299
 
    Finnish, Norwegian and Swedish. If you use \l{qmake}, you usually
300
 
    don't need an extra project file for \c lupdate; your \c qmake
301
 
    project file will work fine once you add the \c TRANSLATIONS
302
 
    entry.
303
 
 
304
 
    In your application, you must \l QTranslator::load() the translation
305
 
    files appropriate for the user's language, and install them using \l
306
 
    QCoreApplication::installTranslator().
307
 
 
308
 
    \c linguist, \c lupdate and \c lrelease are installed in the \c bin
309
 
    subdirectory of the base directory Qt is installed into. Click Help|Manual
310
 
    in \e{Qt Linguist} to access the user's manual; it contains a tutorial
311
 
    to get you started.
312
 
 
313
 
    \target qt-itself
314
 
    Qt itself contains over 400 strings that will also need to be
315
 
    translated into the languages that you are targeting. You will find
316
 
    translation files for French, German and Simplified Chinese in
317
 
    \c{$QTDIR/translations}, as well as a template for translating to
318
 
    other languages. (This directory also contains some additional
319
 
    unsupported translations which may be useful.)
320
 
 
321
 
    Typically, your application's \c main() function will look like
322
 
    this:
323
 
 
324
 
    \snippet doc/src/snippets/code/doc_src_i18n.qdoc 8
325
 
 
326
 
    Note the use of QLibraryInfo::location() to locate the Qt translations.
327
 
    Developers should request the path to the translations at run-time by
328
 
    passing QLibraryInfo::TranslationsPath to this function instead of
329
 
    using the \c QTDIR environment variable in their applications.
330
 
 
331
 
    \section2 Support for Encodings
332
 
 
333
 
    The QTextCodec class and the facilities in QTextStream make it easy to
334
 
    support many input and output encodings for your users' data. When an
335
 
    application starts, the locale of the machine will determine the 8-bit
336
 
    encoding used when dealing with 8-bit data: such as for font
337
 
    selection, text display, 8-bit text I/O, and character input.
338
 
 
339
 
    The application may occasionally require encodings other than the
340
 
    default local 8-bit encoding. For example, an application in a
341
 
    Cyrillic KOI8-R locale (the de-facto standard locale in Russia) might
342
 
    need to output Cyrillic in the ISO 8859-5 encoding. Code for this
343
 
    would be:
344
 
 
345
 
    \snippet doc/src/snippets/code/doc_src_i18n.qdoc 9
346
 
 
347
 
    For converting Unicode to local 8-bit encodings, a shortcut is
348
 
    available: the QString::toLocal8Bit() function returns such 8-bit
349
 
    data. Another useful shortcut is QString::toUtf8(), which returns
350
 
    text in the 8-bit UTF-8 encoding: this perfectly preserves
351
 
    Unicode information while looking like plain ASCII if the text is
352
 
    wholly ASCII.
353
 
 
354
 
    For converting the other way, there are the QString::fromUtf8() and
355
 
    QString::fromLocal8Bit() convenience functions, or the general code,
356
 
    demonstrated by this conversion from ISO 8859-5 Cyrillic to Unicode
357
 
    conversion:
358
 
 
359
 
    \snippet doc/src/snippets/code/doc_src_i18n.qdoc 10
360
 
 
361
 
    Ideally Unicode I/O should be used as this maximizes the portability
362
 
    of documents between users around the world, but in reality it is
363
 
    useful to support all the appropriate encodings that your users will
364
 
    need to process existing documents. In general, Unicode (UTF-16 or
365
 
    UTF-8) is best for information transferred between arbitrary people,
366
 
    while within a language or national group, a local standard is often
367
 
    more appropriate. The most important encoding to support is the one
368
 
    returned by QTextCodec::codecForLocale(), as this is the one the user
369
 
    is most likely to need for communicating with other people and
370
 
    applications (this is the codec used by local8Bit()).
371
 
 
372
 
    Qt supports most of the more frequently used encodings natively. For a
373
 
    complete list of supported encodings see the \l QTextCodec
374
 
    documentation.
375
 
 
376
 
    In some cases and for less frequently used encodings it may be
377
 
    necessary to write your own QTextCodec subclass. Depending on the
378
 
    urgency, it may be useful to contact Qt's technical support team or
379
 
    ask on the \c qt-interest mailing list to see if someone else is
380
 
    already working on supporting the encoding.
381
 
 
382
 
    \keyword localization
383
 
 
384
 
    \section2 Localize
385
 
 
386
 
    Localization is the process of adapting to local conventions, for
387
 
    example presenting dates and times using the locally preferred
388
 
    formats. Such localizations can be accomplished using appropriate tr()
389
 
    strings.
390
 
 
391
 
    \snippet doc/src/snippets/code/doc_src_i18n.qdoc 11
392
 
 
393
 
    In the example, for the US we would leave the translation of
394
 
    "AMPM" as it is and thereby use the 12-hour clock branch; but in
395
 
    Europe we would translate it as something else and this will make
396
 
    the code use the 24-hour clock branch.
397
 
 
398
 
    For localized numbers use the QLocale class.
399
 
 
400
 
    Localizing images is not recommended. Choose clear icons that are
401
 
    appropriate for all localities, rather than relying on local puns or
402
 
    stretched metaphors. The exception is for images of left and right
403
 
    pointing arrows which may need to be reversed for Arabic and Hebrew
404
 
    locales.
405
 
 
406
 
    \section1 Dynamic Translation
407
 
 
408
 
    Some applications, such as Qt Linguist, must be able to support changes
409
 
    to the user's language settings while they are still running. To make
410
 
    widgets aware of changes to the installed QTranslators, reimplement the 
411
 
    widget's \l{QWidget::changeEvent()}{changeEvent()} function to check whether 
412
 
    the event is a \l{QEvent::LanguageChange}{LanguageChange} event, and update
413
 
    the text displayed by widgets using the \l{QObject::tr()}{tr()} function
414
 
    in the usual way. For example:
415
 
 
416
 
    \snippet doc/src/snippets/code/doc_src_i18n.qdoc 12
417
 
 
418
 
    All other change events should be passed on by calling the default
419
 
    implementation of the function.
420
 
 
421
 
    The list of installed translators might change in reaction to a 
422
 
    \l{QEvent::LocaleChange}{LocaleChange} event, or the application might
423
 
    provide a user interface that allows the user to change the current
424
 
    application language.
425
 
 
426
 
    The default event handler for QWidget subclasses responds to the
427
 
    QEvent::LanguageChange event, and will call this function when necessary;
428
 
    other application components can also force widgets to update themselves
429
 
    by posting the \l{QEvent::LanguageChange}{LanguageChange} event to them.
430
 
 
431
 
    \section1 Translating Non-Qt Classes
432
 
 
433
 
    It is sometimes necessary to provide internationalization support for
434
 
    strings used in classes that do not inherit QObject or use the Q_OBJECT
435
 
    macro to enable translation features. Since Qt translates strings at
436
 
    run-time based on the class they are associated with and \c lupdate
437
 
    looks for translatable strings in the source code, non-Qt classes must
438
 
    use mechanisms that also provide this information.
439
 
 
440
 
    One way to do this is to add translation support to a non-Qt class
441
 
    using the Q_DECLARE_TR_FUNCTIONS() macro; for example:
442
 
 
443
 
    \snippet doc/src/snippets/i18n-non-qt-class/myclass.h 0
444
 
    \dots
445
 
    \snippet doc/src/snippets/i18n-non-qt-class/myclass.h 1
446
 
 
447
 
    This provides the class with \l{QObject::}{tr()} functions that can
448
 
    be used to translate strings associated with the class, and makes it
449
 
    possible for \c lupdate to find translatable strings in the source
450
 
    code.
451
 
 
452
 
    Alternatively, the QCoreApplication::translate() function can be called
453
 
    with a specific context, and this will be recognized by \c lupdate and
454
 
    Qt Linguist.
455
 
 
456
 
    \section1 System Support
457
 
 
458
 
    Some of the operating systems and windowing systems that Qt runs on
459
 
    only have limited support for Unicode. The level of support available
460
 
    in the underlying system has some influence on the support that Qt can
461
 
    provide on those platforms, although in general Qt applications need
462
 
    not be too concerned with platform-specific limitations.
463
 
 
464
 
    \section2 Unix/X11
465
 
 
466
 
    \list
467
 
    \o  Locale-oriented fonts and input methods. Qt hides these and
468
 
        provides Unicode input and output.
469
 
    \o  Filesystem conventions such as
470
 
        \l{http://www.ietf.org/rfc/rfc2279.txt}{UTF-8}
471
 
        are under development in some Unix variants. All Qt file
472
 
        functions allow Unicode, but convert filenames to the local
473
 
        8-bit encoding, as this is the Unix convention (see
474
 
        QFile::setEncodingFunction() to explore alternative
475
 
        encodings).
476
 
    \o  File I/O defaults to the local 8-bit encoding,
477
 
        with Unicode options in QTextStream.
478
 
    \o  Many Unix distributions contain only partial support for some locales.
479
 
        For example, if you have a \c /usr/share/locale/ja_JP.EUC directory,
480
 
        this does not necessarily mean you can display Japanese text; you also
481
 
        need JIS encoded fonts (or Unicode fonts), and the
482
 
        \c /usr/share/locale/ja_JP.EUC directory needs to be complete. For
483
 
        best results, use complete locales from your system vendor.
484
 
    \endlist
485
 
 
486
 
    \section2 Windows
487
 
 
488
 
    \list
489
 
    \o  Qt provides full Unicode support, including input methods, fonts,
490
 
        clipboard, drag-and-drop and file names.
491
 
    \o  File I/O defaults to Latin1, with Unicode options in QTextStream.
492
 
        Note that some Windows programs do not understand big-endian
493
 
        Unicode text files even though that is the order prescribed by
494
 
        the Unicode Standard in the absence of higher-level protocols.
495
 
    \o  Unlike programs written with MFC or plain winlib, Qt programs
496
 
        are portable between Windows 98 and Windows NT.
497
 
        \e {You do not need different binaries to support Unicode.}
498
 
    \endlist
499
 
 
500
 
    \section2 Mac OS X
501
 
 
502
 
    For details on Mac-specific translation, refer to the Qt/Mac Specific Issues
503
 
    document \l{Qt for Mac OS X - Specific Issues#Translating the Application Menu and Native Dialogs}{here}.
504
 
 
505
 
    \section1 Relevant Qt Classes
506
 
 
507
 
    These classes are relevant to internationalizing Qt applications.
508
 
*/