<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html>
<html lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<!-- linguist-manual.qdoc -->
<title>Qt Linguist Manual: Text ID Based Translations | Qt Linguist Manual</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 >Qt 5.9</td><td ><a href="qtlinguist-index.html">Qt Linguist Manual</a></td><td >Qt Linguist Manual: Text ID Based Translations</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">
<link rel="prev" href="linguist-ts-file-format.html" />
<p class="naviNextPrevious headerNavi">
<a class="prevPage" href="linguist-ts-file-format.html">Qt Linguist Manual: TS File Format</a>
</p><p/>
<div class="sidebar">
<div class="toc">
<h3><a name="toc">Contents</a></h3>
<ul>
<li class="level1"><a href="#internationalizing-with-text-ids">Internationalizing With Text IDs</a></li>
<li class="level1"><a href="#localizing-with-text-ids">Localizing With Text IDs</a></li>
<li class="level1"><a href="#advanced-usage">Advanced Usage</a></li>
</ul>
</div>
<div class="sidebar-content" id="sidebar-content"></div></div>
<h1 class="title">Qt Linguist Manual: Text ID Based Translations</h1>
<span class="subtitle"></span>
<!-- $$$linguist-id-based-i18n.html-description -->
<div class="descr"> <a name="details"></a>
<p>The text ID translation mechanism is an "industrial strength" system for internationalization and localization. Each text in the application is assigned a unique identifier (text ID) and these identifiers are used directly in the source code in place of the plain texts. This requires a little more work for the user interface developers but makes it much easier to manage large numbers of translated texts.</p>
<p><b>Note: </b>You must use only plain-text-based or only text-ID-based functions in one application. If you mix them, you will end up with an incomplete set of texts to be translated.</p><a name="internationalizing-with-text-ids"></a>
<h2 id="internationalizing-with-text-ids">Internationalizing With Text IDs</h2>
<p>When using text IDs instead of plain text, the general method of internationalizing an application is the same but the details are a bit different:</p>
<ol class="1" type="1"><li>The functions and macros for the text-ID-based translation system are different to the plain-text system. You use the <code>qsTrId()</code> function instead of qsTr(), and the <code>QT_TRID_NOOP()</code> macro instead of QT_TR_NOOP().</li>
<li>Use text IDs as user interface strings rather than plain text strings. For example, <code>qsTrId("id-back-not-front")</code></li>
<li>You cannot specify a context parameter with a text ID. If there are identically spelled words with different meanings, these need separate text IDs. For example, <code>qsTrId("id-back-backstep")</code> will differentiate the back-step "Back" from the back-of-the-object "Back".</li>
<li>The "Engineering English" text that you see in the user interface for development builds is indicated with a <code>//%</code> comment. If you do not include this, the text ID will be shown in the user interface. This is especially important when you have texts with parameters. The <code>//%</code> comment needs to include the parameters indicators in the string. For example, <code>//% "Number of files: %1"</code></li>
<li>The <code>//:</code> comments that provide extra information to the translator are optional in the plain-text system. However, with the text-ID-based system, this extra information becomes essential because without it you only have the text ID and the translator might not be able to make a sensible translation from without any other context. You can use long descriptive text ID and no comments but comments are often easier to understand.</li>
</ol>
<p>The side-by-side code snippets below show a comparison of text-ID -based and plain-text-based translations:</p>
<div class="table"><table class="generic">
<thead><tr class="qt-style"><th >text-ID-based</th><th >plain-text-based</th></tr></thead>
<tr valign="top" class="odd"><td ><pre class="cpp">
Text {
id: backTxt;
<span class="comment">//: The back of the object, not the front</span>
<span class="comment">//% "Back"</span>
<span class="comment">//~ Context Not related to back-stepping</span>
text: qsTrId(<span class="string">"id-back-not-front"</span>);
}
</pre>
</td><td ><pre class="cpp">
Text {
id: backTxt;
<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>
</td></tr>
</table></div>
<a name="localizing-with-text-ids"></a>
<h2 id="localizing-with-text-ids">Localizing With Text IDs</h2>
<p>Localizing with text IDs follows much the same process as for plain text.</p>
<p>The <code>lupdate</code> tool is used the same way and translations are made into the .ts files:</p>
<pre class="cpp">
lupdate <span class="operator"><</span>myapp<span class="operator">></span><span class="operator">.</span>pro
</pre>
<p>Note that the source values in the translation files will be text IDs rather than plain text. This means you need very descriptive text IDs, or good additional comments, or both to ensure that the translator makes a correct translation.</p>
<p>The example text-ID-based user interface text from above results in the following content in the .ts file:</p>
<pre class="cpp">
<span class="operator"><</span>message id<span class="operator">=</span><span class="string">"id-back-not-front"</span><span class="operator">></span>
<span class="operator"><</span>source<span class="operator">></span>Back<span class="operator"><</span><span class="operator">/</span>source<span class="operator">></span>
<span class="operator"><</span>extracomment<span class="operator">></span>The back of the object<span class="operator">,</span> <span class="keyword">not</span> the front<span class="operator"><</span><span class="operator">/</span>extracomment<span class="operator">></span>
<span class="operator"><</span>translation type<span class="operator">=</span><span class="string">"unfinished"</span><span class="operator">></span><span class="operator"><</span><span class="operator">/</span>translation<span class="operator">></span>
<span class="operator"><</span>extra<span class="operator">-</span>Context<span class="operator">></span>Not related to back<span class="operator">-</span>stepping<span class="operator"><</span><span class="operator">/</span>extra<span class="operator">-</span>Context<span class="operator">></span>
<span class="operator"><</span><span class="operator">/</span>message<span class="operator">></span>
</pre>
<p>When using <code>lrelease</code>, you need to specify that the keys for translated texts are based on text IDs, rather than plain texts. If strings in the code are specified with <code>qsTr()</code> there is no "id" attribute set so they are ignored by <code>lrelease</code>.</p>
<p>This command produces all the compiled translation .qm files for your application:</p>
<pre class="cpp">
lrelease <span class="operator">-</span>idbased <span class="operator"><</span>myapp<span class="operator">></span><span class="operator">.</span>pro
</pre>
<p>However, if there is no translation available for a given text (which is generally the case until late in development), the text ID will be shown in the user interface rather than a proper text. In order to make the application more usable for testing, you can make <code>lrelease</code> use the "Engineering English" source text (from the <code>//%</code> comments) as the translated text and mark it with some indicator so you can see texts that are not yet translated.</p>
<p>For example, this command builds the .qm files and puts a "!" in front of the untranslated texts:</p>
<pre class="cpp">
lrelease <span class="operator">-</span>idbased <span class="operator">-</span>markuntranslated <span class="operator">!</span> <span class="operator"><</span>myapp<span class="operator">></span><span class="operator">.</span>pro
</pre>
<a name="advanced-usage"></a>
<h2 id="advanced-usage">Advanced Usage</h2>
<p>For projects that target a large number of locales, you can remove the TRANSLATIONS info from the .pro file and, instead, manage the translations with a separate script. The script can call lrelease and lupdate for each of the desired targets.</p>
<p>The updates could be scripted something like this:</p>
<pre class="cpp">
lupdate <span class="operator">-</span>recursive <span class="operator"><</span>project<span class="operator">-</span>dir<span class="operator">></span> <span class="operator">-</span>ts <span class="operator"><</span>project<span class="operator">-</span>dir<span class="operator">></span><span class="operator">/</span>i18n<span class="operator">/</span>myapp<span class="operator">-</span>text_en_GB<span class="operator">.</span>ts
lupdate <span class="operator">-</span>recursive <span class="operator"><</span>project<span class="operator">-</span>dir<span class="operator">></span> <span class="operator">-</span>ts <span class="operator"><</span>project<span class="operator">-</span>dir<span class="operator">></span><span class="operator">/</span>i18n<span class="operator">/</span>myapp<span class="operator">-</span>text_en_US<span class="operator">.</span>ts
<span class="operator">.</span><span class="operator">.</span><span class="operator">.</span>
</pre>
<p>The generation of the final .qm files could be scripted something like this:</p>
<pre class="cpp">
lrelease <span class="operator">-</span>idbased <span class="operator"><</span>project<span class="operator">-</span>dir<span class="operator">></span><span class="operator">/</span>i18n<span class="operator">/</span>myapp<span class="operator">-</span>text_en_GB<span class="operator">.</span>ts
lrelease <span class="operator">-</span>idbased <span class="operator"><</span>project<span class="operator">-</span>dir<span class="operator">></span><span class="operator">/</span>i18n<span class="operator">/</span>myapp<span class="operator">-</span>text_en_US<span class="operator">.</span>ts
<span class="operator">.</span><span class="operator">.</span><span class="operator">.</span>
</pre>
</div>
<!-- @@@linguist-id-based-i18n.html -->
<p class="naviNextPrevious footerNavi">
<a class="prevPage" href="linguist-ts-file-format.html">Qt Linguist Manual: TS File Format</a>
</p>
</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>
distrib
>
Mageia
>
6
>
x86_64
>
media
>
core-updates
>
by-pkgid
>
749fcc421771b410525f39bd88a5732d
>
files
>
495
