qiurui
/
qtdeclarative
mirror of https://github.com/qt/qtdeclarative.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

doc: expanded Qt Quick internationalization guide 

Change-Id: I246fb252f6fca046a84fc689cea4334438d669de
Reviewed-by: Geir Vattekar <geir.vattekar@nokia.com>
This commit is contained in:
Gary Aish 2012-07-31 11:08:29 +03:00 committed by Qt by Nokia
parent a0fb32aba4
commit fb31b200bb
1 changed files with 233 additions and 48 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

281
src/quick/doc/src/appdevguide/internationalization.qdoc
View File

@ -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
You can test a translation with the \l{qtquick-qmlscene.html}{QML Scene} using the -translation option.
\section2 Example
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().
hello.qml:
\qml
import QtQuick 2.0
Rectangle {
width: 200; height: 200
Text { text: qsTr("Hello"); anchors.centerIn: parent }
\code
Text {
id: txt1;
text: qsTr("Back");
}
\endqml
Next we create a translation source file using lupdate:
\code
lupdate hello.qml -ts hello.ts
\endcode
Then we open \c hello.ts in \l{Qt Linguist Manual} {Linguist}, provide
a translation and create the release file \c hello.qm.
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.
Finally, we can test the translation:
\code
qmlviewer -translation hello.qm hello.qml
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
You can see a complete example and source code in the \l{declarative/i18n}{QML Internationalization example}.
\section2 3. Disambiguate Identical Texts
\section1 Localization
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.
Localization is the process of adapting to local conventions,
for example presenting dates and times using the locally preferred formats.
Differentiate between identical texts by adding some id text as the second
parameter of the qsTr() function.
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.
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 {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
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.
\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 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.
*/