doc: expanded Qt Quick internationalization guide

Change-Id: I246fb252f6fca046a84fc689cea4334438d669de
Reviewed-by: Geir Vattekar <geir.vattekar@nokia.com>

1 files changed, 226 insertions, 41 deletions

diff --git a/src/quick/doc/src/appdevguide/internationalization.qdoc b/src/quick/doc/src/appdevguide/internationalization.qdoc
index ee2ac5df20..c68ed347e1 100644
--- a/src/quick/doc/src/appdevguide/internationalization.qdoc
+++ b/src/quick/doc/src/appdevguide/internationalization.qdoc
@@ -26,71 +26,256 @@
 ****************************************************************************/
 
 /*!
-\page qtquick-internationalization.html
+\page qtquick-internationalization.html howto
 \ingroup qml-features
-\title Localization And Internationalization Support In Qt Quick
-\brief Description of how a QML developer can internationalize their application
+\title Internationalization and Localization with Qt Quick
+\brief Following these steps, you can write your Qt Quick application so it can be localized for multiple languages
 
-\section1 Translation
+\section1 Internationalizing your Application
 
-Strings in QML can be marked for translation using the qsTr(), qsTranslate(), qsTrId(),
-QT_TR_NOOP(), QT_TRANSLATE_NOOP(), and QT_TRID_NOOP() functions.
+The following sections describe various aspects of internationalizing your QML
+source code. If you follow these guides for all the user interface elements in
+your application, it becomes possible to localize every aspect of your
+application for different languages and local cultural conventions such as the
+way dates and numbers are formatted.
 
-For example:
-\qml
-Text { text: qsTr("Pictures") }
-\endqml
+\section2 1. Use qsTr() for all Literal User Interface Strings
 
-These functions are standard QtScript functions; for more details see
-QScriptEngine::installTranslatorFunctions().
+Strings in QML can be marked for translation using the qsTr(), qsTranslate(),
+qsTrId(), QT_TR_NOOP(), QT_TRANSLATE_NOOP(), and QT_TRID_NOOP() functions. The
+most common way of marking strings is with the qsTr() function. For example:
 
-QML relies on the core internationalization capabilities provided by Qt. These
-capabilities are described more fully in:
-\list
-\li \l {Internationalization with Qt}
-\li \l {Qt Linguist Manual}
-\endlist
+\code
+Text {
+    id: txt1;
+    text: qsTr("Back");
+}
+\endcode
+
+This code makes "Back" a key entry in the translation files. At runtime, the
+translation system looks up the keyword "Back" and then gets the corresponding
+translation value for the current system locale. The result is returned to the
+\c text property and the user interface will show the appropriate translation of
+"Back" for the current locale.
 
-You can test a translation with the \l{qtquick-qmlscene.html}{QML Scene} using the -translation option.
 
-\section2 Example
+\section2 2. Add Context for the Translator
 
-First we create a simple QML file with text to be translated. The string
-that needs to be translated is enclosed in a call to \c qsTr().
+User interface strings are often short so you need to help the person
+translating the text understand the context of the text. You can add context
+information in the source code as extra descriptive text before the string to be
+translated. These extra descriptions are included in the .ts translation files
+delivered to the translator.
 
-hello.qml:
-\qml
-import QtQuick 2.0
+\note The .ts files are XML files with the source texts and a place for the
+translated text. The updated .ts files are converted into binary translation
+files and included as part of the final application.
 
-Rectangle {
-    width: 200; height: 200
-    Text { text: qsTr("Hello"); anchors.centerIn: parent }
+In the following code snippet, the text on the \c {//:} line is the main comment
+for the translator.
+
+The text on the \c{//~} line is optional extra information. The first word of
+the text is used as an additional identifier in the XML element in the .ts file
+so make sure the first word is not part of the sentence. For example, the
+comment "Context Not related to that" is converted to "<extra-Context>Not
+related to that" in the .ts file.
+
+\code
+Text {
+    id: txt1;
+    // This user interface string is only used here
+    //: The back of the object, not the front
+    //~ Context Not related to back-stepping
+    text: qsTr("Back");
+}
+\endcode
+
+\section2 3. Disambiguate Identical Texts
+
+The translation system consolidates the user interface text strings into unique
+items. This consolidation saves the person doing the translation work having to
+translate the same text multiple times. However, in some cases, the text is
+identical but has a different meaning. For example, in English, "back" means
+take a step backward and also means the part of an object opposite to the front.
+You need to tell the translation system about these two separate meanings so the
+translator can create two separate translations.
+
+Differentiate between identical texts by adding some id text as the second
+parameter of the qsTr() function.
+
+In the following code snippet, the \c {not front} text is an id to differentiate
+this "Back" text from the backstepping "Back" text:
+
+\code
+Text {
+    id: txt1;
+    // This user interface string is used only here
+    //: The back of the object, not the front
+    //~ Context Not related to back-stepping
+    text: qsTr("Back", "not front");
 }
-\endqml
+\endcode
+
+\section2 4. Use \c %x to Insert Parameters into a String
+
+Different languages put words together in different orders so it is not a good
+idea to create sentences by concatenating words and data. Instead, use \c % to
+insert parameters into strings. For example, the following snippet has a string
+with two number parameters \c %1 and \c %2. These parameters are inserted with
+the \c .arg() functions.
 
-Next we create a translation source file using lupdate:
 \code
-lupdate hello.qml -ts hello.ts
+Text {
+    text: qsTr("File %1 of %2").arg(counter).arg(total)
+}
 \endcode
 
-Then we open \c hello.ts in \l{Qt Linguist Manual} {Linguist}, provide
-a translation and create the release file \c hello.qm.
+%1 refers to the first parameter and \c %2 refers to the second parameter so this
+code produces output like: "File 2 of 3".
+
+\section2 5. Use %Lx so Numbers are Localized
+
+If you include the \c %L modifier when you specify a parameter, the number is
+localized according to the current regional settings. For example, in the
+following code snippet, \c %L1 means to format the first parameters according to
+the number formatting conventions of the currently selected locale (geographical
+region):
 
-Finally, we can test the translation:
 \code
-qmlviewer -translation hello.qm hello.qml
+Text {
+    text: qsTr("%L1").arg(total)
+}
 \endcode
 
-You can see a complete example and source code in the \l{declarative/i18n}{QML Internationalization example}.
+Then, with the above code, if \c total is the number "4321.56" (four thousand
+three hundred and twenty one point fifty six); with English regional settings,
+(locale) the output is "4,321.56"; with German regional settings, the output is
+"4.321,56".
+
+\section2 6. Internationalize Dates, Times and Currencies
+
+There are no special in-string modifiers for formatting dates and times.
+Instead, you need to query the current locale (geographical region) and use the
+methods of \l {QtQuick2::Date}{Date} to format the string.
+
+\c Qt.locale() returns a \l {QtQuick2::Locale}{Locale} object which contains all
+kinds of information about the locale. In particular, the \l
+{QtQuick2::Locale::name}{Locale.name} property contains the language and country
+information for the current locale. You can use the value as is, or you can
+parse it to determine the appropriate content for the current locale.
+
+The following snippet gets the current date and time with Date(), then converts
+that to a string for the current locale. Then it inserts the date string into
+the %1 parameter for the appropriate translation.
+
+\code
+Text {
+    text: qsTr("Date %1").arg(Date().toLocaleString(Qt.locale()))
+}
+\endcode
 
-\section1 Localization
+To make sure currency numbers are localized, use the \l
+{QtQuick2::Number}{Number} type. This type has similar functions as the Date
+type for converting numbers into localized currency strings.
 
-Localization is the process of adapting to local conventions,
-for example presenting dates and times using the locally preferred formats.
+\section2 7. Use QT_TR_NOOP() for Translatable Data Text Strings
 
-Qt Quick supports localization via the \l {QtQuick2::Locale}{Locale} object and extensions to the
-\l{ECMA-262}{ECMAScript} \l {QtQuick2::Date}{Date} and \l {QtQuick2::Number}{Number} types.
+If the user changes the system language without a reboot, depending on the
+system, the strings in arrays and list models and other data structures might
+not be refreshed automatically. To force the texts to be refreshed when they are
+displayed in the user interface, you need declare the strings with the
+QT_TR_NOOP() macro. Then, when you populate the objects for display, you need to
+explicitly retrieve the translation for each text. For example:
+
+\code
+ListModel {
+    id: myListModel;
+    ListElement {
+        //: Capital city of Finland
+        name: QT_TR_NOOP("Helsinki");
+        }
+    }
+
+...
+
+Text {
+    text: qsTr(myListModel.get(0).name); // get the translation of the name property in element 0
+    }
+\endcode
+
+
+\section2 8. Use Locale to Extend Localization Features
+
+If you want different graphics or audio for different geographical regions, you
+can use Qt.locale() to get the current locale. Then you choose appropriate
+graphics or audio for that locale.
+
+The following code snippet shows how you could select an appropriate icon
+that represents the language of the current locale.
+
+\code
+Component.onCompleted: {
+    switch (Qt.locale().name.substring(0,2)) {
+        case "en":   // show the English-language icon
+            languageIcon = "../images/language-icon_en.png";
+            break;
+        case "fi":   // show the Finnish language icon
+            languageIcon = "../images/language-icon_fi.png";
+            break;
+        default:     // show a default language icon
+            languageIcon = "../images/language-icon_default.png";
+    }
+}
+\endcode
+
+\section1 Localizing your Application
+
+Qt Quick applications use the same underlying localization system as Qt C++
+applications (lupdate, lrelease and .ts files). You use the same tools as
+described in the \l {Qt Linguist Manual: Release Manager}{Qt Linguist Manual}.
+You can even have user interface strings in C++ and QML source in the same
+application. The system will create a single combined translation file and the
+strings are accessible from QML and C++.
+
+\section2 Use a Conditional to Hide QML Source From the Compiler
+
+The \c lupdate tool extracts user interface strings from your application.
+lupdate reads your application's .pro file to identify which source files
+contain texts to be translated. This means your source files must be listed in
+the \c SOURCES or \c HEADERS entry in the .pro file. If your files are not
+listed the texts in them will not be found.
+
+However, the SOURCES variable is intended for C++ source files. If you list QML
+or JavaScript source files there, the compiler tries to build them as though
+they are C++ files. As a workaround, you can use an \c lupdate_only{...}
+conditional statement so the \c lupdate tool sees the .qml files but the C++
+compiler ignores them.
+
+For example, the following .pro file snippet specifies two .qml files in
+the application.
+
+\code
+lupdate_only{
+SOURCES = main.qml \
+          MainPage.qml
+}
+\endcode
+
+
+You can also specify the .qml source files without with a wildcard match. The
+search is not recursive so you need to specify each directory where there are
+user interface strings in the source code:
+
+\code
+lupdate_only{
+SOURCES = *.qml \
+          *.js \
+          content/*.qml \
+          content/*.js
+}
+\endcode
 
+See the \l {Qt Linguist Manual} for more details about Qt localization.
 
 */