diff -r dee5afe5301f -r 3f74d0d4af4c doc/src/internationalization/i18n.qdoc --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/src/internationalization/i18n.qdoc Thu Apr 08 14:19:33 2010 +0300 @@ -0,0 +1,786 @@ +/**************************************************************************** +** +** Copyright (C) 2010 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. + \nextpage Writing Source Code for Translation + + \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 5.1 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 + \o N'Ko + \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 5.1 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. + + \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 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}. +*/ + +/*! + \page i18n-source-translation.html + \title Writing Source Code for Translation + \ingroup i18n + \previouspage Internationalization with Qt + \contentspage 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 + + \section1 The Basics + + Developers use the \l{QObject::}{tr()} function to obtain translated text + for their classes, typically for display purposes. This function is also + used to indicate which text strings in an application are translatable. + + 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 the + \l{#Enabling Translation}{Enabling Translation} section below. + + \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: + + \snippet mainwindows/sdi/mainwindow.h class definition with macro + \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: + + \snippet mainwindows/sdi/mainwindow.cpp implicit tr context + \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 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 doc/src/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 Translator Comments + + Developers can include information about each translatable string to + help translators with the translation process. These are extracted + when \l 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 doc/src/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 \l 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{//= } + + 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{//~ } + + 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 doc/src/snippets/code/src_corelib_kernel_qobject.cpp meta data + + Meta-data appearing right in front of a magic TRANSLATOR comment 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 doc/src/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 Character Encodings + + You can set the encoding for the source text by calling QTextCodec::setCodecForTr(). + By default, the source text is assumed to be in Latin-1 encoding. + + \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 doc/src/snippets/code/src_corelib_kernel_qobject.cpp 18 + + The table below shows what string is returned depending on the + active translation: + + \table + \header \o \o{3,1} Active Translation + \header \o \a n \o No Translation \o French \o English + \row \o 0 \o "0 message(s) saved" \o "0 message sauvegard\unicode{0xE9}" \o "0 message\bold{s} saved" + \row \o 1 \o "1 message(s) saved" \o "1 message sauvegard\unicode{0xE9}" \o "1 message saved" + \row \o 2 \o "2 message(s) saved" \o "2 message\bold{s} sauvegard\unicode{0xE9}\bold{s}" \o "2 message\bold{s} saved" + \row \o 37 \o "37 message(s) saved" \o "37 message\bold{s} sauvegard\unicode{0xE9}\bold{s}" \o "37 message\bold{s} saved" + \endtable + + This idiom is more flexible than the traditional approach; e.g., + + \snippet doc/src/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. + See the \l{Qt Linguist Manual} for details. + + 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 "C" 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 Enabling Translation + + 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. + + \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 i18n + \previouspage Writing Source Code for Translation + \contentspage Internationalization with Qt + \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 \o Language \o Rule 1 \o Rule 2 \o Rule 3 + \row \o English \o \c{n == 1} + \o \e{otherwise} \o N/A + \row \o French \o \c{n < 2} + \o \e{otherwise} \o N/A + \row \o Czech \o \c{n % 100 == 1} + \o \c{n % 100 >= 2 && n % 100 <= 4} + \o \e{otherwise} + \row \o Irish \o \c{n == 1} + \o \c{n == 2} \o \e{otherwise} + \row \o Latvian \o \c{n % 10 == 1&& n % 100 != 11} + \o \c{n != 0} \o \e{otherwise} + \row \o Lithuanian \o \c{n % 10 == 1&& n % 100 != 11} + \o \c{n % 100 != 12 && n % 10 == 2} + \o \e{otherwise} + \row \o Macedonian \o \c{n % 10 == 1} + \o \c{n % 10 == 2} \o \e{otherwise} + \row \o Polish \o \c{n == 1} + \o \c{n % 10 >= 2 && n % 10 <= 4 + && (n % 100 < 10 || n % 100 > 20)} + \o \e{otherwise} + \row \o Romanian \o \c{n == 1} + \o \c{n == 0|| (n % 100 >= 1 && n % 100 <= 20)} + \o \e{otherwise} + \row \o Russian \o \c{n % 10 == 1&& n % 100 != 11} + \o \c{n % 10 >= 2 && n % 10 <= 4 + && (n % 100 < 10 || n % 100 > 20)} + \o \e{otherwise} + \row \o Slovak \o \c{n == 1} \o \c{n >= 2 && n <= 4} + \o \e{otherwise} + \row \o Japanese \o \e{otherwise} \o N/A \o N/A + \endtable + + The rules themselves are not documented and are internal to Qt Linguist and \c lrelease. +*/