/usr/share/qt5/doc/qtlinguist/qtlinguist-trollprint-example.html is in qttools5-doc-html 5.5.1-3build1.
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 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 | <?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html>
<html lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<!-- trollprint.qdoc -->
<title>Troll Print Example | Qt Linguist Manual </title>
<link rel="stylesheet" type="text/css" href="style/offline.css" />
</head>
<body>
<div class="header" id="qtdocheader">
<div class="main">
<div class="main-rounded">
<div class="navigationbar">
<ul>
<li>Qt 5.5</li>
<li><a href="qtlinguist-index.html">Qt Linguist Manual</a></li>
<li>Troll Print Example</li>
<li id="buildversion">Qt 5.5.1 Reference Documentation</li>
</ul>
</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="#line-by-line-walkthrough">Line by Line Walkthrough</a></li>
<li class="level1"><a href="#running-troll-print-1-0-in-english-and-in-portuguese">Running Troll Print 1.0 in English and in Portuguese</a></li>
<li class="level1"><a href="#troll-print-1-1">Troll Print 1.1</a></li>
</ul>
</div>
<div class="sidebar-content" id="sidebar-content"></div></div>
<h1 class="title">Troll Print Example</h1>
<span class="subtitle"></span>
<!-- $$$trollprint-description -->
<div class="descr"> <a name="details"></a>
<p>Troll Print is an example application that lets the user choose printer settings. It comes in two versions: English and Portuguese.</p>
<p class="centerAlign"><img src="images/linguist-trollprint_10_en.png" alt="" /></p><p>We've included a translation file, <code>trollprint_pt.ts</code>, which contains some Portuguese translations for this example.</p>
<p>We will consider two releases of the same application: Troll Print 1.0 and 1.1. We will learn to reuse the translations created for one release in a subsequent release. (In this tutorial, you need to edit some source files. It's probably best to copy all the files to a new temporary directory and work from there.)</p>
<p>See the <a href="qtlinguist-index.html">Qt Linguist Manual</a> for more information about translating Qt application.</p>
<a name="line-by-line-walkthrough"></a>
<h2 id="line-by-line-walkthrough">Line by Line Walkthrough</h2>
<p>The <code>PrintPanel</code> class is defined in <code>printpanel.h</code>.</p>
<pre class="cpp"><span class="keyword">class</span> PrintPanel : <span class="keyword">public</span> <span class="type">QWidget</span>
{
Q_OBJECT</pre>
<p><code>PrintPanel</code> is a QWidget. It needs the <code>Q_OBJECT</code> macro for <code>tr()</code> to work properly.</p>
<p>The implementation file is <code>printpanel.cpp</code>.</p>
<pre class="cpp">PrintPanel<span class="operator">::</span>PrintPanel(<span class="type">QWidget</span> <span class="operator">*</span>parent)
: <span class="type">QWidget</span>(parent)
{
<span class="comment">/*
QLabel *label = new QLabel(tr("<b>TROLL PRINT</b>"));
label->setAlignment(Qt::AlignCenter);
*/</span></pre>
<p>Some of the code is commented out in Troll Print 1.0; you will uncomment it later, for Troll Print 1.1.</p>
<pre class="cpp"> twoSidedGroupBox <span class="operator">=</span> <span class="keyword">new</span> <span class="type">QGroupBox</span>(tr(<span class="string">"2-sided"</span>));
twoSidedEnabledRadio <span class="operator">=</span> <span class="keyword">new</span> <span class="type">QRadioButton</span>(tr(<span class="string">"Enabled"</span>));
twoSidedDisabledRadio <span class="operator">=</span> <span class="keyword">new</span> <span class="type">QRadioButton</span>(tr(<span class="string">"Disabled"</span>));
twoSidedDisabledRadio<span class="operator">-</span><span class="operator">></span>setChecked(<span class="keyword">true</span>);
colorsGroupBox <span class="operator">=</span> <span class="keyword">new</span> <span class="type">QGroupBox</span>(tr(<span class="string">"Colors"</span>));
colorsEnabledRadio <span class="operator">=</span> <span class="keyword">new</span> <span class="type">QRadioButton</span>(tr(<span class="string">"Enabled"</span>));
colorsDisabledRadio <span class="operator">=</span> <span class="keyword">new</span> <span class="type">QRadioButton</span>(tr(<span class="string">"Disabled"</span>));</pre>
<p>Notice the two occurrences of <code>tr("Enabled")</code> and of <code>tr("Disabled")</code> in PrintPanel. Since both "Enabled"s and "Disabled"s appear in the same context <i>Qt Linguist</i> will only display one occurrence of each and will use the same translations for the duplicates that it doesn't display. Whilst this is a useful timesaver, in some languages, such as Portuguese, the second occurrence requires a separate translation. We will see how <i>Qt Linguist</i> can be made to display all the occurrences for separate translation shortly.</p>
<p>The header file for <code>MainWindow</code>, <code>mainwindow.h</code>, contains no surprises. In the implementation, <code>mainwindow.cpp</code>, we have some user-visible source texts that must be marked for translation.</p>
<pre class="cpp"> setWindowTitle(tr(<span class="string">"Troll Print 1.0"</span>));</pre>
<p>We must translate the window title.</p>
<pre class="cpp"><span class="type">void</span> MainWindow<span class="operator">::</span>createActions()
{
exitAct <span class="operator">=</span> <span class="keyword">new</span> <span class="type">QAction</span>(tr(<span class="string">"E&xit"</span>)<span class="operator">,</span> <span class="keyword">this</span>);
exitAct<span class="operator">-</span><span class="operator">></span>setShortcut(tr(<span class="string">"Ctrl+Q"</span><span class="operator">,</span> <span class="string">"Quit"</span>));
connect(exitAct<span class="operator">,</span> SIGNAL(triggered())<span class="operator">,</span> <span class="keyword">this</span><span class="operator">,</span> SLOT(close()));
aboutAct <span class="operator">=</span> <span class="keyword">new</span> <span class="type">QAction</span>(tr(<span class="string">"&About"</span>)<span class="operator">,</span> <span class="keyword">this</span>);
aboutAct<span class="operator">-</span><span class="operator">></span>setShortcut(<span class="type"><a href="../qtcore/qt.html">Qt</a></span><span class="operator">::</span>Key_F1);
connect(aboutAct<span class="operator">,</span> SIGNAL(triggered())<span class="operator">,</span> <span class="keyword">this</span><span class="operator">,</span> SLOT(about()));
aboutQtAct <span class="operator">=</span> <span class="keyword">new</span> <span class="type">QAction</span>(tr(<span class="string">"About &Qt"</span>)<span class="operator">,</span> <span class="keyword">this</span>);
connect(aboutQtAct<span class="operator">,</span> SIGNAL(triggered())<span class="operator">,</span> qApp<span class="operator">,</span> SLOT(aboutQt()));
}
<span class="type">void</span> MainWindow<span class="operator">::</span>createMenus()
{
<span class="type">QMenu</span> <span class="operator">*</span>fileMenu <span class="operator">=</span> menuBar()<span class="operator">-</span><span class="operator">></span>addMenu(tr(<span class="string">"&File"</span>));
fileMenu<span class="operator">-</span><span class="operator">></span>addAction(exitAct);
menuBar()<span class="operator">-</span><span class="operator">></span>addSeparator();
<span class="type">QMenu</span> <span class="operator">*</span>helpMenu <span class="operator">=</span> menuBar()<span class="operator">-</span><span class="operator">></span>addMenu(tr(<span class="string">"&Help"</span>));
helpMenu<span class="operator">-</span><span class="operator">></span>addAction(aboutAct);
helpMenu<span class="operator">-</span><span class="operator">></span>addAction(aboutQtAct);
}</pre>
<p>We also need to translate the actions and menus. Note that the two argument form of <code>tr()</code> is used for the keyboard accelerator, "Ctrl+Q", since the second argument is the only clue the translator has to indicate what function that accelerator will perform.</p>
<pre class="cpp"> <span class="type"><a href="../qtcore/qtranslator.html">QTranslator</a></span> translator;
translator<span class="operator">.</span>load(<span class="type"><a href="../qtcore/qstring.html">QString</a></span>(<span class="string">"trollprint_"</span>) <span class="operator">+</span> locale);
app<span class="operator">.</span>installTranslator(<span class="operator">&</span>translator);</pre>
<p>The <code>main()</code> function in <code>main.cpp</code> is the same as the one in the <a href="qtlinguist-arrowpad-example.html">Arrow Pad</a> example. In particular, it chooses a translation file based on the current locale.</p>
<a name="running-troll-print-1-0-in-english-and-in-portuguese"></a>
<h2 id="running-troll-print-1-0-in-english-and-in-portuguese">Running Troll Print 1.0 in English and in Portuguese</h2>
<p>We will use the translations in the <code>trollprint_pt.ts</code> file that is provided.</p>
<p>Set the <code>LANG</code> environment variable to <code>pt</code>, and then run <code>trollprint</code>. You should still see the English version. Now run <code>lrelease</code>, e.g. <code>lrelease trollprint.pro</code>, and then run the example again. Now you should see the Portuguese edition (Troll Imprimir 1.0):</p>
<p class="centerAlign"><img src="images/linguist-trollprint_10_pt_bad.png" alt="" /></p><p>Whilst the translation has appeared correctly, it is in fact wrong. In good Portuguese, the second occurrence of "Enabled" should be "Ativadas", not "Ativado" and the ending for the second translation of "Disabled" must change similarly too.</p>
<p>If you open <code>trollprint_pt.ts</code> using <i>Qt Linguist</i>, you will see that there is just one occurrence of "Enabled" and of "Disabled" in the translation source file, even though there are two of each in the source code. This is because <i>Qt Linguist</i> tries to minimize the translator's work by using the same translation for duplicate source texts. In cases such as this where an identical translation is wrong, the programmer must disambiguate the duplicate occurrences. This is easily achieved by using the two argument form of <code>tr()</code>.</p>
<p>We can easily determine which file must be changed because the translator's "context" is in fact the class name for the class where the texts that must be changed appears. In this case the file is <code>printpanel.cpp</code>, where there are four lines to change. Add the second argument "two-sided" in the appropriate <code>tr()</code> calls to the first pair of radio buttons:</p>
<pre class="cpp">twoSidedEnabledRadio <span class="operator">=</span> <span class="keyword">new</span> <span class="type">QRadioButton</span>(tr(<span class="string">"Enabled"</span><span class="operator">,</span> <span class="string">"two-sided"</span>));
twoSidedDisabledRadio <span class="operator">=</span> <span class="keyword">new</span> <span class="type">QRadioButton</span>(tr(<span class="string">"Disabled"</span><span class="operator">,</span> <span class="string">"two-sided"</span>));</pre>
<p>and add the second argument "colors" in the appropriate <code>tr()</code> calls for the second pair of radio buttons:</p>
<pre class="cpp">colorsEnabledRadio <span class="operator">=</span> <span class="keyword">new</span> <span class="type">QRadioButton</span>(tr(<span class="string">"Enabled"</span><span class="operator">,</span> <span class="string">"colors"</span>)<span class="operator">,</span> colors);
colorsDisabledRadio <span class="operator">=</span> <span class="keyword">new</span> <span class="type">QRadioButton</span>(tr(<span class="string">"Disabled"</span><span class="operator">,</span> <span class="string">"colors"</span>)<span class="operator">,</span> colors);</pre>
<p>Now run <code>lupdate</code> and open <code>trollprint_pt.ts</code> with <i>Qt Linguist</i>. You should now see two changes.</p>
<p>First, the translation source file now contains <i>three</i> "Enabled", "Disabled" pairs. The first pair is marked "(obs.)" signifying that they are obsolete. This is because these texts appeared in <code>tr()</code> calls that have been replaced by new calls with two arguments. The second pair has "two-sided" as their comment, and the third pair has "colors" as their comment. The comments are shown in the <b>Source text and comments</b> area in <i>Qt Linguist</i>.</p>
<p>Second, the translation text "Ativado" and "Desativado" have been automatically used as translations for the new "Enabled" and "Disabled" texts, again to minimize the translator's work. Of course in this case these are not correct for the second occurrence of each word, but they provide a good starting point.</p>
<p>Change the second "Ativado" into "Ativadas" and the second "Desativado" into "Desativadas", then save and quit. Run <code>lrelease</code> to obtain an up-to-date binary <code>trollprint_pt.qm</code> file, and run Troll Print (or rather Troll Imprimir).</p>
<p class="centerAlign"><img src="images/linguist-trollprint_10_pt_good.png" alt="" /></p><p>The second argument to <code>tr()</code> calls, called "comments" in <i>Qt Linguist</i>, distinguish between identical source texts that occur in the same context (class). They are also useful in other cases to give clues to the translator, and in the case of Ctrl key accelerators are the only means of conveying the function performed by the accelerator to the translator.</p>
<p>An additional way of helping the translator is to provide information on how to navigate to the particular part of the application that contains the source texts they must translate. This helps them see the context in which the translation appears and also helps them to find and test the translations. This can be achieved by using a <code>TRANSLATOR</code> comment in the source code:</p>
<pre class="cpp"><span class="comment">/*
TRANSLATOR MainWindow
In this application the whole application is a MainWindow.
Choose Help|About from the menu bar to see some text
belonging to MainWindow.
...
*/</span></pre>
<p>Try adding these comments to some source files, particularly to dialog classes, describing the navigation necessary to reach the dialogs. You could also add them to the example files, e.g. <code>mainwindow.cpp</code> and <code>printpanel.cpp</code> are appropriate files. Run <code>lupdate</code> and then start <i>Qt Linguist</i> and load in <code>trollprint_pt.ts</code>. You should see the comments in the <b>Source text and comments</b> area as you browse through the list of source texts.</p>
<p>Sometimes, particularly with large programs, it can be difficult for the translator to find their translations and check that they're correct. Comments that provide good navigation information can save them time:</p>
<pre class="cpp"><span class="comment">/*
TRANSLATOR ZClientErrorDialog
Choose Client|Edit to reach the Client Edit dialog, then choose
Client Specification from the drop down list at the top and pick
client Bartel Leendert van der Waerden. Now check the Profile
checkbox and then click the Start Processing button. You should
now see a pop up window with the text "Error: Name too long!".
This window is a ZClientErrorDialog.
*/</span></pre>
<a name="troll-print-1-1"></a>
<h2 id="troll-print-1-1">Troll Print 1.1</h2>
<p>We'll now prepare release 1.1 of Troll Print. Start your favorite text editor and follow these steps:</p>
<ul>
<li>Uncomment the two lines that create a QLabel with the text "<b>TROLL PRINT</b>" in <code>printpanel.cpp</code>.</li>
<li>Word-tidying: Replace "2-sided" by "Two-sided" in <code>printpanel.cpp</code>.</li>
<li>Replace "1.0" with "1.1" everywhere it occurs in <code>mainwindow.cpp</code>.</li>
<li>Update the copyright year to 1999-2000 in <code>mainwindow.cpp</code>.</li>
</ul>
<p>(Of course the version number and copyright year would be consts or #defines in a real application.)</p>
<p>Once finished, run <code>lupdate</code>, then open <code>trollprint_pt.ts</code> in <i>Qt Linguist</i>. The following items are of special interest:</p>
<ul>
<li><code>MainWindow</code><ul>
<li>Troll Print 1.0 - marked "(obs.)", obsolete</li>
<li>About Troll Print 1.0 - marked "(obs.)", obsolete</li>
<li>Troll Print 1.0. Copyright 1999 Software, Inc. - marked obsolete</li>
<li>Troll Print 1.1 - automatically translated as "Troll Imprimir 1.1"</li>
<li>About Troll Print 1.1 - automatically translated as "Troll Imprimir 1.1"</li>
<li>Troll Print 1.1. Copyright 1999-2000 Software, Inc. - automatically translated as "Troll Imprimir 1.1. Copyright 1999-2000 Software, Inc."</li>
</ul>
</li>
<li><code>PrintPanel</code><ul>
<li>2-sided - marked "(obs.)", obsolete</li>
<li><b>TROLL PRINT</b> - unmarked, i.e. untranslated</li>
<li>Two-sided - unmarked, i.e. untranslated.</li>
</ul>
</li>
</ul>
<p>Notice that <code>lupdate</code> works hard behind the scenes to make revisions easier, and it's pretty smart with numbers.</p>
<p>Go over the translations in <code>MainWindow</code> and mark these as "done". Translate "<b>TROLL PRINT</b>" as "<b>TROLL IMPRIMIR</b>". When you're translating "Two-sided", press the <b>Guess Again</b> button to translate "Two-sided", but change the "2" into "Dois".</p>
<p>Save and quit, then run <code>lrelease</code>. The Portuguese version should look like this:</p>
<p class="centerAlign"><img src="images/linguist-trollprint_11_pt.png" alt="" /></p><p>Choose <b>Ajuda|Sobre</b> (<b>Help|About</b>) to see the about box.</p>
<p>If you choose <b>Ajuda|Sobre Qt</b> (<b>Help|About Qt</b>), you'll get an English dialog. Oops! Qt itself needs to be translated. See Internationalization with Qt for details.</p>
<p>Now set <code>LANG=en</code> to get the original English version:</p>
<p class="centerAlign"><img src="images/linguist-trollprint_11_en.png" alt="" /></p><p>Files:</p>
<ul>
<li><a href="qtlinguist-trollprint-mainwindow-cpp.html">trollprint/mainwindow.cpp</a></li>
<li><a href="qtlinguist-trollprint-mainwindow-h.html">trollprint/mainwindow.h</a></li>
<li><a href="qtlinguist-trollprint-printpanel-cpp.html">trollprint/printpanel.cpp</a></li>
<li><a href="qtlinguist-trollprint-printpanel-h.html">trollprint/printpanel.h</a></li>
<li><a href="qtlinguist-trollprint-main-cpp.html">trollprint/main.cpp</a></li>
<li><a href="qtlinguist-trollprint-trollprint-pro.html">trollprint/trollprint.pro</a></li>
</ul>
</div>
<!-- @@@trollprint -->
</div>
</div>
</div>
</div>
</div>
<div class="footer">
<p>
<acronym title="Copyright">©</acronym> 2015 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>
|