<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html>
<html lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<!-- internationalization.qdoc -->
<title>Internationalization and Localization with Qt Quick | Qt 5.9</title>
<link rel="stylesheet" type="text/css" href="style/offline-simple.css" />
<script type="text/javascript">
document.getElementsByTagName("link").item(0).setAttribute("href", "style/offline.css");
// loading style sheet breaks anchors that were jumped to before
// so force jumping to anchor again
setTimeout(function() {
var anchor = location.hash;
// need to jump to different anchor first (e.g. none)
location.hash = "#";
setTimeout(function() {
location.hash = anchor;
}, 0);
}, 0);
</script>
</head>
<body>
<div class="header" id="qtdocheader">
<div class="main">
<div class="main-rounded">
<div class="navigationbar">
<table><tr>
<td ><a href="index.html">Qt 5.9</a></td><td >Internationalization and Localization with Qt Quick</td></tr></table><table class="buildversion"><tr>
<td id="buildversion" width="100%" align="right">Qt 5.9.4 Reference Documentation</td>
</tr></table>
</div>
</div>
<div class="content">
<div class="line">
<div class="content mainContent">
<div class="sidebar">
<div class="toc">
<h3><a name="toc">Contents</a></h3>
<ul>
<li class="level1"><a href="#internationalizing-your-application">Internationalizing Your Application</a></li>
<li class="level2"><a href="#1-use-qstr-for-all-literal-user-interface-strings">1. Use qsTr() for all Literal User Interface Strings</a></li>
<li class="level2"><a href="#2-add-context-for-the-translator">2. Add Context for the Translator</a></li>
<li class="level2"><a href="#3-disambiguate-identical-texts">3. Disambiguate Identical Texts</a></li>
<li class="level2"><a href="#4-use-op-op-x-to-insert-parameters-into-a-string">4. Use <code>%x</code> to Insert Parameters into a String</a></li>
<li class="level2"><a href="#5-use-lx-so-numbers-are-localized">5. Use %Lx so Numbers are Localized</a></li>
<li class="level2"><a href="#6-internationalize-dates-times-and-currencies">6. Internationalize Dates, Times and Currencies</a></li>
<li class="level2"><a href="#7-use-qt-tr-noop-for-translatable-data-text-strings">7. Use QT_TR_NOOP() for Translatable Data Text Strings</a></li>
<li class="level2"><a href="#8-use-locale-to-extend-localization-features">8. Use Locale to Extend Localization Features</a></li>
<li class="level1"><a href="#localizing-your-application">Localizing Your Application</a></li>
<li class="level2"><a href="#use-a-conditional-to-hide-qml-source-from-the-compiler">Use a Conditional to Hide QML Source From the Compiler</a></li>
</ul>
</div>
<div class="sidebar-content" id="sidebar-content"></div></div>
<h1 class="title">Internationalization and Localization with Qt Quick</h1>
<span class="subtitle"></span>
<!-- $$$qtquick-internationalization.html-description -->
<div class="descr"> <a name="details"></a>
<a name="internationalizing-your-application"></a>
<h2 id="internationalizing-your-application">Internationalizing Your Application</h2>
<p>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.</p>
<a name="1-use-qstr-for-all-literal-user-interface-strings"></a>
<h3 >1. Use qsTr() for all Literal User Interface Strings</h3>
<p>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:</p>
<pre class="cpp">
Text {
id: txt1;
text: qsTr(<span class="string">"Back"</span>);
}
</pre>
<p>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 <code>text</code> property and the user interface will show the appropriate translation of "Back" for the current locale.</p>
<a name="2-add-context-for-the-translator"></a>
<h3 >2. Add Context for the Translator</h3>
<p>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.</p>
<p><b>Note: </b>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.</p><p>In the following code snippet, the text on the <code>//:</code> line is the main comment for the translator.</p>
<p>The text on the <code>//~</code> 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.</p>
<pre class="cpp">
Text {
id: txt1;
<span class="comment">// This user interface string is only used here</span>
<span class="comment">//: The back of the object, not the front</span>
<span class="comment">//~ Context Not related to back-stepping</span>
text: qsTr(<span class="string">"Back"</span>);
}
</pre>
<a name="3-disambiguate-identical-texts"></a>
<h3 >3. Disambiguate Identical Texts</h3>
<p>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.</p>
<p>Differentiate between identical texts by adding some id text as the second parameter of the qsTr() function.</p>
<p>In the following code snippet, the <code>not front</code> text is an id to differentiate this "Back" text from the backstepping "Back" text:</p>
<pre class="cpp">
Text {
id: txt1;
<span class="comment">// This user interface string is used only here</span>
<span class="comment">//: The back of the object, not the front</span>
<span class="comment">//~ Context Not related to back-stepping</span>
text: qsTr(<span class="string">"Back"</span><span class="operator">,</span> <span class="string">"not front"</span>);
}
</pre>
<a name="4-use-op-op-x-to-insert-parameters-into-a-string"></a>
<h3 >4. Use <code>%x</code> to Insert Parameters into a String</h3>
<p>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 <code>%</code> to insert parameters into strings. For example, the following snippet has a string with two number parameters <code>%1</code> and <code>%2</code>. These parameters are inserted with the <code>.arg()</code> functions.</p>
<pre class="cpp">
Text {
text: qsTr(<span class="string">"File %1 of %2"</span>)<span class="operator">.</span>arg(counter)<span class="operator">.</span>arg(total)
}
</pre>
<p>%1 refers to the first parameter and <code>%2</code> refers to the second parameter so this code produces output like: "File 2 of 3".</p>
<a name="5-use-lx-so-numbers-are-localized"></a>
<h3 >5. Use %Lx so Numbers are Localized</h3>
<p>If you include the <code>%L</code> modifier when you specify a parameter, the number is localized according to the current regional settings. For example, in the following code snippet, <code>%L1</code> means to format the first parameters according to the number formatting conventions of the currently selected locale (geographical region):</p>
<pre class="cpp">
Text {
text: qsTr(<span class="string">"%L1"</span>)<span class="operator">.</span>arg(total)
}
</pre>
<p>Then, with the above code, if <code>total</code> 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".</p>
<a name="6-internationalize-dates-times-and-currencies"></a>
<h3 >6. Internationalize Dates, Times and Currencies</h3>
<p>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 Date to format the string.</p>
<p><code>Qt.locale()</code> returns a Locale object which contains all kinds of information about the locale. In particular, the 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.</p>
<p>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.</p>
<pre class="cpp">
Text {
text: qsTr(<span class="string">"Date %1"</span>)<span class="operator">.</span>arg(Date()<span class="operator">.</span>toLocaleString(<span class="type">Qt</span><span class="operator">.</span>locale()))
}
</pre>
<p>To make sure currency numbers are localized, use the Number type. This type has similar functions as the Date type for converting numbers into localized currency strings.</p>
<a name="7-use-qt-tr-noop-for-translatable-data-text-strings"></a>
<h3 >7. Use QT_TR_NOOP() for Translatable Data Text Strings</h3>
<p>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:</p>
<pre class="cpp">
ListModel {
id: myListModel;
ListElement {
<span class="comment">//: Capital city of Finland</span>
name: QT_TR_NOOP(<span class="string">"Helsinki"</span>);
}
}
<span class="operator">.</span><span class="operator">.</span><span class="operator">.</span>
Text {
text: qsTr(myListModel<span class="operator">.</span>get(<span class="number">0</span>)<span class="operator">.</span>name); <span class="comment">// get the translation of the name property in element 0</span>
}
</pre>
<a name="8-use-locale-to-extend-localization-features"></a>
<h3 >8. Use Locale to Extend Localization Features</h3>
<p>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.</p>
<p>The following code snippet shows how you could select an appropriate icon that represents the language of the current locale.</p>
<pre class="cpp">
Component<span class="operator">.</span>onCompleted: {
<span class="keyword">switch</span> (<span class="type">Qt</span><span class="operator">.</span>locale()<span class="operator">.</span>name<span class="operator">.</span>substring(<span class="number">0</span><span class="operator">,</span><span class="number">2</span>)) {
<span class="keyword">case</span> <span class="string">"en"</span>: <span class="comment">// show the English-language icon</span>
languageIcon <span class="operator">=</span> <span class="string">"../images/language-icon_en.png"</span>;
<span class="keyword">break</span>;
<span class="keyword">case</span> <span class="string">"fi"</span>: <span class="comment">// show the Finnish language icon</span>
languageIcon <span class="operator">=</span> <span class="string">"../images/language-icon_fi.png"</span>;
<span class="keyword">break</span>;
<span class="keyword">default</span>: <span class="comment">// show a default language icon</span>
languageIcon <span class="operator">=</span> <span class="string">"../images/language-icon_default.png"</span>;
}
}
</pre>
<a name="localizing-your-application"></a>
<h2 id="localizing-your-application">Localizing Your Application</h2>
<p>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 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++.</p>
<a name="use-a-conditional-to-hide-qml-source-from-the-compiler"></a>
<h3 >Use a Conditional to Hide QML Source From the Compiler</h3>
<p>The <code>lupdate</code> 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 <code>SOURCES</code> or <code>HEADERS</code> entry in the .pro file. If your files are not listed the texts in them will not be found.</p>
<p>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 <code>lupdate_only{...}</code> conditional statement so the <code>lupdate</code> tool sees the .qml files but the C++ compiler ignores them.</p>
<p>For example, the following .pro file snippet specifies two .qml files in the application.</p>
<pre class="cpp">
lupdate_only{
SOURCES <span class="operator">=</span> main<span class="operator">.</span>qml \
MainPage<span class="operator">.</span>qml
}
</pre>
<p>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:</p>
<pre class="cpp">
lupdate_only{
SOURCES <span class="operator">=</span> <span class="operator">*</span><span class="operator">.</span>qml \
<span class="operator">*</span><span class="operator">.</span>js \
content<span class="comment">/*.qml \
content/*.js
}
</span>
</pre>
<p>See the Qt Linguist Manual for more details about Qt localization.</p>
</div>
<!-- @@@qtquick-internationalization.html -->
</div>
</div>
</div>
</div>
</div>
<div class="footer">
<p>
<acronym title="Copyright">©</acronym> 2017 The Qt Company Ltd.
Documentation contributions included herein are the copyrights of
their respective owners.<br> The documentation provided herein is licensed under the terms of the <a href="http://www.gnu.org/licenses/fdl.html">GNU Free Documentation License version 1.3</a> as published by the Free Software Foundation.<br> Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property
of their respective owners. </p>
</div>
</body>
</html>
