| /**************************************************************************** |
| ** |
| ** Copyright (C) 2019 The Qt Company Ltd. |
| ** Contact: https://www.qt.io/licensing/ |
| ** |
| ** 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 The Qt Company. For licensing terms |
| ** and conditions see https://www.qt.io/terms-conditions. For further |
| ** information use the contact form at https://www.qt.io/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: https://www.gnu.org/licenses/fdl-1.3.html. |
| ** $QT_END_LICENSE$ |
| ** |
| ****************************************************************************/ |
| |
| /*! |
| \group i18n |
| \brief How to internationalize your Qt application. |
| \title Qt Classes for Internationalization |
| |
| See \l{Internationalization with Qt} for information on how to use these classes |
| in your applications. |
| */ |
| |
| /*! |
| \group internationalization |
| \title Internationalization with Qt |
| \brief Information about Qt's support for internationalization and multiple languages. |
| \nextpage Writing Source Code for Translation |
| |
| |
| \keyword internationalization |
| \keyword i18n |
| |
| The \e internationalization and \e localization of an application are the |
| processes of adapting the application to different languages, regional |
| differences and technical requirements of a target market. |
| Internationalization means designing a software application so that it can |
| be adapted to various languages and regions without engineering changes. |
| Localization means adapting internationalized software for a specific region |
| or language by adding locale-specific components (such as date, time, and |
| number formats) and translating text. |
| |
| \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 controls 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 |
| \li All East Asian languages (Chinese, Japanese and Korean) |
| \li All Western languages (using Latin script) |
| \li Arabic |
| \li Cyrillic languages (Russian, Ukrainian, etc.) |
| \li Greek |
| \li Hebrew |
| \li Thai and Lao |
| \li All scripts in Unicode 6.2 that do not require special processing |
| \li Bengali |
| \li Burmese (Myanmar) |
| \li Devanagari |
| \li Gujarati |
| \li Gurmukhi |
| \li Kannada |
| \li Khmer |
| \li Malayalam |
| \li Tamil |
| \li Telugu |
| \li Tibetan |
| \endlist |
| |
| The list above is supported and will work on all platforms as long as |
| the system has fonts to render these writing systems installed. |
| |
| On Windows, Linux and Unix with FontConfig (client side font support) |
| the following languages are also supported: |
| \list |
| \li Dhivehi (Thaana) |
| \li Syriac |
| \li N'Ko |
| \endlist |
| |
| On \macos, the following languages are also supported: |
| \list |
| \li Oriya |
| \li Sinhala |
| \endlist |
| |
| Many of these writing systems exhibit special features: |
| |
| \list |
| |
| \li \b{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. |
| |
| \li \b{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}. |
| |
| \li \b{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. |
| |
| \li \b{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 controls (e.g. QLineEdit, QTextEdit, and derived classes |
| or the Quick TextInput item) and Qt's display controls (e.g. QLabel |
| and Qt Quick's Text item). |
| |
| 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 usually need to have any knowledge of the writing |
| system used in a particular language, unless you want to write your own text |
| input controls. In some languages, such as Arabic or languages from the |
| Indian subcontinent, the width and shape of a glyph changes depending on the |
| surrounding characters. To take this into account, use QTextLayout. |
| Writing input controls also requires some knowledge of the scripts they are |
| going to be used in. Usually, the easiest way is to subclass QLineEdit or |
| QTextEdit. |
| |
| For more information about how to internationalize source code, see |
| \l{Writing Source Code for Translation} and |
| \l{Internationalization and Localization with Qt Quick}. |
| |
| \section1 Producing Translations |
| |
| Qt provides excellent support for translating Qt C++ and Qt Quick |
| applications into local languages. Release managers, translators, and |
| developers can use the Qt translation tools to accomplish their tasks. |
| |
| The Qt translation tools, Qt Linguist, \c lupdate, and \c lrelease are |
| installed in the \c bin subdirectory of the base directory Qt is installed |
| into. For more information about using them, see the \l{Qt Linguist Manual}. |
| |
| \target qt-itself |
| Qt itself contains several thousands of strings that will also need to be |
| translated into the languages that you are targeting. You will find |
| a number of translation files in the qttranslations repository. |
| Before you start translating Qt, read the wiki page |
| \l{external: Translating Qt Into Other Languages} |
| {Translating Qt Into Other Languages}. |
| |
| \section1 Enabling Translation |
| |
| Typically, your application's \c main() function will look like |
| this: |
| |
| \snippet snippets/code/doc_src_i18n.cpp 8 |
| |
| For a translation-aware application, a QTranslator object is created, then a |
| translation is loaded according to the user's preferred UI display locale at |
| runtime, and finally, the translator object is installed into the |
| application. |
| |
| \section1 Locating Qt Translations |
| |
| You can also use QLibraryInfo::location() to locate the translations for the |
| Qt modules used. You can request the path to the translations at run-time by |
| passing QLibraryInfo::TranslationsPath to this function. |
| |
| \section2 Available Catalogs |
| |
| The Qt translation catalogs are located in the \c qttranslations repository. |
| |
| \warning Qt translations are contributed by the Qt community, and provided |
| without any guarantees. Translations migh be missing, outdated, or entirely |
| incorrect, up to the point of being malicious. It is recommended that you |
| audit any translations you ship. |
| |
| The \c qt_ meta catalog contains the still-existing Qt translations that |
| were included in the \c qt_ catalog in Qt 4. It was created to make porting |
| applications from Qt 4 to Qt 5 easier. The meta catalog depends on |
| translations that might be absent, because they belong to unnecessary or |
| deprecated modules, which might cause the loading of the translations to |
| fail. If you use modules that are new in Qt 5 in your application, you must |
| specify the names of the catalogs for those modules even if you use the |
| meta catalog. |
| |
| The following table lists the translation catalogs available for the Qt |
| modules and tools in Qt. |
| |
| \table |
| \header |
| \li Qt Module or Tool |
| \li Catalog |
| \row |
| \li \l {Qt Assistant Manual}{Qt Assistant} |
| \li \c assistant_ |
| \row |
| \li \l [QtBluetooth]{Qt Bluetooth} |
| \li \c qtconnectivity_ |
| \row |
| \li \l [QtConcurrent]{Qt Concurrent} |
| \li \c qtbase_ |
| \row |
| \li \l [QtCore]{Qt Core} |
| \li \c qtbase_ |
| \row |
| \li \l [QtDBus]{Qt D-Bus} |
| \li \c qtbase_ |
| \row |
| \li \l {Qt Designer} |
| \li \c designer_ |
| \row |
| \li \l [QtGui]{Qt GUI} |
| \li \c qtbase_ |
| \row |
| \li \l {Qt Help} |
| \li \c qt_help_ |
| \row |
| \li \l {Qt Linguist Manual}{Qt Linguist} |
| \li \c linguist_ |
| \row |
| \li \l [QtLocation]{Qt Location} |
| \li \c qtlocation_ |
| \row |
| \li \l [QtMultimedia]{Qt Multimedia} |
| \li \c qtmultimedia_ |
| \row |
| \li \l [QtMultimediaWidgets]{Qt Multimedia Widgets} |
| \li \c qtmultimedia_ |
| \row |
| \li \l[QtNfc]{Qt NFC} |
| \li \c qtconnectivity_ |
| \row |
| \li \l[Qt Network]{Qt Network} |
| \li \c qtbase_ |
| \row |
| \li \l [QtPositioning]{Qt Positioning} |
| \li \c qtlocation_ |
| \row |
| \li \l [QtPrintSupport]{Qt Print Support} |
| \li \c qtbase_ |
| \row |
| \li \l {Qt QML} |
| \li \c qtdeclarative_ |
| \row |
| \li \l {Qt Quick} |
| \li \c qtdeclarative_ |
| \row |
| \li \l {Qt Quick Controls} |
| \li \c qtquickcontrols2_ |
| \row |
| \li \l {Qt Quick Widgets C++ Classes}{Qt Quick Widgets} |
| \li \c qtdeclarative_ |
| \row |
| \li \l [QtSerialPort]{Qt Serial Port} |
| \li \c qtserialport_ |
| \row |
| \li \l [QtSql]{Qt SQL} |
| \li \c qtbase_ |
| \row |
| \li \l [QtWebEngine]{Qt WebEngine} |
| \li \c qtwebengine_ |
| \row |
| \li \l [QtWebSockets]{Qt WebSockets} |
| \li \c qtwebsockets_ |
| \row |
| \li \l [QtWidgets]{Qt Widgets} |
| \li \c qtbase_ |
| \endtable |
| |
| \omit |
| The following modules are not listed above because they are deprecated, |
| documented as a part of another module, QPA modules, or not translated |
| for some reason. |
| |
| \list |
| \row \li QtEglFSDeviceIntegration \li \c qtbase_ \li QPA |
| \row \li QtMultimediaGstTools \li \c qtmultimedia_ \li Qt Multimedia |
| \row \li QtMultimediaQuick \li \c qtmultimedia_ \li Qt Multimedia |
| \row \li QtOpenGL \li \c qtbase_ \li Deprecated |
| \row \li QtOpenGLExtensions \li \c qtbase_ \li Deprecated |
| \row \li QtPacketProtocol \li \c qtdeclarative_ \li Qt Quick |
| \row \li QtPositioningQuick \li \c qtlocation_ \li Qt Positioning |
| \row \li QtQmlDebug \li \c qtdeclarative_ \li Qt Quick |
| \row \li QtQmlModels \li \c qtdeclarative_ \li Qt Quick |
| \row \li QtQmlWorkerScript \li \c qtdeclarative_ \li Qt Quick |
| \row \li QtQuickParticles \li \c qtdeclarative_ \li Qt Quick |
| \row \li QtQuickShapes \li \c qtdeclarative_ \li Qt Quick |
| \row \li QtQuickTemplates2 \li \c qtquickcontrols2_ \li Qt Quick Controls 2 |
| \row \li QtQuickTest \li \c qtdeclarative_ \li Not translated |
| \row \li QtQuickWidgets \li \c qtdeclarative_ \li Qt Quick |
| \row \li QtScript \li \c qtscript_ \li Deprecated |
| \row \li QtScriptTools \li \c qtscript_ \li Deprecated |
| \row \li QtTest \li \c qtbase_ \li Not translated |
| \row \li QtWebEngineCore \li \c qtwebengine_ \li Qt WebEngine |
| \row \li QtWebEngineWidgets \li \c qtwebengine_ \li Qt WebEngine |
| \row \li QtXml \li \c qtbase_ \li Deprecated |
| \row \li QtXmlPatterns \li \c qtxmlpatterns_ \li Deprecated |
| \endlist |
| \endomit |
| |
| \section2 Example: Basic Qt Modules |
| |
| For example, to locate translations for basic Qt modules, such as Qt Core, |
| Qt GUI, Qt Network, and Qt Widgets, add the following code to the \c main() |
| function: |
| |
| \snippet snippets/code/doc_src_i18n.cpp 14 |
| |
| \section1 Support for Encodings |
| |
| The QTextCodec class and the facilities in QTextStream make it easy to |
| support many legacy 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 external 8-bit data. QTextCodec::codecForLocale() |
| returns a codec that can be used to convert between this locale encoding |
| and Unicode. |
| |
| 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 snippets/code/doc_src_i18n.cpp 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 \l{http://www.ietf.org/rfc/rfc2279.txt}{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 snippets/code/doc_src_i18n.cpp 10 |
| |
| Unicode I/O should be used as this maximizes the portability |
| of documents between users around the world. In many cases it is |
| however still necessary to support other encodings as your users will |
| need to process existing documents. The most important additional |
| 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 |
| |
| \section1 Localizing Numbers, Dates, Times and Currency |
| |
| Localization is the process of adapting to local conventions, for |
| example presenting dates and times using the locally preferred |
| formats. For localized numbers, dates, times and currency strings, 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 QTranslator objects, 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 snippets/code/doc_src_i18n.cpp 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. |
| |
| \l{QEvent::LanguageChange}{LanguageChange} events are posted when a new |
| translation is installed using the QCoreApplication::installTranslator() |
| function. Additionally, other application components can also force |
| widgets to update themselves by posting LanguageChange events to them. |
| |
| \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 |
| \li Locale-oriented fonts and input methods. Qt hides these and |
| provides Unicode input and output. |
| \li Filesystem conventions such as UTF-8 |
| are today used by default in most 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). |
| \li File I/O defaults to the local 8-bit encoding, |
| with Unicode options in QTextStream. |
| \li Some older 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 to have Japanese fonts installed, 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 Linux |
| |
| \list |
| \li Qt provides full Unicode support, including input methods, fonts, |
| clipboard, drag-and-drop. |
| \li The file system is usually encoded in UTF-8 on all modern Linux |
| distributions and should not pose a problem. File I/O defaults to UTF-8. |
| \endlist |
| |
| \section2 Windows |
| |
| \list |
| \li Qt provides full Unicode support, including input methods, fonts, |
| clipboard, drag-and-drop and file names. |
| \li 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. |
| \endlist |
| |
| \section2 \macos |
| |
| For details on \macos-specific translation, refer to the Qt for macOS issues |
| document \l{Qt for macOS - Specific Issues#Translating the Application Menu and Native Dialogs}{here}. |
| |
| \section1 Related Pages |
| */ |
| |
| /*! |
| \page i18n-source-translation.html |
| \title Writing Source Code for Translation |
| \ingroup internationalization |
| \previouspage Internationalization with Qt |
| \nextpage Translation Rules for Plurals |
| \brief How to write source code in a way that makes it possible for user-visible text to be translated. |
| |
| \tableofcontents |
| |
| Writing cross-platform international software with Qt is a gentle, |
| incremental process. Your software can become internationalized in |
| the stages described in the following sections. |
| For more information about internalizing Qt Quick application, see |
| \l{Internationalization and Localization with Qt Quick}. |
| |
| \section1 Using QString for All User-Visible Text |
| |
| Since QString uses the Unicode 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 easier versions of the crude |
| \c{const char *} and \c char from traditional C. |
| |
| \c{char *} strings in source code are assumed to be |
| \l{http://www.ietf.org/rfc/rfc2279.txt}{UTF-8} encoded when being |
| implicitly converted to a QString. If your C string literal |
| uses a different encoding, use QString::fromLatin1() or QTextCodec |
| to convert the literal to a Unicode encoded QString. |
| |
| \section1 Using tr() for All Literal Text |
| |
| Wherever your program uses a string literal (quoted 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 the \l{QObject::}{tr()} function to obtain |
| translated text for your classes, typically for display purposes. This |
| function is also used to indicate which text strings in an application are |
| translatable. |
| |
| For example, assuming the \c LoginWidget is a subclass of QWidget: |
| |
| \snippet snippets/code/doc_src_i18n.cpp 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 snippets/code/doc_src_i18n.cpp 1 |
| |
| Qt indexes each translatable string by the \e{translation context} it is |
| associated with; this is generally the name of the QObject subclass it is |
| used in. |
| |
| Translation contexts are defined for new QObject-based classes by the use |
| of the Q_OBJECT macro in each new class definition. |
| |
| When tr() is called, it looks up the translatable string using a QTranslator |
| object. For translation to work, one or more of these must have been |
| installed on the application object in the way described in |
| \l{Enabling Translation}. |
| |
| Translating strings in QML works exactly the same way as in C++, with the only |
| difference being that you need to call qsTr() instead of \l{QObject::}{tr()}. See also |
| the page on \l{Internationalization and Localization with Qt Quick}. |
| |
| \section1 Defining a Translation Context |
| |
| The translation context for QObject and each QObject subclass is the |
| class name itself. Developers subclassing QObject must use the |
| Q_OBJECT macro in their class definition to override the translation |
| context. This macro sets the context to the name of the subclass. |
| |
| For example, the following class definition includes the Q_OBJECT macro, |
| implementing a new tr() that uses the \c MainWindow context: |
| |
| \code |
| class MainWindow : public QMainWindow |
| { |
| Q_OBJECT |
| |
| public: |
| MainWindow(); |
| \endcode |
| \dots |
| |
| If Q_OBJECT is not used in a class definition, the context will be |
| inherited from the base class. For example, since all QObject-based |
| classes in Qt provide a context, a new QWidget subclass defined without |
| a Q_OBJECT macro will use the \c QWidget context if its tr() function |
| is invoked. |
| |
| \section1 Using tr() to Obtain a Translation |
| |
| The following example shows how a translation is obtained for the |
| class shown in the previous section: |
| |
| \code |
| void MainWindow::createMenus() |
| { |
| fileMenu = menuBar()->addMenu(tr("&File")); |
| \endcode |
| \dots |
| |
| Here, the translation context is \c MainWindow because it is the |
| \c MainWindow::tr() function that is invoked. The text returned |
| by the tr() function is a translation of "&File" obtained from |
| the \c MainWindow context. |
| |
| When Qt's translation tool, \l{Using lupdate}{lupdate}, is used to process |
| a set of source |
| files, the text wrapped in tr() calls is stored in a section of the translation |
| file that corresponds to its translation context. |
| |
| In some situations, it is useful to give a translation context explicitly |
| by fully qualifying the call to tr(); for example: |
| |
| \snippet snippets/code/src_corelib_kernel_qobject.cpp explicit tr context |
| |
| This call obtains the translated text for "Page up" from the \c QScrollBar |
| context. Developers can also use the QCoreApplication::translate() function |
| to obtain a translation for a particular translation context. |
| |
| \section1 Using tr() to Localize Numbers |
| |
| You can localize numbers by using appropriate tr() strings: |
| |
| \snippet snippets/code/doc_src_i18n.cpp 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 to make |
| the code use the 24-hour clock branch. |
| |
| \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 snippets/i18n-non-qt-class/myclass.h 0 |
| \dots |
| \snippet 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 Translator Comments |
| |
| Developers can include information about each translatable string to |
| help translators with the translation process. These are extracted |
| when \c lupdate is used to process the source files. The recommended |
| way to add comments is to annotate the tr() calls in your code with |
| comments of the form: |
| |
| \tt{//: ...} |
| |
| or |
| |
| \tt{\begincomment: ... \endcomment} |
| |
| Examples: |
| |
| \snippet snippets/code/src_corelib_kernel_qobject.cpp 40 |
| |
| In these examples, the comments will be associated with the strings |
| passed to tr() in the context of each call. |
| |
| \section1 Adding Meta-Data to Strings |
| |
| Additional data can be attached to each translatable message. These are |
| extracted when \c lupdate is used to process the source files. The |
| recommended way to add meta-data is to annotate the tr() calls in your code |
| with comments of the form: |
| |
| \tt{//= <id>} |
| |
| This can be used to give the message a unique identifier to support tools |
| which need it. |
| |
| An alternative way to attach meta-data is to use the following syntax: |
| |
| \tt{//~ <field name> <field contents>} |
| |
| This can be used to attach meta-data to the message. The field name should |
| consist of a domain prefix (possibly the conventional file extension of the |
| file format the field is inspired by), a hyphen and the actual field name |
| in underscore-delimited notation. For storage in TS files, the field name |
| together with the prefix "extra-" will form an XML element name. The field |
| contents will be XML-escaped, but otherwise appear verbatim as the |
| element's contents. Any number of unique fields can be added to each |
| message. |
| |
| Example: |
| |
| \snippet snippets/code/src_corelib_kernel_qobject.cpp meta data |
| |
| You can use the keyword \e TRANSLATOR for translator comments. |
| Meta-data appearing right in front of the TRANSLATOR keyword applies to |
| the whole TS file. |
| |
| \section1 Disambiguation |
| |
| If the same translatable string is used in different roles within the same |
| translation context, an additional identifying string may be passed in |
| the call to \l{QObject::}{tr()}. This optional disambiguation argument |
| is used to distinguish between otherwise identical strings. |
| |
| Example: |
| |
| \snippet snippets/code/src_corelib_kernel_qobject.cpp 17 |
| \dots |
| |
| In Qt 4.4 and earlier, this disambiguation parameter was the preferred |
| way to specify comments to translators. |
| |
| \section1 Handling Plurals |
| |
| Some translatable strings contain placeholders for integer values and need |
| to be translated differently depending on the values in use. |
| |
| To help with this problem, developers pass an additional integer argument |
| to the \l{QObject::}{tr()} function, and typically use a special notation |
| for plurals in each translatable string. |
| |
| If this argument is equal or greater than zero, all occurrences of |
| \c %n in the resulting string are replaced with a decimal representation |
| of the value supplied. In addition, the translation used will adapt to the |
| value according to the rules for each language. |
| |
| Example: |
| |
| \snippet snippets/code/src_corelib_kernel_qobject.cpp 18 |
| |
| The table below shows what string is returned depending on the |
| active translation: |
| |
| \table |
| \header \li \li{3,1} Active Translation |
| \header \li \a n \li No Translation \li French \li English |
| \row \li 0 \li "0 message(s) saved" \li "0 message sauvegard\unicode{0xE9}" \li "0 message\b{s} saved" |
| \row \li 1 \li "1 message(s) saved" \li "1 message sauvegard\unicode{0xE9}" \li "1 message saved" |
| \row \li 2 \li "2 message(s) saved" \li "2 message\b{s} sauvegard\unicode{0xE9}\b{s}" \li "2 message\b{s} saved" |
| \row \li 37 \li "37 message(s) saved" \li "37 message\b{s} sauvegard\unicode{0xE9}\b{s}" \li "37 message\b{s} saved" |
| \endtable |
| |
| This idiom is more flexible than the traditional approach; e.g., |
| |
| \snippet snippets/code/src_corelib_kernel_qobject.cpp 19 |
| |
| because it also works with target languages that have several |
| plural forms (e.g., Irish has a special "dual" form that should |
| be used when \c n is 2), and it handles the \e n == 0 case |
| correctly for languages such as French that require the singular. |
| |
| To handle plural forms in the native language, you need to load a |
| translation file for this language, too. The lupdate tool has the |
| \c -pluralonly command line option, which allows the creation of |
| TS files containing only entries with plural forms. |
| |
| See the \l{Qt Quarterly} Article |
| \l{http://doc.qt.io/archives/qq/qq19-plurals.html} |
| {Plural Forms in Translations} for further details on this issue. |
| |
| Instead of \c %n, you can use \c %Ln to produce a localized |
| representation of \a n. The conversion uses the default locale, |
| set using QLocale::setDefault(). (If no default locale was |
| specified, the system wide locale is used.) |
| |
| A summary of the rules used to translate strings containing plurals can be |
| found in the \l{Translation Rules for Plurals} document. |
| |
| \section1 Translating Text That is Outside of a QObject Subclass |
| |
| \section2 Using QCoreApplication::translate() |
| |
| 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 snippets/code/doc_src_i18n.cpp 13 |
| |
| \section2 Using QT_TR_NOOP() and QT_TRANSLATE_NOOP() in C++ |
| |
| 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 tool. The macros expand to |
| just the text (without the context). |
| |
| Example of QT_TR_NOOP(): |
| |
| \snippet snippets/code/doc_src_i18n.cpp 2 |
| |
| Example of QT_TRANSLATE_NOOP(): |
| |
| \snippet snippets/code/doc_src_i18n.cpp 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::fromUtf8() and QString::fromLatin1() |
| for more information. |
| |
| \section1 Using QKeySequence() for Accelerator Values |
| |
| Accelerator values such as Ctrl+Q or Alt+F need to be translated |
| too. If you hardcode \c{Qt::CTRL + Qt::Key_Q} for "quit" in your |
| application, translators won't be able to override it. The |
| correct idiom is: |
| |
| \code |
| exitAct = new QAction(tr("E&xit"), this); |
| exitAct->setShortcuts(QKeySequence::Quit); |
| \endcode |
| |
| \section1 Using Numbered Arguments |
| |
| The QString::arg() functions offer a simple means for substituting |
| arguments: |
| \snippet snippets/code/doc_src_i18n.cpp 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 snippets/code/doc_src_i18n.cpp 5 |
| |
| produces the correct output in English and Norwegian: |
| \snippet snippets/code/doc_src_i18n.qdoc 6 |
| |
| \section1 Further Reading |
| |
| \l{Qt Linguist Manual}, \l{Hello tr() Example}, \l{Translation Rules for Plurals} |
| */ |
| |
| /*! |
| \page i18n-plural-rules.html |
| \title Translation Rules for Plurals |
| \ingroup internationalization |
| \previouspage Writing Source Code for Translation |
| \brief A summary of the translation rules for plurals produced by Qt's i18n tools. |
| |
| The table below shows the specific rules that are produced by Qt Linguist |
| and \c lrelease for a selection of languages. Cells marked \e otherwise |
| indicate the form used when none of the other rules are appropriate for a |
| specific language. |
| |
| \table 80% |
| \header \li Language \li Rule 1 \li Rule 2 \li Rule 3 |
| \row \li English \li \c{n == 1} |
| \li \e{otherwise} \li N/A |
| \row \li French \li \c{n < 2} |
| \li \e{otherwise} \li N/A |
| \row \li Czech \li \c{n % 100 == 1} |
| \li \c{n % 100 >= 2 && n % 100 <= 4} |
| \li \e{otherwise} |
| \row \li Irish \li \c{n == 1} |
| \li \c{n == 2} \li \e{otherwise} |
| \row \li Latvian \li \c{n % 10 == 1&& n % 100 != 11} |
| \li \c{n != 0} \li \e{otherwise} |
| \row \li Lithuanian \li \c{n % 10 == 1&& n % 100 != 11} |
| \li \c{n % 100 != 12 && n % 10 == 2} |
| \li \e{otherwise} |
| \row \li Macedonian \li \c{n % 10 == 1} |
| \li \c{n % 10 == 2} \li \e{otherwise} |
| \row \li Polish \li \c{n == 1} |
| \li \c{n % 10 >= 2 && n % 10 <= 4 |
| && (n % 100 < 10 || n % 100 > 20)} |
| \li \e{otherwise} |
| \row \li Romanian \li \c{n == 1} |
| \li \c{n == 0|| (n % 100 >= 1 && n % 100 <= 20)} |
| \li \e{otherwise} |
| \row \li Russian \li \c{n % 10 == 1&& n % 100 != 11} |
| \li \c{n % 10 >= 2 && n % 10 <= 4 |
| && (n % 100 < 10 || n % 100 > 20)} |
| \li \e{otherwise} |
| \row \li Slovak \li \c{n == 1} \li \c{n >= 2 && n <= 4} |
| \li \e{otherwise} |
| \row \li Japanese \li \e{otherwise} \li N/A \li N/A |
| \endtable |
| |
| The rules themselves are not documented and are internal to Qt Linguist and \c lrelease. |
| */ |