<blockquote><palign="center"><em>Linguist Main Window</em></p></blockquote>
<h3><aname="1"></a>The One Minute Guide to Using TQt Linguist</h3>
<!-- index Linguist --><!-- index TQt Linguist --><!-- index Contexts!for Translation --><p><em>TQt Linguist</em> is a tool for adding translations to TQt applications. It introduces the concept of a translation "context" which means a group of phrases that appear together on the screen e.g. in the same menu or dialog.</p>
<p>To start, run <em>TQt Linguist</em>, either from the taskbar menu, or by double clicking the desktop icon, or type <tt>linguist</tt> (followed by <b>Enter</b>) at the command line. Once <em>TQt Linguist</em> has started choose <b>File|Open</b> from the menu bar and select a <tt>.ts</tt> translation source file to work on.</p>
<p><em>TQt Linguist</em>'s main window is divided into four main areas. The left hand side contains the Context list, the top right is the Source text area, the middle right is the translation area and the bottom right is the phrases and guesses area. We'll describe them in detail later.</p>
<p>Click on one of the contexts in the context list (left hand side) and then click on one of the phrases that appears in the Source text area (top right). The phrase will be copied into the translation area (middle right). Click under the word 'Translation' and type in the translation. Click <b>Ctrl+Enter</b> (Done & Next) to confirm that you have completed the translation and to move on to the next phrase that requires translation.</p>
<p>The cycle of entering a translation then pressing <b>Ctrl+Enter</b> can be repeated until all the translations are done or until you finish the session. Linguist will attempt to fill the "phrases and guesses" area with possible translations from any open phrase books and any previous translations. Each has a keyboard shortcut, e.g. <b>Ctrl+1</b>, <b>Ctrl+2</b>, etc., which you can use to copy the guess into the Translation area. (Mouse users can double click a phrase or guess to move it into the Translation area.) At the end of the session choose <b>File|Save</b> from the menu bar and then <b>File|Exit</b> to quit.</p>
<h3><aname="2"></a>TQt Linguist's Main Window</h3>
<h4><aname="2-1"></a>Context List</h4>
<!-- index Contexts!for Translation --><p>This appears at the left hand side of the main window by default. The first column, 'Done', identifies whether or not the translations for the context have been done. A tick indicates that all the translations have been done and are valid. A question mark indicates that one or more translations have not been done or have failed validation. The second column, 'Context' is the name of the context in which the translation phrases appear. The third column, 'Items' shows two numbers, the first is the number of translations that have been done, and the second is the number of phrases that are in the context; if the numbers are equal then all the translations have been done. Note that a greyed out tick indicates an obsolete translation, i.e. a phrase that was translated in a previous version of the application but which does not occur in the new version.</p>
<p>The contexts are ordered alphabetically. The phrases within each context are in the order in which they appear in the source program and this may not be the order in which they are shown on screen.</p>
<p>The Context List is a dockable window so it can be dragged to another position in the main window, or dragged out of the main window to be a window in its own right. If you move the Context List, <em>TQt Linguist</em> will remember its position and restore it whenever you start the program.</p>
<h4><aname="2-2"></a>Source Text Area</h4>
<p>This appears at the top right of the main window by default. The first column, 'Done', signifies the status of the translation. A tick indicates that the phrase has been translated and passed validation. A question mark indicates that the translation has not been done. An exclamation mark indicates that the translation has failed validation. The second column 'Source text' shows the text that must be translated. The third column shows the translation.</p>
<p><em>TQt Linguist</em> provides three kinds of validation: accelerator, punctuation and phrase. If the source text contains an accelerator i.e. an ampersand, '&' and the translated text does not contain an ampersand the translation will fail the accelerator validation. Similarly, if the source text ends with a particular punctuation mark, e.g. '?', '!' or '.' and the translation ends with a different punctuation mark the translation will fail the punctuation validation. If the source text has a translation in one of the open phrase books that differs from the translation used the translation will fail phrase validation. (See <ahref="linguist-manual-3.html#5">Validation</a>.)</p>
<p>The Source Text Area is a dockable window.</p>
<h4><aname="2-3"></a>Translation Area</h4>
<p>This area appears at the middle right of the main window by default. It is comprised of three vertical sections. The first section is labelled 'Source text' below which the source text appears. The second section contains contextual information on a light blue background that the programmer has added to assist the translator. If no contextual information has been given this section does not appear. The third section is labelled 'Translation' and this is where you enter the translation of the source text.</p>
<h4><aname="2-4"></a>Phrases and Guesses Area</h4>
<!-- index Phrases!in TQt Linguist --><!-- index Guesses!in TQt Linguist --><p>This area appears at the bottom right of the main window by default. When you move to a new phrase if the phrase is in one of the phrase books that has been loaded the phrase will appear in this area with its translation. If the phrase is the same or similar to another phrase that has already been translated the phrase and translation will be shown in this area. To copy a translation from the phrases and guesses area press <b>F6</b> to move to the phrases and guesses area, use the up and down arrow keys to move to the phrase you want to use and press Enter to copy it. If you decide that you don't want to copy a phrase after all, press Esc. In both cases the focus will return to the Translation area. Alternatively, double click the translation you want to use and it will be copied into the translation area.</p>
<p>The Phrases and Guesses Area is a dockable window.</p>
<h3><aname="3"></a>Common Tasks</h3>
<h4><aname="3-1"></a>Leaving a Translation for Later</h4>
<p>If you wish to leave a translation press <b>Ctrl+L</b> (Next Unfinished) to move to the next unfinished translation. An unfinished translation is one that either has not been translated at all or one which fails validation. To move to the next phrase press <b>Shift+Ctrl+L</b>. You can also navigate using the Translation menu. If you want to go to a different context entirely, click the context you want to work on in the Context list, then click the source text in the Source Text area.</p>
<h4><aname="3-2"></a>Phrases That Retquire Multiple Translations Depending on Context</h4>
<!-- index Contexts!for Translation --><!-- index Comments!for Translators --><p>The same phrase may occur in two or more contexts without conflict. Once a phrase has been translated in one context, <em>TQt Linguist</em> notes that the translation has been made and when the translator reaches a later occurrence of the same phrase <em>TQt Linguist</em> will provide the previous translation as a possible translation candidate in the phrases and guesses area. If the previous translation is acceptable just click the <em>Done & Next</em> button (press <b>Ctrl+Enter</b>) to move on to the next unfinished phrase.</p>
<p>If a phrase occurs more than once in a particular context it will only be shown once in <em>TQt Linguist</em>'s context list and the translation will be applied to every occurrence within the context. If the same phrase needs to be translated differently within the same context the programmer must provide a distinguishing comment for each of the phrases concerned. If such comments are used the duplicate phrases will appear in the context list. The programmers comments will appear in the translation area on a light blue background.</p>
<!-- index Accelerators --><!-- index Keyboard Accelerators --><p>A keyboard accelerator is a key combination that when pressed will cause an application to perform an action. Keyboard accelerators normally come in two forms: Alt key and Ctrl key accelerators.</p>
<!-- index Alt Key --><p>Alt key accelerators are used for menus and buttons. The underlining signifies that pressing the Alt key with the underlined letter is the same as clicking the menu item with the mouse. For example, most applications have a <em>File</em> menu with the "F" in the word "file" underlined. In these applications the file menu can be invoked either by clicking the word "File" on the menu bar or by pressing Alt+F. The accelerator key which is underlined is signified by preceeding it with an ampersand, e.g. <em></em>&File. If a source phrase appears with an ampersand in it then the translation should also contain an ampersand, preferably in front of the same letter. The meaning of Alt key accelerators can be determined from the phrase in which the ampersand is embedded. The translator may need to change the letter used with the Alt key, e.g. if the translated phrase does not contain the original accelerator letter. Conflicts with other keys, i.e. having two Alt key accelerators using the same letter in the same context, must be avoided. Note that some Alt key accelerators, usually those on the menu bar, may apply in other contexts.</p>
<!-- index Ctrl Key --><p>Ctrl key accelerators can exist independently of any visual control. They are often used to invoke actions in menus that would otherwise take several keystrokes or mouse clicks. They may also be used to perform actions that do not appear in any menu or on any button. For example, most applications that have a <em>File</em> menu have a submenu item called <em>New</em>. In many applications this will appear as "<u>N</u>ew... Ctrl+N". This menu option could be invoked by clicking <em>File</em> then clicking <em>New</em> with the mouse. Or you could press Alt+F then press N since these letters are underlined. But the same thing can be achieved simply by pressing <b>Ctrl+N</b>. Accelerators that use the Ctrl key are shown literally in the source text, e.g. <b>Ctrl+Enter</b>. Ctrl key accelerators have no phrase so the translator<!-- index Comments!for --> Translators must rely on the programmer to add a "comment" which appears in the top right hand pane. This comment should explain what action the Ctrl key accelerator performs. Ideally Ctrl key accelerators are translated simply by copying them by chossing the <em>Begin from Source</em> entry in the <b>Translations</b> menu. However in some cases the letter will not make sense in the target language and must be changed. Whatever letter (or digit) is chosen, the translation should always be in the form "Ctrl+" followed by the letter or digit in upper case. As with Alt key accelerators, if the translator changes the key it must not conflict with any other Ctrl key accelerator.</p>
<p>Later versions of <em>TQt Linguist</em> are expected to help the translator avoid accelerator conflicts.</p>
<h4><aname="3-4"></a>Dealing with Phrases that Contain Variables</h4>
<p>Some phrases contain variables. Variables are placeholders for items of text that are filled in at runtime. They are signified in the source text with a percent sign followed by a digit, e.g. <em>After processing file %1, file %2 is next in line</em>. In this example, <tt>%1</tt> will be replaced at runtime with the name of the first file to be processed and <tt>%2</tt> with the name of the next file to be processed. In the translated version the variables must still appear. For example a German translation might reverse the phrases, e.g. <em>Datei %2 wird bearbeitet, wenn. Datei %1 fertig ist</em>. Note that both variables are still used but their order has changed. The order in which variables appear does not matter; <tt>%1</tt> will always be replaced by the same text at runtime no matter where it appears in the source text or translation and similarly <tt>%2</tt>, etc.</p>
<h4><aname="3-5"></a>Reusing Translations</h4>
<p>If the translated text is similar to the source text, choose the <em>Begin from Source</em> entry in the <b>Translations</b> menu (press <b>Ctrl+B</b>) which will copy the source text into the translation area.</p>
<p><em>TQt Linguist</em> automatically lists phrases from the open phrase books and similar or identical phrases that have already been translated in the Phrases and guesses area.</p>
<h3><aname="4"></a>Creating and Using Phrase Books</h3>
<!-- index Phrases!in TQt Linguist --><!-- index Phrase Books --><palign="center"><imgalign="middle"src="phrasebookdialog.png"width="431"height="277">
</p>
<blockquote><palign="center"><em>Phrase Book Dialog</em></p></blockquote>
<p>A <em>TQt Linguist</em> phrase book is a set of source phrases, target (translated) phrases, and optional definitions. Phrase Books are created independently of any application, although typically one phrase book will be created per application or family of applications.</p>
<p>If the translator reaches an untranslated phrase that is the same as a source phrase in the phrase book, <em>TQt Linguist</em> will show the phrase book entry in the <em>Relevant phrases</em> panel at the bottom right of the main window. Phrases which have translations that conflict with those given in the phrase book are marked with a question mark in the source text pane. Phrase Books are used to provide a common set of translations to help ensure consistency. They can also be used to avoid duplication of effort since the translations for a family of applications can be produced once in the phrase book and the phrase book used for the majority of translations in each application.</p>
<p>Before a phrase book can be edited it must be created or if it already exists, opened. Create a new phrase book by selecting <b>Phrase|New Phrase Book</b> from the menu bar. You must enter a filename and may change the location of the file if you wish. A newly created phrase book is automatically opened. Open an existing phrase book by choosing <b>Phrase|Open Phrase Book</b> from the menu bar.</p>
<p>To add a new phrase click the <b>New Phrase</b> button (or press Alt+N) and type in a new source phrase. Press Tab and type in the translation. Optionally press Tab and enter a definition -- this is useful to distinguish different translations of the same source phrase. This process may be repeated as often as necessary.</p>
<p>You can delete a phrase by selecting it in the phrases list and clicking Remove Phrase.</p>
<p>Click the <em>Save</em> button (press Alt+S) and then click the <em>Close</em> button (press Esc) once you've finished adding (and removing) phrases.</p>
<p>When a phrase or set of phrases appears in the phrase book double clicking the required target phrase will copy it to the translation pane at the text cursor position. If you want to <em>replace</em> the text in the translation pane with the target phrase, click the translation pane, choose <b>Edit|Select All</b> (press <b>Alt+A</b>) and then double click the target phrase.</p>
<!-- index Validation of Translations --><!-- index Accelerators!Validation --><!-- index Punctuation!Validation --><!-- index Phrases!Validation --><p><em>TQt Linguist</em> provides three kinds of validation on translated phrases.</p>
<oltype=1><li><p><em>Accelerator validation</em> detects translated phrases that do not have an ampersand when the source phrase does and vice versa.</p>
<li><p><em>Punctuation validation</em> detects differences in the terminating punctuation between source and translated phrases when this may be significant, e.g. warns if the source phrase ends with an ellipsis, exclamation mark or question mark, and the translated phrase doesn't and vice versa.</p>
<li><p><em>Phrases validation</em> detects source phrases that are also in the phrase book but whose translation differs from that given in the phrase book.</p>
</ol><p>Validation may be switched on or off from the menu bar's Validation item or using the toolbar buttons. Phrases that fail validation are marked with a question mark in the source text pane. If you switch validation off and then switch it on later, <em>TQt Linguist</em> will recheck all phrases and mark any that fail validation.</p>
<p>If any phrase in a context is invalid then the context itself will be marked with a question mark; if all the phrases in a context are done and are valid the context will be marked with a tick.</p>
<p>Note that only phrases which are marked as done (with a tick) will appear in the application. Invalid phrases and phrases which are translated but not marked as done are kept in the translation source file but are not used by the application.</p>
<h3><aname="6"></a>TQt Linguist Reference</h3>
<h4><aname="6-1"></a>File Types</h4>
<p><em>TQt Linguist</em> makes use of three kinds of file:</p>
<!-- index .ts Files --><!-- index Translation Source Files --><!-- index .qm Files --><!-- index TQt Message Files --><!-- index .qph Files --><!-- index TQt Phrase Book Files --><ul><li><p><tt>.ts</tt><em>translation source files</em><br> are human-readable XML files containing source phrases and their translations. These files are usually created and updated by <ahref="linguist-manual-2.html#2">lupdate</a> and are specific to an application.</p>
<li><p><tt>.qm</tt><em>TQt message files</em><br> are binary files that contain translations used by an application at runtime. These files are generated by <ahref="linguist-manual-2.html#3">lrelease</a>, but can also be generated by <em>TQt Linguist</em>.</p>
<li><p><tt>.qph</tt><em>TQt phrase book files</em><br> are human-readable XML files containing standard phrases and their translations. These files are created and updated by <em>TQt Linguist</em> and may be used by any number of projects and applications.</p>
<ul><li><p><em>Open... Ctrl+O</em><br> pops up an open file dialog from which a translation source <tt>.ts</tt> file can be chosen.</p>
<li><p><em>Save Ctrl+S</em><br> saves the current translation source <tt>.ts</tt> file.</p>
<li><p><em>Save As...</em><br> pops up a save as file dialog so that the current translation source <tt>.ts</tt> file may be saved with a different name and/or put in a different location.</p>
<li><p><em>Release...</em><br> pops up a save as file dialog. The filename entered will be a TQt message <tt>.qm</tt> file of the translation based on the current translation source file. The release manager's command line tool <ahref="linguist-manual-2.html#3">lrelease</a> performs the same function on <em>all</em> of an application's translation source files.</p>
<li><p><em>Print... Ctrl+P</em><br> pops up a print dialog. If you click OK the translation source and the translations will be printed.</p>
<li><p><em>Recently opened files</em><br> shows the <tt>.ts</tt> files that have been opened recently, click one to open it.</p>
<ul><li><p><em>Undo Ctrl+Z</em><br> undoes the last editing action in the translation pane.</p>
<li><p><em>Redo Ctrl+Y</em><br> redoes the last editing action in the translation pane.</p>
<li><p><em>Cut Ctrl+X</em><br> deletes any highlighted text in the translation pane and saves a copy to the clipboard.</p>
<li><p><em>Copy Ctrl+C</em><br> copies the highlighted text in the translation pane to the clipboard.</p>
<li><p><em>Paste Ctrl+V</em><br> pastes the clipboard text into the translation pane.</p>
<li><p><em>Select All Ctrl+A</em><br> selects all the text in the translation pane ready for copying or deleting.</p>
<li><p><em>Find... Ctrl+F</em><br> pops up the <ahref="linguist-manual-3.html#6-4">Find dialog</a>. When the dialog pops up enter the text to be found and click the <em>Find Next</em> button. Source phrases, translations and comments may be searched.</p>
<li><p><em>Find Next F3</em><br> finds the next occurrence of the text that was last entered in the Find dialog.</p>
</ul><li><p><em>Translation</em></p>
<ul><li><p><em>Prev Unfinished Ctrl+K</em><br> moves to the nearest previous unfinished source phrase (unfinished means untranslated or translated but failed validation).</p>
<li><p><em>Next Unfinished Ctrl+L</em><br> moves to the next unfinished source phrase.</p>
<li><p><em>Prev Shift+Ctrl+K</em><br> moves to the previous source phrase.</p>
<li><p><em>Next Shift+Ctrl+L</em><br> moves to the next source phrase.</p>
<li><p><em>Done & NextCtrl+Enter</em><br> mark this phrase as 'done' (translated) and move to the next unfinished source phrase.</p>
<li><p><em>Begin from Source Ctrl+B</em><br> copies the source text into the translation.</p>
</ul><li><p><em>Validation</em> (See the <ahref="linguist-manual-3.html#5">Validation</a> section)</p>
<ul><li><p><em>Accelerators</em><br> toggles validation on or off for Alt accelerators.</p>
<li><p><em>Ending Punctuation</em><br> switches validation on or off for phrase ending punctuation, e.g. ellipsis, exclamation mark, question mark, etc.</p>
<li><p><em>Phrase Matches</em><br> sets validation on or off for matching against translations that are in the current phrase book.</p>
</ul><li><p><em>Phrase</em> (See the section <ahref="linguist-manual-3.html#4">Creating and Using Phrase Books</a> for details.)</p>
<ul><li><p><em>New Phrase Book... Ctrl+N</em><br> pops up a save as file dialog. You must enter a filename to be used for the phrase book and save the file. Once saved you should open the phrase book to begin using it.</p>
<li><p><em>Open Phrase Book... Ctrl+H</em><br> pops up an open file dialog. Find and choose a phrase book to open.</p>
<li><p><em>Close Phrase Book</em><br> closes the current phrase book. This will stop any further phrase validation taking place. The same effect can be achieved by switching off phrase validation using the Validation menu or the phrase toolbar button.</p>
<li><p><em>Edit Phrase Book...</em><br> pops up the <ahref="linguist-manual-3.html#6-5">phrase book dialog</a> where you can add, edit or delete phrases.</p>
<li><p><em>Print Phrase Book...</em><br> pops up a print dialog. If you click OK the phrase book will be printed.</p>
</ul><li><p><em>View</em></p>
<ul><li><p><em>Revert Sorting</em><br> puts the phrases in the source text pane into their original order.</p>
<li><p><em>Display Guesses</em><br> turns the display of phrases and guesses on or off.</p>
<li><p><em>Statistics</em><br> toggles the visibility of the Statistics dialog.</p>
<li><p><em>Views</em><br> toggles the visibility of the Context, Source text and Phrase views.</p>
<li><p><em>Toolbars</em><br> toggles the visibility of the different toolbars.</p>
<p>Choose <b>Edit|Find</b> from the menu bar or press <b>Ctrl+F</b> to pop up the Find dialog. Press <b>F3</b> to repeat the last search. By default the source phrases, translations and comments will all be searched and the search will be case-insensitive. These settings can be changed by checking or unchecking the checkboxes to reflect your preferences.</p>
<h4><aname="6-5"></a>The Phrase Dialog</h4>
<p>This dialog is explained in the <ahref="linguist-manual-3.html#4">Creating and Using Phrase Books</a> section.</p>
