diff options
Diffstat (limited to 'doc/src')
| -rw-r--r-- | doc/src/internationalization/i18n.qdoc | 267 | ||||
| -rw-r--r-- | doc/src/internationalization/linguist-manual.qdoc | 368 | ||||
| -rw-r--r-- | doc/src/snippets/code/doc_src_i18n.qdoc | 2 | ||||
| -rw-r--r-- | doc/src/snippets/code/src_corelib_kernel_qobject.cpp | 3 |
4 files changed, 290 insertions, 350 deletions
diff --git a/doc/src/internationalization/i18n.qdoc b/doc/src/internationalization/i18n.qdoc index e873f4e..1a2839d 100644 --- a/doc/src/internationalization/i18n.qdoc +++ b/doc/src/internationalization/i18n.qdoc @@ -51,6 +51,7 @@ \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 @@ -59,11 +60,11 @@ 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 @@ -516,3 +517,265 @@ 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{//= <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 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. +*/ diff --git a/doc/src/internationalization/linguist-manual.qdoc b/doc/src/internationalization/linguist-manual.qdoc index 5d388f1..3e06a2f 100644 --- a/doc/src/internationalization/linguist-manual.qdoc +++ b/doc/src/internationalization/linguist-manual.qdoc @@ -62,7 +62,7 @@ software engineers and the translator. The chapter describes the use of two tools. The \l{lupdate} tool is used to synchronize source code and translations. The \l{lrelease} tool is used to - create runtime translation files for use by the released + create run-time translation files for use by the released application. The \l{linguist-translators.html}{Translators} chapter is for @@ -119,7 +119,7 @@ \o Phrases that contain variables, for example, "The 25 files selected will take 63 seconds to process", where the two numbers - are inserted programmatically at runtime may need to be reworded + are inserted programmatically at run-time may need to be reworded because in a different language the word order and therefore the placement of the variables may have to change. @@ -147,7 +147,7 @@ \row \o{1,2} \inlineimage wVista-Cert-border-small.png \o \e{Qt Linguist 4.3 is Certified for Windows Vista} - + \row \o Windows Vista and the Windows Vista Start button are trademarks or registered trademarks of Microsoft Corporation in the United States and/or other countries. @@ -508,7 +508,7 @@ translation. The state is reset to \inlineimage linguist-danger.png , and the number of accepted translations in the \e{Items} column of the \l{Context Window} {context list} is decremented by 1. - + \row \o Not Accepted \o \inlineimage linguist-check-off.png @@ -781,7 +781,7 @@ changed. Whichever character (alpha or digit) is chosen, the translation must be in the form "Ctrl+" followed by the upper case character. \e{Qt} will automatically display the correct name at - runtime. As with Alt key accelerators, if the translator changes + run-time. As with Alt key accelerators, if the translator changes the character, the new character must not conflict with any other Ctrl key accelerator. @@ -790,14 +790,14 @@ supported languages, \e {Qt} automatically translates these strings. - \section2 Handling Numbered Arguments + \section2 Handling Numbered Arguments and Plurals Some phrases contain numbered arguments. A numbered argument is a - placeholder that will be replaced with text at runtime. A numbered + placeholder that will be replaced with text at run-time. A numbered argument appears in a source string as a percent sign followed by a digit. Consider an example: \c{After processing file %1, file %2 is next in line}. In this string to be translated, \c{%1} and - \c{%2} are numbered arguments. At runtime, \c{%1} and \c{%2} will + \c{%2} are numbered arguments. At run-time, \c{%1} and \c{%2} will be replaced with the first and next file names respectively. The same numbered arguments must appear in the translation, but not necessarily in the same order. A German translation of the string @@ -808,336 +808,14 @@ of where argument \e{i} appears in the argument sequence in the source string. - \section2 Plurals - - The problem of plurals in output is resolved by using an overload of - the \c tr() function with the signature - \code - QString tr(const char *text, const char *comment, int n); - \endcode - Using built in comparisons for the value of \c n the tr() function will - translate the phrase to the plural form for the target language. - - Different languages have various forms for plurals beyond simply - \e singular and \e plural. The rules for determining which form of the - plural to use are encoded as conditional tests. Below is a table - representing the numbers associated with the forms rather than the - conditional tests themselves. - - - - \table 90% - \header - \o Language - \o Form 1 - \o Form 2 - \o Form 3 - \o Form 4 - \row - \o Arabic - \o 0, 1, 11-102, 111-202... - \o 2 - \o 3-10, 103-110, 203-210... - \o - \row - \o Basque - \o 1 - \o 0, 2-100, 101- - \o - \o - \row - \o Bulgarian - \o 1 - \o 0, 2-100, 101- - \o - \o - \row - \o Catalan - \o 1 - \o 11, 11 000-11 999, 11 000 000-11 999 999... - \o 0, 2-10, 12-10 999, 12-10 999 999... - \o - \row - \o Chinese-CN - \o 0- - \o - \o - \o - \row - \o Chinese-HK - \o 0- - \o - \o - \o - \row - \o Chinese-TW - \o 0- - \o - \o - \o - \row - \o Croation - \o 1, 21, 31, 41, 51, 61, 71, 81, 91, 101... - \o 2-4, 22-24, 32-34, 42-44... - \o 0, 5-20, 25-30, 35-40... - \o - \row - \o Czech - \o 1 - \o 2-4 - \o 0, 5- - \o - \row - \o Danish - \o 1 - \o 0, 2-100, 101- - \o - \o - \row - \o Dutch - \o 1 - \o 0, 2-100, 101- - \o - \o - \row - \o English - \o 1 - \o 0, 2-100, 101- - \o - \o - \row - \o English-US - \o 1 - \o 0, 2-100, 101- - \o - \o - \row - \o Estonian - \o 1 - \o 0, 2-100, 101- - \o - \o - \row - \o Finnish - \o 1 - \o 0, 2-100, 101- - \o - \o - \row - \o French-CA - \o 0, 1 - \o 2-100, 101- - \o - \o - \row - \o French-FR - \o 0, 1 - \o 2-100, 101- - \o - \o - \row - \o Galician - \o 1 - \o 0, 2-100, 101- - \o - \o - \row - \o German - \o 1 - \o 0, 2-100, 101- - \o - \o - \row - \o Greek - \o 1 - \o 0, 2-100, 101- - \o - \o - \row - \o Hebrew - \o 1 - \o 0, 2-100, 101- - \o - \o - \row - \o - \o 1 - \o 0, 2-100, 101- - \o - \o - \row - \o Hungarian - \o 0- - \o - \o - \o - \row - \o Icelandic - \o 1, 21, 31, 41, 51....101, 121, 131... - \o 0, 2-20, 22-30, 32-40...102-120... - \o - \o - \row - \o Indonesian - \o 0- - \o - \o - \o - \row - \o Italian - \o 1 - \o 0, 2-100, 101- - \o - \o - \row - \o Japanese - \o 0- - \o - \o - \o - \row - \o Korean - \o 0- - \o - \o - \o - \row - \o Latvian - \o 0 - \o 1, 21, 31, 41, 51, 61, 71, 81, 91, 101, 131, 141... - \o 2-20, 22-30, 32-40, 42-50...202-220, 222-230... - \o - \row - \o Lithuanian - \o 1, 21, 31, 41, 51...101, 121, 131... - \o 2-9, 22-29, 32-39...102-109, 122-129, 132-139... - \o 0, 10-20, 30, 40, 50...110-120, 130, 140... - \o - \row - \o Malay - \o 0- - \o - \o - \o - \row - \o Norwegian - \o 1 - \o 0, 2-100, 101- - \o - \o - \row - \o Persian - \o 0- - \o - \o - \o - \row - \o Polish - \o 1 - \o 2-4, 22-24, 32-34... - \o 5-21, 25-31, 35-41... - \o - \row - \o Portugese-BR - \o 0, 1 - \o 2-100, 101- - \o - \o - \row - \o Portugese-PT - \o 1 - \o 0, 2-100, 101- - \o - \o - \row - \o Romanian - \o 1 - \o 0, 2-19, 101-119, 201-219... - \o 20-100, 120-200, 220-300... - \o - \row - \o Russian - \o 1, 21, 31, 41, 51, 61, 71, 81, 91, 101... - \o 2-4, 22-24, 32-34... - \o 0, 5-20, 25-30, 35-40... - \o - \row - \o Serbian - \o 1, 21, 31, 41, 51, 61, 71, 81, 91, 101... - \o 2-4, 22-24, 32-34... - \o 0, 5-20, 25-30, 35-40... - \o - \row - \o Slovak - \o 1 - \o 2-4 - \o 0, 5-20, 25-30, 35-40... - \o - \row - \o Slovene - \o 1, 101, 201, 301... - \o 2, 102, 202, 302... - \o 3, 4, 103, 104, 203, 204, 303, 304... - \o 0, 5-100, 105-200, 205-300... - \row - \o Spanish-US - \o 1 - \o 0, 2- - \o - \o - \row - \o Spanish-ES - \o 1 - \o 0, 2- - \o - \o - \row - \o Swedish - \o 1 - \o 0, 2-100, 101- - \o - \o - \row - \o Tagalog - \o 0, 1 - \o 2, 3, 5, 7-8, 10-13, 15, 17-18, 20-23...101...1001 - \o 4, 6, 9, 14, 16, 19, 24, 26, 29...104, 106, 109... - \o - \row - \o Thai - \o 0- - \o - \o - \o - \row - \o Turkish - \o 0- - \o - \o - \o - \row - \o Ukrainian - \o 1, 21, 31, 41, 51, 61, 71, 81, 91, 101... - \o 2-4, 22-24, 32-34... - \o 0, 5-20, 25-30, 35-40... - \o - \row - \o Urdu - \o 1 - \o 0, 2-100, 101- - \o - \o - \row - \o Vietnamese - \o 0- - \o - \o - \o - \endtable - - These rules are embedded within the Qt libraries, there is no need for - the developer to know them. Merely to use the correct \c tr() call. - + The use of numbered arguments is often accompanied by the use of + plurals in the source text. In many languages, the form of the + text will depend on the value shown, and more than one translation + is required. If the developers have marked up the source text in + correct way, fields for each of the possible plural forms will be + available in the translation area. (The + \l{Writing Source Code for Translation#Handling Plurals}{Writing Source Code for Translation} + document contains details about this feature for developers.) \section2 Reusing Translations @@ -1157,7 +835,7 @@ {translation area}, and adapts the number of input fields for plural forms accordingly. If not explicitly set, \QL guesses the target language and country by evaluating the translation source - file name: E.g. \c app_de.ts sets the target language to German, + file name. For example, \c app_de.ts sets the target language to German, and \c app_de_ch.ts sets the target language to German and the target country to Switzerland (this also helps loading translations for the current locale automatically; see @@ -1287,7 +965,7 @@ can be used to edit XLIFF files generated by other programs. For standard Qt projects, however, only the TS file format is used. \o QM \e {Qt message files} \BR are binary files that contain - translations used by an application at runtime. These files are + translations used by an application at run-time. These files are generated by \l lrelease, but can also be generated by \QL. \o \c .qph \e {Qt phrase book files} \BR are human-readable XML files containing standard phrases and their translations. These files @@ -1416,7 +1094,7 @@ \endlist - \o \gui {Tools} + \o \gui {Tools} \list \o \gui {Batch Translation...} \BR Opens a \l{Batch @@ -1427,7 +1105,7 @@ Preview}. This window let you instantly see translations for forms created with \QD. \endlist - \o \gui {View} + \o \gui {View} \list \o \gui {Revert Sorting} \BR puts the items in the \l{Context @@ -1449,7 +1127,7 @@ \endlist - \o \gui {Help} + \o \gui {Help} \list \o \gui {Manual F1} \BR opens this manual. \o \gui {About Qt Linguist} \BR Shows information about \QL. @@ -1621,7 +1299,7 @@ \code CODECFORTR = UTF-8 \endcode - + See the \l lupdate and \l lrelease sections. \section2 Loading Translations @@ -1683,7 +1361,7 @@ \snippet doc/src/snippets/code/doc_src_linguist-manual.qdoc 9 - \section2 Distinguishing Identical Strings That Require Different Translations + \section2 Distinguishing Between Identical Translatable Strings The \l lupdate program automatically provides a \e context for every source text. This context is the class name of the class that contains diff --git a/doc/src/snippets/code/doc_src_i18n.qdoc b/doc/src/snippets/code/doc_src_i18n.qdoc index eca2868..80faabc 100644 --- a/doc/src/snippets/code/doc_src_i18n.qdoc +++ b/doc/src/snippets/code/doc_src_i18n.qdoc @@ -184,7 +184,7 @@ void Clock::setTime(const QTime &time) //! [12] -void QWidget::changeEvent(QEvent *event) +void MyWidget::changeEvent(QEvent *event) { if (e->type() == QEvent::LanguageChange) { titleLabel->setText(tr("Document Title")); diff --git a/doc/src/snippets/code/src_corelib_kernel_qobject.cpp b/doc/src/snippets/code/src_corelib_kernel_qobject.cpp index 4c64374..88d8025 100644 --- a/doc/src/snippets/code/src_corelib_kernel_qobject.cpp +++ b/doc/src/snippets/code/src_corelib_kernel_qobject.cpp @@ -235,9 +235,8 @@ MyWindow::MyWindow() { QLabel *senderLabel = new QLabel(tr("Name:")); QLabel *recipientLabel = new QLabel(tr("Name:", "recipient")); - ... -} //! [17] +} //! [18] |