Qt Linguist is a tool for adding translations to Qt applications. To start, run Qt Linguist, either from the taskbar menu, or by double clicking the desktop icon, or type linguist (followed by Enter) at the command line. Once Qt Linguist has started choose File|Open from the menu bar and select a .ts translation source file to work on. If you do not have a .ts file to work on, see the release manager manual on how to generate one.
By default, Qt Linguist's main window is divided into four main areas. The left hand side contains the Context List, the top right shows the String List, the middle right is the Translation Area and the bottom right shows either the Phrases and Guesses Window, the Source Code Window or the Warnings Window. We will describe them all in detail later.
First open a translation file choosing File|Open... in the menu bar. 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 String List (top right). The phrase will be copied into the Translation Area (middle right). Click under the word 'translation' and type in the translation. Press Ctrl+Enter (Done & Next) to confirm that you have completed the translation and to move on to the next phrase that requires translation. The cycle of entering a translation and pressing Ctrl+Enter can be repeated until all the translations are done or until you finish the session.
Additional help for the translation is provided in the area at the bottom right: If you activate the Phrases and Guesses Window (e.g. by clicking on its tab), Qt Linguist will show possible translations from open phrase books and previous translations. Each has a keyboard shortcut, e.g. Ctrl+1, Ctrl+2, 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.) Qt Linguist can also check for you if the source and the translation obey certain consistency rules: The results are shown in the Warnings Window. Finally, if you have the source code of the program to translate available, the Source Code Window can help you to get to know the context where a translation is used.
At the end of the session choose File|Save from the menu bar and then File|Exit to quit.
This appears at the left hand side of the main window by default. The first column identifies whether or not the translations for the context have been done. A tick indicates that all the translations have been done. Otherwise a question mark is shown. Note that a greyed out tick indicates an obsolete translation context, i.e. a context that was translated in a previous version of the application but which does not occur in the new version. See also Context States.
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. Click on the appropriate header to sort the Context List either by the status, the name or the number of items in a context.
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, Qt Linguist will remember its position and restore it whenever you start the program. If the dock has been closed or is hidden it can be made visible by pressing F6.
String List
This appears at the top right of the main window by default. The first column signifies the status of the translation. A tick indicates that the phrase has been translated and is finished: If it is grey, the translation is obsolete. A yellow tick marks a finished translation which does not pass the automatic validation tests (see Validation). Other finished translations have a green tick. A question mark indicates that the translation has not been done. An exclamation mark indicates that the translation is unfinished and has failed validation. See also Message States. The second column 'Source text' shows the text that must be translated. The third column shows the translation.
The String List is a dockable window. If it has been closed or is hidden it can be made visible by pressing F7.
Translation Area
This area appears at the middle right of the main window by default. At the top is the text to translate under the label "Source text", at the bottom the input field or (in the case of plural forms) multiple input fields for editing the translations. The number of fields, as well as their description, depend on the language to translate to. See also Changing the Target Locale.
The programmer can provide additional information about a certain translation. If available, this information will appear right beneath the source text on a light blue background. Furthermore, you can display auxiliary translations: These are translations of the same source text in other languages, and are displayed above the translation input fields. The fields are only visible in case you explicitly loaded an auxiliary translation file, and the file actually contains a translation for the source text (see Auxiliary Translations).
Phrases and Guesses Window
This window appears at the bottom right of the main window by default. If the text to translate is in one of the phrase books that has been loaded, the phrase will appear in this window 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 window. To copy a translation from the Phrases and Guesses Window press F10 to move to the Phrases and Guesses Window, 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.
The Phrases and Guesses Window is a dockable window. If it has been closed or is hidden it can be made visible by pressing F10.
Source Code Window
This window appears at the bottom right of the main window by default. If the appropriate files are available locally, the window shows the context of the source code the source text was extracted from. The corresponding line is centered vertically, and highlighted. If the file containing the source code is not available, or not at the expected folder, an error message containing the expected absolute file path is shown.
The Source Code Window is a dockable window. If it has been closed or is hidden it can be made visible by pressing F9.
Warnings Window
This window appears at the bottom right of the main window by default. It shows the active validation checks that the current translation fails. The first warning is also shown in the main window's status bar.
The Warnings Window is a dockable window. If it has been closed or is hidden it can be made visible by pressing F8.
Common Tasks
Leaving a Translation for Later
If you wish to leave a translation press Ctrl+L (Next Unfinished) to move to the next unfinished translation. To move to the next translation (whether finished or unfinished) press Shift+Ctrl+L. 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 String List.
Phrases That Require Multiple Translations Depending on Context
The same phrase may occur in two or more contexts without conflict. Once a phrase has been translated in one context, Qt Linguist notes that the translation has been made and when the translator reaches a later occurrence of the same phrase Qt Linguist will provide the previous translation as a possible translation candidate in the Phrases and Guesses Window.
If a phrase occurs more than once in a particular context it will only be shown once in Qt Linguist'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.
Changing Keyboard Accelerators
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.
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 File 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 preceding it with an ampersand, e.g. &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.
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 File menu have a submenu item called New. In many applications this will appear as "New Ctrl+N". This menu option could be invoked by clicking File then clicking New 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 Ctrl+N. Accelerators that use the Ctrl key are shown literally in the source text, e.g. Ctrl+Enter. Ctrl key accelerators have no phrase so the translator 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 choosing the Begin from Source entry in the Translation 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: Qt will automatically display the correct name at runtime. As with Alt key accelerators, if the translator changes the key it must not conflict with any other Ctrl key accelerator.
Warning: Do not translate the "Alt", "Ctrl" or "Shift" parts of the accelerators, since Qt internally relies on these identifiers. For the supported languages, Qt will automatically translate these strings.
Dealing with Phrases That Contain Variables
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. After processing file %1, file %2 is next in line. In this example, %1 will be replaced at runtime with the name of the first file to be processed and %2 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. Datei %2 wird bearbeitet, wenn Datei %1 fertig ist. Note that both variables are still used but their order has changed. The order in which variables appear does not matter; %1 will always be replaced by the same text at runtime no matter where it appears in the source text or translation and similarly %2, etc.
Reusing Translations
If the translated text is similar to the source text, choose the Begin from Source entry in the Translation menu (press Ctrl+B) which will copy the source text into the Translation Area.
Qt Linguist automatically lists phrases from the open phrase books and similar or identical phrases that have already been translated in the Phrases and Guesses Window.
Showing Auxiliary Translations
Qt Linguist currently only allows one translation file to be worked on at any given time. However, if the program has already been translated to other languages, you can display these auxiliary translations in addition to the source text.
This feature enables translators who are not familiar with the language used for the source text to create new translations based on existing ones. This "translation chain" approach enables a wider range of translation services to be used, since translators only need to know one of the of the languages for which an existing translation is available.
The list of auxiliary files to display is managed in the Auxiliary Languages dialog, which can be activated by selecting Other Languages... in the Phrases menu.
By default the list of auxiliary files is empty. Click on the folder button (the fourth from the left) to select files containing other translations of the same source. If you select multiple files you can sort them in the dialog by the up- and down buttons. Auxiliary translations for the selected locales will show up in the Translation Area if an auxiliary translation is available.
Changing the Target Locale
Qt Linguist displays the language to translate to in the Translation Area, and adapts the number of input fields for plural forms accordingly. If not explicitly set, Qt Linguist guesses the target language and country by evaluating the translation source file name: E.g. app_de.ts sets the target language to German, and app_de_ch.ts sets the target language to German and the target country to Switzerland (this also helps loading translations for the current locale automatically; see Programmers Manual for details). If your files do not follow this convention, you can also set the locale information explicitly by activating Translation File Settings... in the Edit menu.
Phrase Books
A Qt Linguist phrase book is a set of source phrases, target (translated) phrases, and optional definitions. Typically one phrase book will be created per language and family of applications. 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. If the translator reaches an untranslated phrase that is the same as a source phrase in a phrase book, Qt Linguist will show the phrase book entry in the Phrases and Guesses Window.
Creating and Editing Phrase Books
Before a phrase book can be edited it must be created or, if it already exists, opened. Create a new phrase book by selecting Phrase|New Phrase Book 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 Phrase|Open Phrase Book from the menu bar.
The phrase book contents can be displayed and changed by selecting Phrase|Edit Phrase Book, and then activating the phrase book you want to work on. This will pop up the Phrase Book Dialog as shown in the image above. To add a new phrase click the New Phrase 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. You can delete a phrase by selecting it in the phrases list and clicking Remove Phrase. Click the Close button (press Esc) once you've finished adding (and removing) phrases.
Shortcuts for Editing Phrase Books
You can also create a new phrase book entry directly out of the translation you are working on: Clicking Phrases|Add to Phrase Book or pressing Ctrl+T will add the source text and the content of the first translation field to the current phrase book. If multiple phrase books are loaded, you have to specify the phrase book to add the entry to in a dialogue. If you detect an error in a phrase book entry that is shown in the Phrases and Guesses Window, you can also edit it in place by right clicking on the entry, and selecting Edit. After fixing the error press Return to leave the editing mode.
Batch Translation
Use the batch translation feature of Qt Linguist to automatically translate source texts that are also in a phrase book. Selecting Tools|Batch Translation will show you the batch translation dialog, which let you configure which phrase books to use in what order during the batch translation process. Furthermore you can set whether only entries with no present translation should be considered, and whether batch translated entries should be set to finished (see also Message States).
Validation
Qt Linguist provides four kinds of validation on translated phrases.
Accelerator validation detects translated phrases that do not have an ampersand when the source phrase does and vice versa.
Punctuation validation 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.
Phrases validation detects source phrases that are also in the phrase book but whose translation differs from that given in the phrase book.
Place marker validation detects whether the same variables (like %1, %2) are used both in the source text and in the translation.
Validation may be switched on or off from the menu bar's Validation item or using the toolbar buttons. Unfinished phrases that fail validation are marked with an exclamation mark in the source text pane. Finished phrases will get a yellow tick instead. If you switch validation off and then switch it on later, Qt Linguist will recheck all phrases and mark any that fail validation. See also Message States.
Form Preview
Forms created by Qt Designer are stored in special .ui files. Qt Linguist can make use of these .ui files to show the translations done so far on the form itself. This of course requires access to the .ui files during the translation process. Activate Tools|Open/Refresh Form Preview to open the window shown above. The list of .ui files Qt Linguist has detected are displayed in the Forms List on the left hand. If the path to the files has changed, you can load the files manually via File|Open Form.... Double-click on an entry in the Forms List to display the Form File. Select <No Translation> from the toolbar to display the untranslated form.
Qt Linguist Reference
Message States
A message in Qt Linguist can be in a variety of states, depending on whether the translation has been marked as finished, the source text is obsolete, a translation has been provided or the translation fails a validity check. Qt Linguist summarizes these properties in six overall states that are shown as individual icons in the first row of the String List:
The message is marked as finished, and there are no warnings. Clicking on the icon or editing a translation will mark the message as unfinished. Also, if the source text is changed by lupdate, the message is automatically set to unfinished.
The message is marked as finished while there are warnings. Clicking on the icon or editing a translation will mark it as unfinished. Also, if the source text is changed by lupdate, the message is automatically set to unfinished.
The message is obsolete. See the Release Manager manual on how to remove such messages from the file.
The message is unfinished, and no translation has been provided. This is default state for messages that were not changed before. You should insert a translation.
The message is unfinished, but not empty. Furthermore, there are no warnings generated by validity checks. Clicking on the icon or pressing Ctrl+Enter (Done & Next) will mark it as finished.
The message is unfinished, and there are warnings about the translation. It is recommended to fix these first, but if the warnings are wrong you can just click on the icon or press Ctrl+Return (Done & Next) to mark the message as finished.
Context States
The states of the individual messages in a context are also summarized in a context state:
All messages in the context are marked as finished.
All the messages in the context are obsolete.
At least one message in the context is not marked as finished.
File Types
Qt Linguist makes use of four kinds of files:
.tstranslation source files are human-readable XML files containing source phrases and their translations. These files are usually created and updated by lupdate and are specific to an application.
.xlfXLIFF files are human-readable XML files that adhere to the international XML Localization Interchange File Format. Qt Linguist can be used to edit XLIFF files generated by other programs. For standard Qt projects, however, only the .ts file format is used.
.qmQt message files are binary files that contain translations used by an application at runtime. These files are generated by lrelease, but can also be generated by Qt Linguist.
.qphQt phrase book files are human-readable XML files containing standard phrases and their translations. These files are created and updated by Qt Linguist and may be used by any number of projects and applications.
The Menu Bar
File
Open... Ctrl+O pops up an open file dialog from which a translation source .ts or .xlf file can be chosen.
Recently opened files shows the .ts files that have been opened recently, click one to open it.
Save Ctrl+S saves the current translation source file.
Save As... pops up a save as file dialog so that the current translation source file may be saved with a different name, format and/or put in a different location.
Release create a Qt message .qm file with the same base name as the current translation source file. The release manager's command line tool lrelease performs the same function on all of an application's translation source files.
Release As... pops up a save as file dialog. The filename entered will be a Qt message .qm file of the translation based on the current translation source file. The release manager's command line tool lrelease performs the same function on all of an application's translation source files.
Print... Ctrl+P pops up a print dialog. If you click OK the translation source and the translations will be printed.
Exit Ctrl+Q closes Qt Linguist.
Edit
Undo Ctrl+Z undoes the last editing action in the translation pane.
Redo Ctrl+Y redoes the last editing action in the translation pane.
Cut Ctrl+X deletes any highlighted text in the translation pane and saves a copy to the clipboard.
Copy Ctrl+C copies the highlighted text in the translation pane to the clipboard.
Paste Ctrl+V pastes the clipboard text into the translation pane.
Select All Ctrl+A selects all the text in the translation pane ready for copying or deleting.
Find... Ctrl+F pops up the Find dialog. When the dialog pops up enter the text to be found and click the Find Next button. Source phrases, translations and comments may be searched.
Find Next F3 finds the next occurrence of the text that was last entered in the Find dialog.
Search and Translate... pops up the Search and Replace Dialog. Use this dialog to translate the same text in multiple items.
Translation File Settings... let you configure the target language and the country/region of a translation source file.
Translation
Prev Unfinished Ctrl+K moves to the nearest previous unfinished source phrase (unfinished means untranslated or translated but failed validation).
Next Unfinished Ctrl+L moves to the next unfinished source phrase.
Prev Shift+Ctrl+K moves to the previous source phrase.
Next Shift+Ctrl+L moves to the next source phrase.
Done & Next Ctrl+Enter mark this phrase as 'done' (translated) and move to the next unfinished source phrase.
Begin from Source Ctrl+B copies the source text into the translation.
Accelerators toggles validation on or off for Alt accelerators.
Ending Punctuation switches validation on or off for phrase ending punctuation, e.g. ellipsis, exclamation mark, question mark, etc.
Phrase Matches sets validation on or off for matching against translations that are in the current phrase book.
Place Marker Matches sets validation on or off for the use of the same place markers in the source and translation.
Phrases (See the section Phrase Books for details.)
New Phrase Book... Ctrl+N 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.
Open Phrase Book... Ctrl+H pops up an open file dialog. Find and choose a phrase book to open.
Close Phrase Book displays the list of phrase books currently opened. Clicking on one of the items will close the phrase book. If the phrase book has been modified, a dialog box asks whether Qt Linguist should save the changes.
Edit Phrase Book... displays the list of phrase books currently opened. Clicking on one of the items will open the Phrase Book Dialog where you can add, edit or delete phrases.
Print Phrase Book... displays the list of phrase books currently opened. Clicking on one of the items pops up a print dialog. If you click OK the phrase book will be printed.
Add to Phrase Book Ctrl+T Adds the source text and translation currently shown in the Translation Area to a phrase book. If multiple phrase books are loaded, a dialog box let you specify select one.
Cette page est une traduction d'une page de la documentation de Qt, écrite par Nokia Corporation and/or its subsidiary(-ies). Les éventuels problèmes résultant d'une mauvaise traduction ne sont pas imputables à Nokia.
Vous avez déniché une erreur ? Un bug ? Une redirection cassée ? Ou tout autre problème, quel qu'il soit ? Ou bien vous désirez participer à ce projet de traduction ? N'hésitez pas à nous contacter
ou par MP !
