<p>TQt 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 TQt, but requires a certain amount of programmer intervention and will of course incur some runtime performance cost.</p>
<h3><aname="1"></a>Making the Application Translation Aware</h3>
<p>Programmers should make their application look for and load the appropriate translation file and mark user-visible text and Ctrl keyboard accelerators as targets for translation.</p>
<p>Each piece of text that requires translating requires context to help the translator identify where in the program the text occurs. 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 programmer may be required to add additional information to help the translator.</p>
<!-- index .ts Files --><!-- index Translation Source Files --><p>Translation files consist of all the user-visible text and Ctrl key accelerators in an application and translations of that text. Translation files are created as follows:</p>
<!-- index lupdate --><!-- index lrelease --><oltype=1><li><p>Run <ahref="linguist-manual-2.html#2">lupdate</a> initially to generate the first set of <tt>.ts</tt> translation source files with all the user-visible text but no translations.</p>
<li><p>The <tt>.ts</tt> files are given to the translator who adds translations using <em>TQt Linguist</em>. <em>TQt Linguist</em> takes care of any changed or deleted source text.</p>
<li><p>Run <ahref="linguist-manual-2.html#2">lupdate</a> to incorporate any new text added to the application. <ahref="linguist-manual-2.html#2">lupdate</a> synchronizes the user-visible text from the application with the translations; it does not destroy any data.</p>
<li><p>Steps 2 and 3 are repeated as often as necessary.</p>
<li><p>When a release of the application is needed <ahref="linguist-manual-2.html#3">lrelease</a> is run to read the <tt>.ts</tt> files and produce the <tt>.qm</tt> files used by the application at runtime.</p>
</ol><!-- index .pro Files --><!-- index Project Files --><!-- index qmake!Project Files --><p>For <ahref="linguist-manual-2.html#2">lupdate</a> to work successfully, it must know which translation files to produce. The files are simply listed in the application's <tt>.pro</tt> TQt project file, for example:</p>
<pre> TRANSLATIONS = tt2_fr.ts \
tt2_nl.ts
</pre>
<p>See the <ahref="linguist-manual-2.html#2">"lupdate"</a> and <ahref="linguist-manual-2.html#3">"lrelease"</a> sections.</p>
<!-- index main() --><p>This is how a simple <tt>main()</tt> function of a TQt application begins.</p>
<!-- index TQTranslator!load() --><!-- index load()!TQTranslator --><!-- index TQApplication!installTranslator() --><!-- index installTranslator()!TQApplication --><pre> int main( int argc, char **argv )
<p>For a translation-aware application a translator object is created, a translation is loaded and the translator object installed into the application.</p>
<p>In production applications a more flexible approach, for example, loading translations according to locale, might be more appropriate. If the <tt>.ts</tt> files are all named according to a convention such as <em>appname_locale</em>, e.g. <tt>tt2_fr</tt>, <tt>tt2_de</tt> etc, then the code above will load the current locale's translation at runtime.</p>
<p>If there is no translation file for the current locale the application will fall back to using the original source text.</p>
<h4><aname="1-3"></a>Making the Application Translate User-Visible Strings</h4>
<!-- index tr() --><!-- index TQObject!tr() --><p>User-visible strings are marked as translation targets by wrapping them in a <tt>tr()</tt> call, for example:</p>
<pre>
button = new TQPushButton( "&Quit", this );
</pre>
<p>would become</p>
<pre>
button = new TQPushButton( tr("&Quit"), this);
<!-- index TQ_OBJECT --><p>All <ahref="tqobject.html">TQObject</a> subclasses that use the <tt>TQ_OBJECT</tt> macro implement the <tt>tr()</tt> function.</p>
<p>Although the <tt>tr()</tt> call is normally made directly since it is usually called as a member function of a <ahref="tqobject.html">TQObject</a> subclass, in other cases an explicit class name can be supplied, for example:</p>
<!-- index Translation Contexts --><!-- index Contexts!for Translation --><!-- index lupdate --><p>The <ahref="linguist-manual-2.html#2">lupdate</a> program automatically provides a <em>context</em> for every source text. This context is the class name of the class that contains the <tt>tr()</tt> call. This is sufficient in the vast majority of cases. Sometimes however, the translator will need further information to uniquely identify a source text; for example, a dialog that contained two separate frames, each of which contained an "Enabled" option would need each identified because in some languages the translation would differ between the two. This is easily achieved using the two argument form of the <tt>tr()</tt> call, e.g.</p>
<pre>
rbc = new TQRadioButton( tr("Enabled", "Color frame"), this );
</pre>
<p>and</p>
<pre>
rbh = new TQRadioButton( tr("Enabled", "Hue frame"), this );
</pre>
<!-- index Ctrl Key --><p>Ctrl key accelerators are also translatable:</p>
<p>It is strongly recommended that the two argument form of <tt>tr()</tt> is used for Ctrl key accelerators. The second argument is the only clue the translator has as to the function performed by the accelerator.</p>
<h4><aname="1-5"></a>Helping The Translator With Navigation Information</h4>
<!-- index TRANSLATOR!in Comments --><!-- index Translator Comments --><!-- index Comments!for Translators --><p>In large complex applications it may be difficult for the translator to see where a particular source text comes from. This problem can be solved by adding a comment using the keyword <em>TRANSLATOR</em> which describes the navigation steps to reach the text in question; e.g.</p>
<pre>
/* TRANSLATOR FindDialog
Choose Edit|Find from the menu bar or press Ctrl+F to pop up the
Find dialog.
*/
</pre>
<p>These comments are particularly useful for widget classes.</p>
<h4><aname="1-6"></a>Coping With C++ Namespaces</h4>
<!-- index Namespaces --><!-- index C++!Namespaces --><!-- index lupdate --><p>C++ namespaces and the <tt>using namespace</tt> statement can confuse <ahref="linguist-manual-2.html#2">lupdate</a>. It will interpret <tt>MyClass::tr()</tt> as meaning just that, not as <tt>MyNamespace::MyClass::tr()</tt>, even if <tt>MyClass</tt> is defined in the <tt>MyNamespace</tt> namespace. Runtime translation of these strings will fail because of that.</p>
<!-- index TRANSLATOR!in Comments --><!-- index Translator Comments --><!-- index Comments!for Translators --><p>You can work around this limitation by putting a <em>TRANSLATOR</em> comment at the beginning of the source files that use <tt>MyClass::tr()</tt>:</p>
<pre>
/* TRANSLATOR MyNamespace::MyClass */
</pre>
<p>After the comment, all references to <tt>MyClass::tr()</tt> will be understood as meaning <tt>MyNamespace::MyClass::tr()</tt>.</p>
<h4><aname="1-7"></a>Translating Text that is Outside of a TQObject subclass</h4>
<p>If the quoted text is not in a member function of a TQObject subclass, use either the tr() function of an appropriate class, or the TQApplication::translate() function directly:</p>
<h5><aname="1-7-2"></a>Using TQT_TR_NOOP() and TQT_TRANSLATE_NOOP()</h5>
<p>If you need to have translatable text completely outside a function, there are two macros to help: TQT_TR_NOOP() and TQT_TRANSLATE_NOOP(). These macros merely mark the text for extraction by <ahref="linguist-manual-2.html#2">lupdate</a>. The macros expand to just the text (without the context).</p>
<p>Three tutorials are presented. The first demonstrates the creation of a <ahref="ntqtranslator.html">TQTranslator</a> object. It also shows the simplest use of the <tt>tr()</tt> function to mark user-visible source text for translation. The second tutorial explains 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 <tt>tr()</tt> which provides additional information to the translator. The third tutorial explains 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.</p>
<p>This example is a reworking of the <ahref="tutorial1-01.html">"hello-world"</a> example from <ahref="tutorial.html">Tutorial #1</a>, with a Latin translation. The <em>Tutorial 1 Screenshot, English version</em>, above, shows the English version.</p>
<h5><aname="2-1-1"></a>Line by Line Walk-through</h5>
<!-- index TQTranslator --><p>This line includes the definition of the <ahref="ntqtranslator.html">TQTranslator</a> class. Objects of this class provide translations for user-visible text.</p>
<!-- index tt1_la.qm --><p>Tries to load a file called <tt>tt1_la.qm</tt> (the <tt>.qm</tt> file extension is implicit) that contains Latin translations for the source texts used in the program. No error will occur if the file is not found.</p>
<!-- index TQApplication!installTranslator() --><!-- index installTranslator()!TQApplication --><pre> app.<ahref="ntqapplication.html#installTranslator">installTranslator</a>( &translator );
<!-- index Hello World --><pre><ahref="ntqpushbutton.html">TQPushButton</a> hello( TQPushButton::<ahref="tqobject.html#tr">tr</a>("Hello world!"), 0 );
<p>Creates a push button that displays "Hello world!". If <tt>tt1_la.qm</tt> was found and contains a translation for "Hello world!", the translation appears; if not, the source text appears.</p>
<!-- index tr() --><!-- index TQObject!tr() --><p>All classes that inherit <ahref="tqobject.html">TQObject</a> have a <tt>tr()</tt> function. Inside a member function of a <ahref="tqobject.html">TQObject</a> class, we simply write <tt>tr("Hello world!")</tt> instead of <tt>TQPushButton::tr("Hello world!")</tt> or <tt>TQObject::tr("Hello world!")</tt>.</p>
<h5><aname="2-1-2"></a>Running the Application in English</h5>
<!-- index English Language --><p>Since we haven't made the translation file <tt>tt1_la.qm</tt>, the source text is shown when we run the application:</p>
<blockquote><palign="center"><em>Tutorial 1 Screenshot, English version</em></p></blockquote>
<h5><aname="2-1-3"></a>Creating a Latin Message File</h5>
<!-- index tt1.pro --><!-- index Latin --><p>The first step is to create a project file, <tt>tt1.pro</tt>, that lists all the source files for the project. The project file can be a qmake project file, or even an ordinary makefile. Any file that contains</p>
<!-- index SOURCES!in Project Files --><!-- index TRANSLATIONS!in Project Files --><pre> SOURCES = main.cpp
TRANSLATIONS = tt1_la.ts
</pre>
<p>will work. <em>TRANSLATIONS</em> specifies the message files we want to maintain. In this example, we just maintain one set of translations, namely Latin.</p>
<!-- index .ts Files --><!-- index Translation Source Files --><!-- index .qm Files --><!-- index TQt Message Files --><p>Note that the file extension is <tt>.ts</tt>, not <tt>.qm</tt>. The <tt>.ts</tt> translation source format is designed for use during the application's development. Programmers or release managers run the <ahref="linguist-manual-2.html#2">lupdate</a> program to generate and update <tt>.ts</tt> files with the source text that is extracted from the source code. Translators read and update the <tt>.ts</tt> files using <em>TQt Linguist</em> adding and editing their translations.</p>
<!-- index XML --><p>The <tt>.ts</tt> format is human-readable XML that can be emailed directly and is easy to put under version control. If you edit this file manually, be aware that the default encoding for XML is UTF-8, not Latin-1 (ISO 8859-1). One way to type in a Latin-1 character such as 'ø' (Norwegian o with slash) is to use an XML entity: "&#xf8;". This will work for any Unicode character.</p>
<p>Once the translations are complete the <ahref="linguist-manual-2.html#3">lrelease</a> program is used to convert the <tt>.ts</tt> files into the <tt>.qm</tt> TQt message file format. The <tt>.qm</tt> format is a compact binary format designed to deliver very fast lookup performance. Both <ahref="linguist-manual-2.html#2">lupdate</a> and <ahref="linguist-manual-2.html#3">lrelease</a> read all the project's source and header files (as specified in the HEADERS and SOURCES lines of the project file) and extract the strings that appear in <tt>tr()</tt> function calls.</p>
<!-- index lupdate --><p><ahref="linguist-manual-2.html#2">lupdate</a> is used to create and update the message files (<tt>tt1_la.ts</tt> in this case) to keep them in sync with the source code. It is safe to run <ahref="linguist-manual-2.html#2">lupdate</a> at any time, as <ahref="linguist-manual-2.html#2">lupdate</a> does not remove any information. For example, you can put it in the makefile, so the <tt>.ts</tt> files are updated whenever the source changes.</p>
<!-- index .ts Files --><!-- index Translation Source Files --><!-- index XML --><p>Try running <ahref="linguist-manual-2.html#2">lupdate</a> right now, like this:</p>
<pre>
lupdate -verbose tt1.pro
</pre>
<p>(The <tt>-verbose</tt> option instructs <tt>lupdate</tt> to display messages that explain what it is doing.) You should now have a file <tt>tt1_la.ts</tt> in the current directory, containing this:</p>
<p>You don't need to understand the file format since it is read and updated using tools (<ahref="linguist-manual-2.html#2">lupdate</a>, <em>TQt Linguist</em>, <ahref="linguist-manual-2.html#3">lrelease</a>).</p>
<h5><aname="2-1-4"></a>Translating to Latin with TQt Linguist</h5>
<!-- index TQt Linguist --><!-- index Linguist --><p>We will use <em>TQt Linguist</em> to provide the translation, although you can use any XML or plain text editor to enter a translation into a <tt>.ts</tt> file.</p>
<p>To start <em>TQt Linguist</em>, type</p>
<pre>
linguist tt1_la.ts
</pre>
<p>You should now see the text "TQPushButton" in the top left pane. Double-click it, then click on "Hello world!" and enter "Orbis, te saluto!" in the <em>Translation</em> pane (the middle right of the window). Don't forget the exclamation mark!</p>
<p>Click the <em>Done</em> checkbox and choose <em>File|Save</em> from the menu bar. The <tt>.ts</tt> file will no longer contain</p>
<translation>Orbis, te saluto!</translation>
</pre>
<h5><aname="2-1-5"></a>Running the Application in Latin</h5>
<!-- index Latin --><!-- index lrelease --><p>To see the application running in Latin, we have to generate a <tt>.qm</tt> file from the <tt>.ts</tt> file. Generating a <tt>.qm</tt> file can be achieved either from within <em>TQt Linguist</em> (for a single <tt>.ts</tt> file), or by using the command line program <ahref="linguist-manual-2.html#3">lrelease</a> which will produce one <tt>.qm</tt> file for each of the <tt>.ts</tt> files listed in the project file. Generate <tt>tt1_la.qm</tt> from <tt>tt1_la.ts</tt> by choosing <em>File|Release</em> from <em>TQt Linguist</em>'s menu bar and pressing <em>Save</em> in the file save dialog that pops up. Now run the <em>tt1</em> example program again. This time the button will be labelled "Orbis, te saluto!".</p>
<!-- index Translation Contexts --><!-- index Contexts!for Translation --><p>This example is a slightly more involved and introduces a key <em>TQt Linguist</em> concept: "contexts".</p>
<ul><li><p><tt>arrowpad.h</tt> contains the definition of <tt>ArrowPad</tt>, a custom widget;</p>
<li><p><tt>arrowpad.cpp</tt> contains the implementation of <tt>ArrowPad</tt>;</p>
<li><p><tt>mainwindow.cpp</tt> contains the implementation of <tt>MainWindow</tt>;</p>
<li><p><tt>main.cpp</tt> contains main().</p>
</ul><!-- index tt2.pro --><!-- index French Language --><!-- index Dutch Language --><p>We will use two translations, French and Dutch, although there is no effective limit on the number of possible translations that can be used with an application. The relevant lines of <tt>tt2.pro</tt> are</p>
<pre> HEADERS = arrowpad.h \
mainwindow.h
SOURCES = arrowpad.cpp \
main.cpp \
mainwindow.cpp
TRANSLATIONS = tt2_fr.ts \
tt2_nl.ts
</pre>
<!-- index lupdate --><!-- index tt2_fr.ts --><!-- index tt2_nl.ts --><p>Run <ahref="linguist-manual-2.html#2">lupdate</a>; it should produce two identical message files <tt>tt2_fr.ts</tt> and <tt>tt2_nl.ts</tt>. These files will contain all the source texts marked for translation with <tt>tr()</tt> calls and their contexts.</p>
<h5><aname="2-2-1"></a>Line by Line Walk-through</h5>
<!-- index ArrowPad!in Translation Tutorial --><!-- index English Language --><p>In <tt>arrowpad.h</tt> we define the <tt>ArrowPad</tt> subclass which is a subclass of <ahref="tqwidget.html">TQWidget</a>. In the <em>Tutorial 2 Screenshot, English version</em>, above, the central widget with the four buttons is an <tt>ArrowPad</tt>.</p>
<!-- index TQ_OBJECT --><!-- index tr() --><!-- index TQObject!tr() --><!-- index Translation Contexts --><!-- index Contexts!for Translation --><p>When <ahref="linguist-manual-2.html#2">lupdate</a> is run it not only extracts the source texts but it also groups them into contexts. A context is the name of the class in which the source text appears. Thus, in this example, "ArrowPad" is a context: it is the context of the texts in the <tt>ArrowPad</tt> class. The <tt>TQ_OBJECT</tt> macro defines <tt>tr(x)</tt> in <tt>ArrowPad</tt> like this</p>
<p>Knowing which class each source text appears in enables <em>TQt Linguist</em> to group texts that are logically related together, e.g. all the text in a dialog will have the context of the dialog's class name and will be shown together. This provides useful information for the translator since the context in which text appears may influence how it should be translated. For some translations keyboard accelerators may need to be changed and having all the source texts in a particular context (class) grouped together makes it easier for the translator to perform any accelerator changes without introducing conflicts.</p>
<p>In <tt>arrowpad.cpp</tt> we implement the <tt>ArrowPad</tt> class.</p>
<p>In the <em>Tutorial 2 Screenshot, English version</em>, above, the whole window is a <tt>MainWindow</tt>. This is defined in the <tt>mainwindow.h</tt> header file. Here too, we use <tt>TQ_OBJECT</tt>, so that <tt>MainWindow</tt> will become a context in <em>TQt Linguist</em>.</p>
<!-- index Ctrl Key --><!-- index Alt Key --><pre> file-><ahref="tqmenudata.html#insertItem">insertItem</a>( <ahref="tqobject.html#tr">tr</a>("E&xit"), tqApp, TQ_SLOT(<ahref="ntqapplication.html#quit">quit</a>()),
<p>Note the use of <tt>tr()</tt> to support different keys in other languages. "Ctrl+Q" is a good choice for Quit in English, but a Dutch translator might want to use "Ctrl+A" (for Afsluiten) and a German translator "Strg+E" (for Beenden). When using <tt>tr()</tt> for Ctrl key accelerators, the two argument form should be used with the second argument describing the function that the accelerator performs.</p>
<!-- index main() --><p>Our <tt>main()</tt> function is defined in <tt>main.cpp</tt> as usual.</p>
<!-- index TQTextCodec!locale() --><!-- index locale()!TQTextCodec --><!-- index LANG!Environment Variable --><!-- index Environment Variables!LANG --><p>We choose which translation to use according to the current locale. <ahref="tqtextcodec.html#locale">TQTextCodec::locale</a>() can be influenced by setting the <tt>LANG</tt> environment variable, for example. Notice that the use of a naming convention that incorporates the locale for <tt>.qm</tt> message files, (and <tt>.ts</tt> files), makes it easy to implement choosing the translation file according to locale.</p>
<p>If there is no <tt>.qm</tt> message file for the locale chosen the original source text will be used and no error raised.</p>
<h5><aname="2-2-2"></a>Translating to French and Dutch</h5>
<p>We'll begin by translating the example application into French. Start <em>TQt Linguist</em> with <tt>tt2_fr.ts</tt>. You should get the seven source texts ("&Up", "&Left", etc.) grouped in two contexts ("ArrowPad" and "MainWindow").</p>
</ul></ul><p>It's quickest to press <b>Alt+D</b> (which clicks the <em>Done & Next</em> button) after typing each translation, since this marks the translation as done and moves on to the next source text.</p>
<p>Save the file and do the same for Dutch working with <tt>tt2_nl.ts</tt>:</p>
<ul><li><p><tt>ArrowPad</tt></p>
<ul><li><p>&Up - &Boven</p>
<li><p>&Left - &Links</p>
<li><p>&Right - &Rechts</p>
<li><p>&Down - &Onder</p>
</ul><li><p><tt>MainWindow</tt></p>
<ul><li><p>E&xit - &Afsluiten</p>
<li><p>Ctrl+Q - Ctrl+A</p>
<li><p>File - &Bestand</p>
</ul></ul><p>We have to convert the <tt>tt1_fr.ts</tt> and <tt>tt1_nl.ts</tt> translation source files into <tt>.qm</tt> files. We could use <em>TQt Linguist</em> as we've done before; however using the command line tool <ahref="linguist-manual-2.html#3">lrelease</a> ensures that <em>all</em> the <tt>.qm</tt> files for the application are created without us having to remember to load and <em>File|Release</em> each one individually from <em>TQt Linguist</em>.</p>
<p>In practice we would include calls to <ahref="linguist-manual-2.html#2">lupdate</a> and <ahref="linguist-manual-2.html#3">lrelease</a> in the application's makefile to ensure that the latest translations are used.</p>
<p>Type</p>
<pre>
lrelease tt2.pro
</pre>
<!-- index LANG!Environment Variable --><!-- index export!Unix Command --><!-- index setenv!Unix Command --><p>This should create both <tt>tt2_fr.qm</tt> and <tt>tt2_nl.qm</tt>. Set the <tt>LANG</tt> environment variable to <tt>fr</tt>. In Unix, one of the two following commands should work</p>
<pre>
export LANG=fr
setenv LANG fr
</pre>
<!-- index --><!-- index autoexec.bat --><!-- index set!Windows Command --><p>In Windows, either modify <tt>autoexec.bat</tt> or run</p>
<pre>
set LANG=fr
</pre>
<p>When you run the program, you should now see the French version:</p>
<p>Mark one of the translations in <em>TQt Linguist</em> as not done, i.e. by unchecking the "done" checkbox; run <ahref="linguist-manual-2.html#2">lupdate</a>, then <ahref="linguist-manual-2.html#3">lrelease</a>, then the example. What effect did this change have?</p>
<!-- index Canada --><!-- index French Canada --><p>Set <tt>LANG=fr_CA</tt> (French Canada) and run the example program again. Explain why the result is the same as with <tt>LANG=fr</tt>.</p>
<p>Change one of the accelerators in the Dutch translation to eliminate the conflict between <em></em>&Bestand and <em></em>&Boven.</p>
<!-- index Portuguese Language --><!-- index Brazilian Language --><p>We've included a translation file, <tt>tt3_pt.ts</tt>, which contains some Portuguese translations for this example.</p>
<!-- index Troll Print --><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>Troll Print is a toy example application that lets the user choose printer settings. It comes in two versions: English and Portuguese.</p>
<p>Version 1.0 consists of these files:</p>
<!-- index tt3.pro --><!-- index tt3_pt.ts --><ul><li><p><tt>printpanel.h</tt> contains the definition of PrintPanel;</p>
<li><p><tt>printpanel.cpp</tt> contains the implementation of PrintPanel;</p>
<li><p><tt>mainwindow.h</tt> contains the definition of <tt>MainWindow</tt>;</p>
<li><p><tt>mainwindow.cpp</tt> contains the implementation of <tt>MainWindow</tt>;</p>
<li><p><tt>main.cpp</tt> contains main();</p>
<li><p><tt>tt3.pro</tt> is the <em>qmake</em> project file.</p>
<li><p><tt>tt3_pt.ts</tt> is the Portuguese message file.</p>
</ul><h5><aname="2-3-1"></a>Line by Line Walk-through</h5>
<p>The PrintPanel is defined in <tt>printpanel.h</tt>.</p>
<!-- index TQ_OBJECT --><!-- index PrintPanel!in Translation Tutorial --><p>PrintPanel is a <ahref="tqwidget.html">TQWidget</a>. It needs the <tt>TQ_OBJECT</tt> macro for <tt>tr()</tt> to work properly.</p>
<ahref="ntqlabel.html">TQLabel</a> *lab = new <ahref="ntqlabel.html">TQLabel</a>( <ahref="tqobject.html#tr">tr</a>("<b>TROLL PRINT</b>"), this );
<p>Notice the two occurrences of <tt>tr("Enabled")</tt> and of <tt>tr("Disabled")</tt> in PrintPanel. Since both "Enabled"s and "Disabled"s appear in the same context <em>TQt Linguist</em> 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 <em>TQt Linguist</em> can be made to display all the occurrences for separate translation shortly.</p>
<!-- index MainWindow!in Translation Tutorial --><p>The header file for <tt>MainWindow</tt>, <tt>mainwindow.h</tt>, contains no surprises. In the implementation, <tt>mainwindow.cpp</tt>, we have some user-visible source texts that must be marked for translation.</p>
<p>We also need to translate the menu items. Note that the two argument form of <tt>tr()</tt> 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>
<!-- index main() --><p>The <tt>main()</tt> function in <tt>main.cpp</tt> is the same as the one in <ahref="linguist-manual-4.html#2-2">Tutorial 2</a>. In particular it chooses a translation file based on the current locale.</p>
<h5><aname="2-3-2"></a>Running Troll Print 1.0 in English and in Portuguese</h5>
<p>We will use the translations in the <tt>tt3_pt.ts</tt> file that is provided.</p>
<p>Set the <tt>LANG</tt> environment variable to <tt>pt</tt>, and then run <tt>tt3</tt>. You should still see the English version, as shown in the <em>Tutorial 3 Screenshot, "Troll Print 1.0", English version</em>, above. Now run <ahref="linguist-manual-2.html#3">lrelease</a>, e.g. <tt>lrelease tt3.pro</tt>, and then run the example again. Now you should see the Portuguese edition (Troll Imprimir 1.0):</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 <tt>tt3_pt.ts</tt> using <em>TQt Linguist</em>, 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 <em>TQt Linguist</em> 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 <tt>tr()</tt>.</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 <tt>printpanel.cpp</tt>, where the there are four lines to change. Add the second argument "two-sided" in the appropriate <tt>tr()</tt> calls to the first pair of radio buttons:</p>
<pre>
but = new TQRadioButton( tr("Enabled", "two-sided"), twoSided );
but = new TQRadioButton( tr("Disabled", "two-sided"), twoSided );
</pre>
<p>and add the second argument "colors" in the appropriate <tt>tr()</tt> calls for the second pair of radio buttons:</p>
<pre>
but = new TQRadioButton( tr("Enabled", "colors"), colors );
but = new TQRadioButton( tr("Disabled", "colors"), colors );
</pre>
<!-- index lupdate --><!-- index tt3_pt.ts --><p>Now run <ahref="linguist-manual-2.html#2">lupdate</a> and open <tt>tt3_pt.ts</tt> with <em>TQt Linguist</em>. You should now see two changes.</p>
<p>First, the translation source file now contains <em>three</em> "Enabled", "Disabled" pairs. The first pair is marked "(obs.)" signifying that they are obsolete. This is because these texts appeared in <tt>tr()</tt> 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 <em>Source text and comments</em> area in <em>TQt Linguist</em>.</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 <ahref="linguist-manual-2.html#3">lrelease</a> to obtain an up-to-date binary <tt>tt3_pt.qm</tt> file, and run Troll Print (or rather Troll Imprimir).</p>
<!-- index Translator Comments --><!-- index Comments!for Translators --><p>The second argument to <tt>tr()</tt> calls, called "comments" in <em>TQt Linguist</em>, 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>
<!-- index TRANSLATOR!in Comments --><!-- index Translator Comments --><!-- index Comments!for Translators --><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 <em>TRANSLATOR</em> comment in the source code:</p>
<pre>
/* 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.
*/
</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. <tt>mainwindow.cpp</tt> and <tt>printpanel.cpp</tt> are appropriate files. Run <ahref="linguist-manual-2.html#2">lupdate</a> and then start <em>TQt Linguist</em> and load in <tt>tt3_pt.ts</tt>. You should see the comments in the <em>Source text and comments</em> 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>
/* 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.
*/
</pre>
<h5><aname="2-3-3"></a>Troll Print 1.1</h5>
<p>We'll now prepare release 1.1 of Troll Print. Start your favorite text editor and follow these steps:</p>
<ul><li><p>Uncomment the two lines that create a <ahref="ntqlabel.html">TQLabel</a> with the text "<b>TROLL PRINT</b>" in <tt>printpanel.cpp</tt>.</p>
<li><p>Word-tidying: Replace "2-sided" by "Two-sided" in <tt>printpanel.cpp</tt>.</p>
<li><p>Replace "1.0" with "1.1" everywhere it occurs in <tt>mainwindow.cpp</tt>.</p>
<li><p>Update the copyright year to 1999-2000 in <tt>mainwindow.cpp</tt>.</p>
</ul><p>(Of course the version number and copyright year would be consts or #defines in a real application.)</p>
<p>Once finished, run <ahref="linguist-manual-2.html#2">lupdate</a>, then open <tt>tt3_pt.ts</tt> in <em>TQt Linguist</em>. The following items are of special interest:</p>
<li><p><b>TROLL PRINT</b> - unmarked, i.e. untranslated</p>
<li><p>Two-sided - unmarked, i.e. untranslated.</p>
</ul></ul><p>Notice that <ahref="linguist-manual-2.html#2">lupdate</a> works hard behind the scenes to make revisions easier, and it's pretty smart with numbers.</p>
<p>Go over the translations in <tt>MainWindow</tt> and mark these as "done". Translate "<b>TROLL PRINT</b>" as "<b>TROLL IMPRIMIR</b>". When you're translating "Two-sided", press the <em>Guess Again</em> button to translate "Two-sided", but change the "2" into "Dois".</p>
<blockquote><palign="center"><em>Tutorial 3 Screenshot, About box, Portuguese version</em></p></blockquote>
<!-- index English Language --><!-- index Translating TQt --><!-- index TQt!Translating TQt --><p>If you choose <em>Ajuda|Sobre TQt</em>, (<em>Help|About TQt</em>), you'll get an English dialog. Oops! TQt itself needs to be translated. See the document <ahref="i18n.html#qt-itself">Internationalization with TQt</a> for details.</p>
<p>Now set <tt>LANG=en</tt> to get the original English version:</p>
<blockquote><palign="center"><em>Tutorial 3 Screenshot, "Troll Print 1.1", English version</em></p></blockquote>
<h4><aname="2-4"></a>Summary</h4>
<p>These tutorials cover all that you need to know to prepare your TQt applications for translation.</p>
<p>At the beginning of a project add the translation source files to be used to the project file and add calls to <ahref="linguist-manual-2.html#2">lupdate</a> and <ahref="linguist-manual-2.html#3">lrelease</a> to the make file.</p>
<p>During the project all the programmer must do is wrap any user-visible text in <tt>tr()</tt> calls. They should also use the two argument form for Ctrl key accelerators, or when asked by the translator for the cases where the same text translates into two different forms in the same context. The programmer should also include <em>TRANSLATION</em> comments to help the translator navigate the application.</p>
