Doc: i18n overhaul for QObject::tr() and the Qt Linguist manual.

Reviewed-by: Trust Me

2 files changed, 288 insertions, 347 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