Contents
Qt Linguist is a tool for adding translations to Qt applications. Run Qt Linguist from the taskbar menu, or by double clicking the desktop icon, or by entering the command linguist at the command line. Once Qt Linguist has started, choose File|Open from the menu bar and select a translation source (TS file) to load. If you do not have a TS file, see the release manager manual to learn how to generate one.
The Qt Linguist main window is divided into several, dockable subwindows arranged around a central translation area. The context list is normally shown on the left, and the source code, string list, and either the phrases and guesses, or the warnings are shown above and below the translations area.
With a translation file loaded, select a context from the context list on the left. Selecting a context loads the translatable strings found in that context into the string list. Selecting one of the strings copies that string as the Source text in the translation area. Click in the text entry widget below the copied string and type your translation for that string. To accept the translation, either press the green tick mark button on the toolbar, or click the icon to the left of the selected source string in the string list. Repeat this process until all strings in the string list are marked with 
or 
. Then select the next context and continue.
Translation options are shown in the phrases and guesses window. If the phrases and guesses window is not visible, click the Phrases and guesses tab at the bottom of the main window. The phrases and guesses window shows possible translations for the current string. These translation "guesses" have been read from phrase books (Phrases|Open Phrase Book...). The current strings translation is also shown here. To select a guess, double click it in the phrases and guesses window or use the keyboard shortcut shown to the right of the guess.
Qt Linguist can automatically check whether your translation strings pass a list of validation tests. Validation test failures are shown in the warnings window. If the warnings window is not visible, click the Warnings tab at the bottom of the main window.
Finally, if the source code for the contexts is accessible, the source code window shows the context where the current string is used. If the source code window is not visible, click the Sources and Forms tab at the bottom of the main window.
At the end of the session choose File|Save from the menu bar and then File|Exit to quit.
This Qt Linguist main window is divided into dockable subwindows arranged around a central translation area. The subwindows are: Context, Sources and Forms, Strings, Phrases and guesses, and Warnings (hidden in the UI snapshot). The translation area is always visible, but the dockable subwindows can be activated or deactivated in the View|Views menu, and dragged around by their title bars and dropped in the translation area or even outside the main window.
The context window normally appears on the left side of the main window. It lists the contexts in which strings to be translated appear. The column labeled Context lists the context names in alphabetical order. Each context is the name of a subclass of QObject. There can also be a context for QObject itself, which contains strings passed to the static function QObject::tr(). There can also be an <unnamed context>, which contains strings that aren't in a subclass of QObject.
To the left of the Context column is a column labeled 
. This column uses the following list of icons to summarize the current translation state for each context:
All strings in the context have been translated, and all the translations passed the validation tests. All strings in the context have been translated or marked as translated, but at least one translation failed the validation tests.
At least one string in the context has not been translated or is not marked as translated. None of the translated strings still appears in the context. This usually means the context itself no longer exists in the application.To the right of the Context column is the Items column. Each entry in the Items column is a pair of numbers separated by a slash ("/"). The number to the right of the slash is the number of translatable strings in the context. The number to the left of the slash is the number of those strings that currently have translations. i.e., if the numbers are equal, all the translatable strings in the context have translations.
In the UI snapshot above, the MessageEditor context is selected. Its Items entry shows 18/18, which means it has 18 translatable strings and all 18 strings currently have translations. However, the context has been marked with the icon, which means that at least one of the current translations failed a validation test. In the strings window to the right, we see that one of the strings is indeed marked with the icon.
The context window is a dockable window. It can be dragged to another position in the main window, or dragged out of the main window to be a separate window. If you move the context window, Qt Linguist remembers the new position and puts the context window there whenever you start the program. If the context window has been closed, it can be restored by pressing F6.
The strings window normally appears on the right in the main window, above the translation area. Its Source text column lists all the translatable strings found in the current context. Selecting a string makes that string the current string in the translation area.
To the left of the Source text column is a column labeled . This column is similar to the one in the context window, but here you can click on the icon to change the translation acceptance state for each string in the list. A tick mark, green or yellow, means the string has been translated and the user has accepted the translation. A question mark means either that the user has not accepted the string's translation or that the string doesn't have a translation. The table below explains the acceptance states and their icons:
| State | Icon | Description |
|---|---|---|
| Accepted/Correct | |
The source string has a translation (possibly empty); the user has accepted the translation, and the translation passes all the validation tests. If the translation is empty, the user has chosen to leave it empty. Click the icon to revoke acceptance of the translation and decrement the number of accepted translations in the Items column of the context list by 1. The state is reset to if the string has a translation, or to  if the string's translation is empty. If lupdate changes the contents of a string, its acceptance state is automatically reset to . |
| Accepted/Warnings | |
The user has accepted the translation, but the translation does not pass all the validation tests. The validation test failures are shown in the warnings window. Click the icon to revoke acceptance of the translation. The state is reset to  , and the number of accepted translations in the Items column of the context list is decremented by 1. |
| Not Accepted | |
The string has a non-empty translation that passes all the validation tests, but the user has not yet accepted the translation. Click the icon or press Ctrl+Enter to accept the translation. The state is reset to , and the number of accepted translations in the Items column of the context list is incremented by 1. |
| No Translation | |
The string does not have a translation. Click the icon to accept the empty translation anyway. The state is reset to , and the number of accepted translations in the Items column of the context list is incremented by 1. |
| Validation Failures | |
The string has a translation, but the translation does not pass all the validation tests. Validation test failures are shown in the warnings window. Click on the icon or press Ctrl+Return to accept the translation even with validation failures. The state is reset to . We recommended editing the translation to fix the causes of the validation failures. The state will reset automatically to , when all the failures have been fixed. |
| Obsolete | |
The string is obsolete. It is no longer used in the context. See the Release Manager for instructions on how to remove obsolete messages from the file. |
The string list is a dockable subwindow. If it has been closed, restored it by pressing F7.
The translation area is in the middle of the main window, to the right of the context list. It doesn't have a title bar, so you can't drag it around. Instead, you drag and drop the other subwindows to arrange them around the translation area. The string currently selected in the string list appears at the top of the translation area, under the label Source text. Note that all blanks in the source text have been replaced by "." so the translator can see the spacing required within the text.
If the developer provides a disambiguating comment, it will appear below the source text area, under the label Developer comments.
Below the source text and optional developer comments are two text entry widgets for the translator, one for entering the translation of the current string, and one for the translator to enter an optional comment to be read by other translators.
When multiple languages are being translated, this sequence of fields is repeated for each language. See also Changing the Target Locale.
If the current string in the string list appears in one or more of the phrase books that have been loaded, the current string and its phrase book translation(s) will be listed in this window. If the current string is the same as, or similar to, another string that has already been translated, that other string and its translation will also be listed in this window.
To use a translation from the Phrases and Guesses Window, you can double click the translation, and it will be copied into the translation area, or you can use the translation's Guess hotkey on the right. You can also press F10 to move the focus to the Phrases and Guesses Window, then use the up and down arrow keys to find the desired translation, and then press Enter to copy it to the translation area. If you decide that you don't want to copy a phrase after all, press Esc to return the focus to the translation area.
The Phrases and Guesses Window is a dockable window. If it has been closed, it can be made visible by pressing the Phrases and guesses tab at the bottom of the window, or by pressing F10.
If the source files containing the translatable strings are available to Qt Linguist, this window shows the source context of the current string in the string list. The source code line containing the current string should be shown and highlighted. If the file containing the source string is not found, the expected absolute file path is shown.
If the source context shows the wrong source line, it probably means the translation file is out of sync with the source files. To re-sync the translation file with the source files, see the lupdate manual.
The Sources and Forms window is a dockable window. If it has been closed, it can be made visible again by pressing the Sources and Forms tab at the bottom of the window, or by pressing F9.
If the translation you enter for the current string fails any of the active validation tests, the failures are listed in the warnings window. The first of these failure messages is also shown in the status bar at the bottom of the main window. Note that only active validation tests are reported. To see which validation tests are currently active, or to activate or deactivate tests, use the Validation menu from the menu bar.
The Warnings window is a dockable window. If it has been closed, it can be made visible by pressing the Warnings tab at the bottom of the window, or by pressing F8.
Qt Linguist can now load and edit multiple translation files simultaneously. One use for this is the case where you know two languages better than you know English (Polish and Japanese, say), and you are given an application's Polish translation file and asked to update the application's Japanese translation file. You are more comfortable translating Polish to Japanese than you are translating English to Japanese.
Below is the UI snapshot shown earlier, but this time with both Polish and Japanese translation files loaded.
The first thing to notice is that the translation area has text editing areas for both Polish and Japanese, and these are color-coded for easier separation. Second, the Context Window and the Strings Window both have two columns labeled instead of one, and although it may be hard to tell, these columns are also color-coded with the same colors. The left-most column in either case applies to the top-most language area (Polish above) in the translation area, and the right-most column applies to the bottom language area.
The Items column in the Context Window combines the values for both languages. The best way to see this is to look at the value for the MessageEditor context, which is the one selected in the snapshot shown above. Recall that in the first UI snapshot (Polish only), the numbers for this context were 18/18, meaning 18 translatable strings had been found in the context, and all 18 strings had accepted translations. In the UI snapshot above, the numbers for the MessageEditor context are now 1/18, meaning that both languages have 18 translatable strings for that context, but for Japanese, only 1 of the 18 strings has an accepted translation. The icon in the Japanese column means that at least one string in the context doesn't have an accepted Japanese translation yet. In fact, 17 of the 18 strings don't have accepted Japanese translations yet. We will see 18/18 in the Items column when all 18 strings have accepted translations for all the loaded translation files, e.g., both Polish and Japanese in the snapshot.
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.
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.
A keyboard accelerator is a key combination that, when pressed, causes an application to perform an action. There are two kinds of keyboard accelerators: Alt key and Ctrl key accelerators.
Alt key accelerators are used in menu selection and on buttons. The underlined character in a menu item or button label signifies that pressing the Alt key with the underlined character will perform the same action as clicking the menu item or pressing the button. 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. To identify an accelerator key in the translation text ("File") precede it with an ampersand, e.g. &File. If a string to be translated has an ampersand in it, then the translation for that string should also have an ampersand in it, preferably in front of the same character.
The meaning of an Alt key accelerator can be determined from the phrase in which the ampersand is embedded. The translator can change the character part of the Alt key accelerator, if the translated phrase does not contain the same character or if that character has already been used in the translation of some other Alt key accelerator. Conflicts with other Alt key accelerators must be avoided within a context. 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 require multiple 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 New submenu item in the File menu. The New item might appear as "New Ctrl+N" in the File menu, meaning the New menu can be invoked by simply pressing Ctrl+N, instead of either clicking File with the mouse and then clicking New with the mouse, or by entering Alt+F and N.
Each Ctrl key accelerator is shown in the string list as a separate string, e.g. Ctrl+Enter. Since the string doesn't have a context to give it meaning, e.g. like the context of the phrase in which an Alt key accelerator appears, the translator must rely on the UI developer to include a disambiguation comment to explain the action the Ctrl key accelerator is meant to perform. This disambiguating comment (if provided by the developer) will appear under Developer comments in the translation area under the Source text area.
Ideally Ctrl key accelerators are translated simply by copying them directly using Copy from source text in the Translation menu. However, in some cases the character will not make sense in the target language, and it must be changed. Whichever character (alpha or digit) is chosen, the translation must be in the form "Ctrl+" followed by the upper case character. Qt will automatically display the correct name at run-time. As with Alt key accelerators, if the translator changes the character, the new character must not conflict with any other Ctrl key accelerator.
Warning: Do not translate the "Alt", "Ctrl" or "Shift" parts of the accelerators. Qt relies on these strings being there. For supported languages, Qt automatically translates these strings.
Some phrases contain numbered arguments. A numbered argument is a placeholder that will be replaced with text at run-time. A numbered argument appears in a source string as a percent sign followed by a digit. Consider an example: After processing file %1, file %2 is next in line. In this string to be translated, %1 and %2 are numbered arguments. At run-time, %1 and %2 will be replaced with the first and next file names respectively. The same numbered arguments must appear in the translation, but not necessarily in the same order. A German translation of the string might reverse the phrases, e.g. Datei %2 wird bearbeitet, wenn Datei %1 fertig ist. Both numbered arguments appear in the translation, but in the reverse order. %i will always be replaced by the same text in the translation strings, regardless of where argument i appears in the argument sequence in the source string.
The use of numbered arguments is often accompanied by the use of plurals in the source text. In many languages, the form of the text will depend on the value shown, and more than one translation is required. If the developers have marked up the source text in correct way, fields for each of the possible plural forms will be available in the translation area. (The Writing Source Code for Translation document contains details about this feature for developers.)
If the translated text is similar to the source text, choose the Copy from source text entry in the Translation menu (press Ctrl+B) which will copy the source text into the translation area.
Qt Linguist automatically lists possible translations from any open phrase books in the Phrases and Guesses Window, as well as similar or identical phrases that have already been translated.
Qt Linguist displays the target language 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. For example, 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 using Translation File Settings in the Edit menu.
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 non-translated 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.
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.
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.
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 String Translation States).
Qt Linguist provides four kinds of validation tests for translations.
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 String Translation States.
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 non-translated form.
Qt Linguist makes use of four kinds of files:
