MCL/sf/mw/qt: comparison doc/src/internationalization/i18n.qdoc

equal deleted inserted replaced

--1:000000000000
+:1918ee327afb
+/****************************************************************************
+**
+** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
+** All rights reserved.
+** Contact: Nokia Corporation (qt-info@nokia.com)
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:LGPL$
+** No Commercial Usage
+** This file contains pre-release code and may not be distributed.
+** You may use this file in accordance with the terms and conditions
+** contained in the Technology Preview License Agreement accompanying
+** this package.
+**
+** GNU Lesser General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU Lesser
+** General Public License version 2.1 as published by the Free Software
+** Foundation and appearing in the file LICENSE.LGPL included in the
+** packaging of this file.  Please review the following information to
+** ensure the GNU Lesser General Public License version 2.1 requirements
+** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
+**
+** In addition, as a special exception, Nokia gives you certain additional
+** rights.  These rights are described in the Nokia Qt LGPL Exception
+** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
+**
+** If you have questions regarding the use of this file, please contact
+** Nokia at qt-info@nokia.com.
+**
+**
+**
+**
+**
+**
+**
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+/*!
+\group i18n
+\title Qt Classes for Internationalization
+See \l{Internationalization with Qt} for information on how to use these classes
+in your applications.
+*/
+/*!
+\page internationalization.html
+\title Internationalization with Qt
+\brief Information about Qt's support for internationalization and multiple languages.
+\keyword internationalization
+\keyword i18n
+The internationalization of an application is the process of making
+the application usable by people in countries other than one's own.
+\tableofcontents
+\section1 Relevant Qt Classes and APIs
+These classes support internationalizing of Qt applications.
+\annotatedlist i18n
+\section1 Languages and Writing Systems
+In some cases internationalization is simple, for example, making a US
+application accessible to Australian or British users may require
+little more than a few spelling corrections. But to make a US
+application usable by Japanese users, or a Korean application usable
+by German users, will require that the software operate not only in
+different languages, but use different input techniques, character
+encodings and presentation conventions.
+Qt tries to make internationalization as painless as possible for
+developers. All input widgets and text drawing methods in Qt offer
+built-in support for all supported languages. The built-in font engine
+is capable of correctly and attractively rendering text that contains
+characters from a variety of different writing systems at the same
+time.
+Qt supports most languages in use today, in particular:
+\list
+\o All East Asian languages (Chinese, Japanese and Korean)
+\o All Western languages (using Latin script)
+\o Arabic
+\o Cyrillic languages (Russian, Ukrainian, etc.)
+\o Greek
+\o Hebrew
+\o Thai and Lao
+\o All scripts in Unicode 4.0 that do not require special processing
+\endlist
+On Windows, Unix/X11 with FontConfig (client side font support)
+and Qt for Embedded Linux the following languages are also supported:
+\list
+\o Bengali
+\o Devanagari
+\o Dhivehi (Thaana)
+\o Gujarati
+\o Gurmukhi
+\o Kannada
+\o Khmer
+\o Malayalam
+\o Myanmar
+\o Syriac
+\o Tamil
+\o Telugu
+\o Tibetan
+\endlist
+Many of these writing systems exhibit special features:
+\list
+\o \bold{Special line breaking behavior.} Some of the Asian languages are
+written without spaces between words. Line breaking can occur either
+after every character (with exceptions) as in Chinese, Japanese and
+Korean, or after logical word boundaries as in Thai.
+\o \bold{Bidirectional writing.} Arabic and Hebrew are written from right to
+left, except for numbers and embedded English text which is written
+left to right. The exact behavior is defined in the
+\l{http://www.unicode.org/unicode/reports/tr9/}{Unicode Technical Annex #9}.
+\o \bold{Non-spacing or diacritical marks (accents or umlauts in European
+languages).} Some languages such as Vietnamese make extensive use of
+these marks and some characters can have more than one mark at the
+same time to clarify pronunciation.
+\o \bold{Ligatures.} In special contexts, some pairs of characters get
+replaced by a combined glyph forming a ligature. Common examples are
+the fl and fi ligatures used in typesetting US and European books.
+\endlist
+Qt tries to take care of all the special features listed above. You
+usually don't have to worry about these features so long as you use
+Qt's input widgets (e.g. QLineEdit, QTextEdit, and derived classes)
+and Qt's display widgets (e.g. QLabel).
+Support for these writing systems is transparent to the
+programmer and completely encapsulated in \l{rich text
+processing}{Qt's text engine}. This means that you don't need to
+have any knowledge about the writing system used in a particular
+language, except for the following small points:
+\list
+\o QPainter::drawText(int x, int y, const QString &str) will always
+draw the string with its left edge at the position specified with
+the x, y parameters. This will usually give you left aligned strings.
+Arabic and Hebrew application strings are usually right
+aligned, so for these languages use the version of drawText() that
+takes a QRect since this will align in accordance with the language.
+\o When you write your own text input controls, use QTextLayout.
+In some languages (e.g. Arabic or languages from the Indian
+subcontinent), the width and shape of a glyph changes depending on the
+surrounding characters, which QTextLayout takes into account.
+Writing input controls usually requires a certain knowledge of the
+scripts it is going to be used in. Usually the easiest way is to
+subclass QLineEdit or QTextEdit.
+\endlist
+The following sections give some information on the status of the
+internationalization (i18n) support in Qt. See also the \l{Qt
+Linguist manual}.
+\section1 Step by Step
+Writing cross-platform international software with Qt is a gentle,
+incremental process. Your software can become internationalized in
+the following stages:
+\section2 Use QString for All User-Visible Text
+Since QString uses the Unicode 4.0 encoding internally, every
+language in 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 \c{char *} to QString conversion overhead.
+Strings that are in "programmer space" (such as QObject names
+and file format texts) need not use QString; the traditional
+\c{char *} or the QByteArray class will suffice.
+You're unlikely to notice that you are using Unicode;
+QString, and QChar are just like easier versions of the crude
+\c{const char *} and char from traditional C.
+\section2 Use tr() for All Literal Text
+Wherever your program uses "quoted text" for text that will
+be presented to the user, ensure that it is processed by the \l
+QCoreApplication::translate() function. Essentially all that is necessary
+to achieve this is to use QObject::tr(). For example, assuming the
+\c LoginWidget is a subclass of QWidget:
+\snippet doc/src/snippets/code/doc_src_i18n.qdoc 0
+This accounts for 99% of the user-visible strings you're likely to
+write.
+If the quoted text is not in a member function of a
+QObject subclass, use either the tr() function of an
+appropriate class, or the QCoreApplication::translate() function
+directly:
+\snippet doc/src/snippets/code/doc_src_i18n.qdoc 1
+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 \c lupdate utility described below.
+The macros expand to just the text (without the context).
+Example of QT_TR_NOOP():
+\snippet doc/src/snippets/code/doc_src_i18n.qdoc 2
+Example of QT_TRANSLATE_NOOP():
+\snippet doc/src/snippets/code/doc_src_i18n.qdoc 3
+If you disable the \c{const char *} to QString automatic
+conversion by compiling your software with the macro \c
+QT_NO_CAST_FROM_ASCII defined, you'll be very likely to catch any
+strings you are missing. See QString::fromLatin1() for more
+information. Disabling the conversion can make programming a bit
+cumbersome.
+If your source language uses characters outside Latin1, you
+might find QObject::trUtf8() more convenient than
+QObject::tr(), as tr() depends on the
+QTextCodec::codecForTr(), which makes it more fragile than
+QObject::trUtf8().
+\section2 Use QKeySequence() for Accelerator Values
+Accelerator values such as Ctrl+Q or Alt+F need to be translated
+too. If you hardcode Qt::CTRL + Qt::Key_Q for "quit" in your
+application, translators won't be able to override it. The
+correct idiom is
+\snippet examples/mainwindows/application/mainwindow.cpp 20
+\section2 Use QString::arg() for Dynamic Text
+The QString::arg() functions offer a simple means for substituting
+arguments:
+\snippet doc/src/snippets/code/doc_src_i18n.qdoc 4
+In some languages the order of arguments may need to change, and this
+can easily be achieved by changing the order of the % arguments. For
+example:
+\snippet doc/src/snippets/code/doc_src_i18n.qdoc 5
+produces the correct output in English and Norwegian:
+\snippet doc/src/snippets/code/doc_src_i18n.qdoc 6
+\section2 Produce Translations
+Once you are using tr() throughout an application, you can start
+producing translations of the user-visible text in your program.
+The \l{Qt Linguist manual} provides further information about
+Qt's translation tools, \e{Qt Linguist}, \c lupdate and \c
+lrelease.
+Translation of a Qt application is a three-step process:
+\list 1
+\o Run \c lupdate 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 and the \c{QT_TR*_NOOP()} macros described above and
+produces TS files (usually one per language).
+\o Provide translations for the source texts in the TS file, using
+\e{Qt Linguist}. Since TS files are in XML format, you can also
+edit them by hand.
+\o Run \c lrelease to obtain a light-weight message file (a QM
+file) from the TS file, suitable only for end use. Think of the TS
+files as "source files", and QM files 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.
+\endlist
+Typically, you will repeat these steps for every release of your
+application. The \c lupdate utility does its best to reuse the
+translations from previous releases.
+Before you run \c lupdate, you should prepare a project file. Here's
+an example project file (\c .pro file):
+\snippet doc/src/snippets/code/doc_src_i18n.qdoc 7
+When you run \c lupdate or \c lrelease, you must give the name of the
+project file as a command-line argument.
+In this example, four exotic languages are supported: Danish,
+Finnish, Norwegian and Swedish. If you use \l{qmake}, you usually
+don't need an extra project file for \c lupdate; your \c qmake
+project file will work fine once you add the \c TRANSLATIONS
+entry.
+In your application, you must \l QTranslator::load() the translation
+files appropriate for the user's language, and install them using \l
+QCoreApplication::installTranslator().
+\c linguist, \c lupdate and \c lrelease are installed in the \c bin
+subdirectory of the base directory Qt is installed into. Click Help|Manual
+in \e{Qt Linguist} to access the user's manual; it contains a tutorial
+to get you started.
+\target qt-itself
+Qt itself contains over 400 strings that will also need to be
+translated into the languages that you are targeting. You will find
+translation files for French, German and Simplified Chinese in
+\c{$QTDIR/translations}, as well as a template for translating to
+other languages. (This directory also contains some additional
+unsupported translations which may be useful.)
+Typically, your application's \c main() function will look like
+this:
+\snippet doc/src/snippets/code/doc_src_i18n.qdoc 8
+Note the use of QLibraryInfo::location() to locate the Qt translations.
+Developers should request the path to the translations at run-time by
+passing QLibraryInfo::TranslationsPath to this function instead of
+using the \c QTDIR environment variable in their applications.
+\section2 Support for Encodings
+The QTextCodec class and the facilities in QTextStream make it easy to
+support many input and output encodings for your users' data. When an
+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.
+The application may occasionally require encodings other than the
+default local 8-bit encoding. For example, an application in a
+Cyrillic KOI8-R locale (the de-facto standard locale in Russia) might
+need to output Cyrillic in the ISO 8859-5 encoding. Code for this
+would be:
+\snippet doc/src/snippets/code/doc_src_i18n.qdoc 9
+For converting Unicode to local 8-bit encodings, a shortcut is
+available: the QString::toLocal8Bit() function returns such 8-bit
+data. Another useful shortcut is QString::toUtf8(), which returns
+text in the 8-bit UTF-8 encoding: this perfectly preserves
+Unicode information while looking like plain ASCII if the text is
+wholly ASCII.
+For converting the other way, there are the QString::fromUtf8() and
+QString::fromLocal8Bit() convenience functions, or the general code,
+demonstrated by this conversion from ISO 8859-5 Cyrillic to Unicode
+conversion:
+\snippet doc/src/snippets/code/doc_src_i18n.qdoc 10
+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 (UTF-16 or
+UTF-8) is 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 QTextCodec::codecForLocale(), 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()).
+Qt supports most of the more frequently used encodings natively. For a
+complete list of supported encodings see the \l QTextCodec
+documentation.
+In some cases and for less frequently used encodings it may be
+necessary to write your own QTextCodec subclass. Depending on the
+urgency, it may be useful to contact Qt's technical support team or
+ask on the \c qt-interest mailing list to see if someone else is
+already working on supporting the encoding.
+\keyword localization
+\section2 Localize
+Localization is the process of adapting to local conventions, for
+example presenting dates and times using the locally preferred
+formats. Such localizations can be accomplished using appropriate tr()
+strings.
+\snippet doc/src/snippets/code/doc_src_i18n.qdoc 11
+In the example, for the US we would leave the translation of
+"AMPM" as it is and thereby use the 12-hour clock branch; but in
+Europe we would translate it as something else and this will make
+the code use the 24-hour clock branch.
+For localized numbers use the QLocale class.
+Localizing images is not recommended. Choose clear icons that are
+appropriate for all localities, rather than relying on local puns or
+stretched metaphors. The exception is for images of left and right
+pointing arrows which may need to be reversed for Arabic and Hebrew
+locales.
+\section1 Dynamic Translation
+Some applications, such as Qt Linguist, must be able to support changes
+to the user's language settings while they are still running. To make
+widgets aware of changes to the installed QTranslators, reimplement the
+widget's \l{QWidget::changeEvent()}{changeEvent()} function to check whether
+the event is a \l{QEvent::LanguageChange}{LanguageChange} event, and update
+the text displayed by widgets using the \l{QObject::tr()}{tr()} function
+in the usual way. For example:
+\snippet doc/src/snippets/code/doc_src_i18n.qdoc 12
+All other change events should be passed on by calling the default
+implementation of the function.
+The list of installed translators might change in reaction to a
+\l{QEvent::LocaleChange}{LocaleChange} event, or the application might
+provide a user interface that allows the user to change the current
+application language.
+The default event handler for QWidget subclasses responds to the
+QEvent::LanguageChange event, and will call this function when necessary;
+other application components can also force widgets to update themselves
+by posting the \l{QEvent::LanguageChange}{LanguageChange} event to them.
+\section1 Translating Non-Qt Classes
+It is sometimes necessary to provide internationalization support for
+strings used in classes that do not inherit QObject or use the Q_OBJECT
+macro to enable translation features. Since Qt translates strings at
+run-time based on the class they are associated with and \c lupdate
+looks for translatable strings in the source code, non-Qt classes must
+use mechanisms that also provide this information.
+One way to do this is to add translation support to a non-Qt class
+using the Q_DECLARE_TR_FUNCTIONS() macro; for example:
+\snippet doc/src/snippets/i18n-non-qt-class/myclass.h 0
+\dots
+\snippet doc/src/snippets/i18n-non-qt-class/myclass.h 1
+This provides the class with \l{QObject::}{tr()} functions that can
+be used to translate strings associated with the class, and makes it
+possible for \c lupdate to find translatable strings in the source
+code.
+Alternatively, the QCoreApplication::translate() function can be called
+with a specific context, and this will be recognized by \c lupdate and
+Qt Linguist.
+\section1 System Support
+Some of the operating systems and windowing systems that Qt runs on
+only have limited support for Unicode. The level of support available
+in the underlying system has some influence on the support that Qt can
+provide on those platforms, although in general Qt applications need
+not be too concerned with platform-specific limitations.
+\section2 Unix/X11
+\list
+\o  Locale-oriented fonts and input methods. Qt hides these and
+provides Unicode input and output.
+\o  Filesystem conventions such as
+\l{http://www.ietf.org/rfc/rfc2279.txt}{UTF-8}
+are under development in some Unix variants. All Qt file
+functions allow Unicode, but convert filenames to the local
+8-bit encoding, as this is the Unix convention (see
+QFile::setEncodingFunction() to explore alternative
+encodings).
+\o  File I/O defaults to the local 8-bit encoding,
+with Unicode options in QTextStream.
+\o  Many Unix distributions contain only partial support for some locales.
+For example, if you have a \c /usr/share/locale/ja_JP.EUC directory,
+this does not necessarily mean you can display Japanese text; you also
+need JIS encoded fonts (or Unicode fonts), and the
+\c /usr/share/locale/ja_JP.EUC directory needs to be complete. For
+best results, use complete locales from your system vendor.
+\endlist
+\section2 Windows
+\list
+\o  Qt provides full Unicode support, including input methods, fonts,
+clipboard, drag-and-drop and file names.
+\o  File I/O defaults to Latin1, 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.
+\o  Unlike programs written with MFC or plain winlib, Qt programs
+are portable between Windows 98 and Windows NT.
+\e {You do not need different binaries to support Unicode.}
+\endlist
+\section2 Mac OS X
+For details on Mac-specific translation, refer to the Qt/Mac Specific Issues
+document \l{Qt for Mac OS X - Specific Issues#Translating the Application Menu and Native Dialogs}{here}.
+*/