/****************************************************************************
**
** Copyright (C) 2016 The Qt Company Ltd.
** Contact: https://www.qt.io/licensing/
**
** This file is part of the documentation of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:FDL$
** Commercial License Usage
** Licensees holding valid commercial Qt licenses may use this file in
** accordance with the commercial license agreement provided with the
** Software or, alternatively, in accordance with the terms contained in
** a written agreement between you and The Qt Company. For licensing terms
** and conditions see https://www.qt.io/terms-conditions. For further
** information use the contact form at https://www.qt.io/contact-us.
**
** GNU Free Documentation License Usage
** Alternatively, this file may be used under the terms of the GNU Free
** Documentation License version 1.3 as published by the Free Software
** Foundation and appearing in the file included in the packaging of
** this file. Please review the following information to ensure
** the GNU Free Documentation License version 1.3 requirements
** will be met: https://www.gnu.org/licenses/fdl-1.3.html.
** $QT_END_LICENSE$
**
****************************************************************************/

/*!
\page qtquick-internationalization.html howto
\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 Internationalizing Your Application

The following sections describe various aspects of internationalizing your QML
source code. If you follow these guides for all the user interface components 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.

\section2 1. Use qsTr() for all Literal User Interface Strings

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:

\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.


\section2 2. Add Context for the Translator

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.

\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.

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");
}
\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.

\code
Text {
    text: qsTr("File %1 of %2").arg(counter).arg(total)
}
\endcode

%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):

\code
Text {
    text: qsTr("%L1").arg(total)
}
\endcode

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 {QtQml::}{Date} to format the string.

\c Qt.locale() returns a \l {QtQml::}{Locale} object which contains all
kinds of information about the locale. In particular, the \l
{QtQml::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

To make sure currency numbers are localized, use the \l
{QtQml::}{Number} type. This type has similar functions as the Date
type for converting numbers into localized currency strings.

\section2 7. Use QT_TR_NOOP() for Translatable Data Text Strings

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 to 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

\section2 9. Prepare for Dynamic Language Changes

You can change the language that Qt translation functions use by adding and
removing translators with QCoreApplication::installTranslator() and
QCoreApplication::removeTranslator(). Afterwards you can call
QQmlEngine::retranslate() to trigger a refresh of all bindings that use
translations. As a result, your user interface will switch, dynamically, to the
newly selected language.

Alternatively, you can also forward a QEvent::LanguageChange event to your
application's QQmlEngine instance or connect your own signal to
QQmlEngine::retranslate().

\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 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.

*/