/usr/share/qt5/doc/qtlinguist/linguist-programmers.html is in qttools5-doc-html 5.9.5-0ubuntu1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 | <?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: Developers | 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: Developers</td></tr></table><table class="buildversion"><tr>
<td id="buildversion" width="100%" align="right">Qt 5.9.5 Reference Documentation</td>
</tr></table>
</div>
</div>
<div class="content">
<div class="line">
<div class="content mainContent">
<link rel="prev" href="linguist-translators.html" />
<link rel="next" href="linguist-ts-file-format.html" />
<p class="naviNextPrevious headerNavi">
<a class="prevPage" href="linguist-translators.html">Qt Linguist Manual: Translators</a>
<span class="naviSeparator"> ◦ </span>
<a class="nextPage" 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="#specifying-translation-sources-in-qt-project-files">Specifying Translation Sources in Qt Project Files</a></li>
<li class="level1"><a href="#internationalizing-applications">Internationalizing Applications</a></li>
<li class="level1"><a href="#deploying-translations">Deploying Translations</a></li>
<li class="level1"><a href="#tutorials">Tutorials</a></li>
</ul>
</div>
<div class="sidebar-content" id="sidebar-content"></div></div>
<h1 class="title">Qt Linguist Manual: Developers</h1>
<span class="subtitle"></span>
<!-- $$$linguist-programmers.html-description -->
<div class="descr"> <a name="details"></a>
<p>Support for multiple languages is extremely simple in Qt applications, and adds little overhead to the developer's workload.</p>
<p>Qt minimizes the performance cost of using translations by translating the phrases for each window as they are created. In most applications the main window is created just once. Dialogs are often created once and then shown and hidden as required. Once the initial translation has taken place there is no further runtime overhead for the translated windows. Only those windows that are created, destroyed and subsequently created will have a translation performance cost.</p>
<p>Creating applications that can switch language at runtime is possible with Qt, but requires a certain amount of developer intervention and will of course incur some runtime performance cost.</p>
<a name="specifying-translation-sources-in-qt-project-files"></a>
<h2 id="specifying-translation-sources-in-qt-project-files">Specifying Translation Sources in Qt Project Files</h2>
<p>To enable release managers to use lupdate and lrelease, specify a <code>.pro</code> Qt project file. There must be an entry in the <code>TRANSLATIONS</code> section of the project file for each language that is additional to the native language. A typical entry looks like this:</p>
<pre class="cpp">
TRANSLATIONS = arrowpad_fr.ts \
arrowpad_nl.ts
</pre>
<p>Using a locale within the translation file name is useful for determining which language to load at runtime. For more information, see <a href="../qtcore/qlocale.html">QLocale</a>.</p>
<p>The <code>lupdate</code> tool extracts user interface strings from your application. It reads the application .pro file to identify which source files contain text 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, or in resource files listed in the <code>RESOURCE</code> entry. If your files are not listed, the text in them will not be found.</p>
<p>An example of a complete <code>.pro</code> file with four translation source files:</p>
<pre class="cpp">
HEADERS = main-dlg.h \
options-dlg.h
SOURCES = main-dlg.cpp \
options-dlg.cpp \
main.cpp
FORMS = search-dlg.ui
TRANSLATIONS = superapp_dk.ts \
superapp_fi.ts \
superapp_no.ts \
superapp_se.ts
</pre>
<p>If your compiler uses a different encoding for its runtime system than for its source code and you want to use non-ASCII characters in string literals, you will need to set the <code>CODECFORSRC</code>. For example:</p>
<pre class="cpp">
CODECFORSRC = UTF-8
</pre>
<p>Microsoft Visual Studio 2005 .NET appears to be the only compiler for which this is necessary. However, if you want to write portable code, we recommend that you avoid non-ASCII characters in your source files. You can still specify non-ASCII characters portably using escape sequences, for example:</p>
<pre class="cpp">
label<span class="operator">-</span><span class="operator">></span>setText(tr(<span class="string">"F\374r \310lise"</span>));
</pre>
<a name="internationalizing-applications"></a>
<h2 id="internationalizing-applications">Internationalizing Applications</h2>
<p>Design your application so that it can be adapted to various languages and regions without engineering changes. Qt tries to make internationalization as painless as possible for you. All input controls and text drawing methods in Qt offer built-in support for all supported languages. But you still need to keep the following things in mind when writing source code for your application:</p>
<ul>
<li>Make your application look for and load the appropriate translation file.</li>
<li>Mark user-visible text and Ctrl keyboard accelerators as targets for translation.</li>
<li>Provide context for text to be translated.</li>
<li>Disambiguate identical texts.</li>
<li>Use numbered arguments (%n) as placeholders for parameters that are replaced with text or numbers at run-time.</li>
<li>Internationalize numbers, dates, times, and currencies.</li>
<li>Mark data text strings outside functions translatable.</li>
</ul>
<p>You can develop applications that use both C++ and QML sources in the same application and even have user interface strings in both sources. The tools create a single combined translation file and the strings are accessible from C++ and QML.</p>
<p>The classes that support internationalizing of Qt applications are described in Internationalization with Qt. The process of making source code translatable is described in Writing Source Code for Translation and in Internationalization and Localization with Qt Quick.</p>
<p>Each piece of text that requires translating requires context to help the translator identify where in the program the text appears. In the case of multiple identical texts that require different translations, the translator also requires some information to disambiguate the source texts. Marking text for translation will automatically cause the class name to be used as basic context information. In some cases the developer may be required to add additional information to help the translator.</p>
<a name="deploying-translations"></a>
<h2 id="deploying-translations">Deploying Translations</h2>
<p>The <code>.qm</code> files required for the application should be placed in a location where the loader code using <a href="../qtcore/qtranslator.html">QTranslator</a> can locate them. Typically, this is done by specifying a path relative to <a href="../qtcore/qcoreapplication.html#applicationDirPath">QCoreApplication::applicationDirPath</a>().</p>
<p>Usually, there are <code>.qm</code> files for the application, and, if a version of Qt is used that is not installed on the system, Qt's .qm files need to be deployed as well.</p>
<p>In Qt 4, there is one big, monolithic <code>.qm</code> file per locale. For example, the file <code>qt_de.qm</code> contains the German translation of all libraries.</p>
<p>In Qt 5, the <code>.qm</code> files were split up by module and there is a so-called meta catalog file which includes the <code>.qm</code> files of all modules. The name of the meta catalog file is identical to the name of Qt 4's monolithic <code>.qm</code> file so that existing loader code works as before provided all included <code>.qm</code> files are found.</p>
<p>However, it is not necessary to always deploy all of Qt 5's <code>.qm</code> files. We recommend concatenating the <code>.qm</code> files of the modules required to one file matching the meta catalog file name using the tool <code>lconvert</code> in the deploy step. For example, to create a German translation file for an application using the modules <a href="../qtcore/qtcore-index.html">Qt Core</a>, <a href="../qtgui/qtgui-index.html">Qt GUI</a>, and Qt Quick, run:</p>
<pre class="cpp">
lconvert <span class="operator">-</span>o installation_folder<span class="operator">/</span>qt_de<span class="operator">.</span>qm qtbase_de<span class="operator">.</span>qm qtdeclarative_de<span class="operator">.</span>qm
</pre>
<a name="tutorials"></a>
<h2 id="tutorials">Tutorials</h2>
<p>The following tutorials illustrate how to prepare Qt applications for translation:</p>
<ul>
<li><a href="qtlinguist-hellotr-example.html">Hello tr()</a> is a C++ application that demonstrates the creation of a <a href="../qtcore/qtranslator.html">QTranslator</a> object. It also shows the simplest use of the <code>tr()</code> function to mark user-visible source text for translation.</li>
<li><a href="qtlinguist-arrowpad-example.html">Arrow Pad</a> is a C++ application that demonstrates how to make the application load the translation file applicable to the current locale. It also shows the use of the two-argument form of <code>tr()</code> which provides additional information to the translator.</li>
<li><a href="qtlinguist-trollprint-example.html">Troll Print</a> is a C++ application that demonstrates how identical source texts can be distinguished even when they occur in the same context. This tutorial also discusses how the translation tools help minimize the translator's work when an application is upgraded.</li>
<li>Internationalization is a Qt Quick application that demonstrates how to internationalize Qt Quick applications.</li>
</ul>
</div>
<!-- @@@linguist-programmers.html -->
<p class="naviNextPrevious footerNavi">
<a class="prevPage" href="linguist-translators.html">Qt Linguist Manual: Translators</a>
<span class="naviSeparator"> ◦ </span>
<a class="nextPage" 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>
|