Contents

The One Minute Guide to Using Qt Linguist

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.

The Qt Linguist Window

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.

Context 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.

Strings Window

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:

The string list is a dockable subwindow. If it has been closed, restored it by pressing F7.

The Translation Area

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.

Phrases and Guesses Window

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.

Sources and Forms Window

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.

Warnings Window

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.

Translating Multiple Languages Simultaneously

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.

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, causes an application to perform an action. There are two kinds of keyboard accelerators: Alt key and Ctrl key accelerators.

Alt 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

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.

Handling Numbered Arguments and Plurals

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.)

Reusing Translations

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.

Changing the Target Locale

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.

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 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.

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 Edit|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).

Validation Tests

Qt Linguist provides four kinds of validation tests for translations.

1. Accelerator validation detects translated phrases that do not have an ampersand when the source phrase does and vice versa.
2. 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.
3. Phrases validation detects source phrases that are also in the phrase book but whose translation differs from that given in the phrase book.
4. 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 String Translation 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 non-translated form.

Qt Linguist Reference

File Types

Qt Linguist makes use of four kinds of files:

• TS translation 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.
• .xlf XLIFF 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. However, for standard Qt projects, only the TS file format is used.

  Note: The minimum supported version for XLIFF format files is 1.1. XLIFF 1.0 version files are not supported.

• QM Qt message files
  are binary files that contain translations used by an application at run-time. These files are generated by lrelease, but can also be generated by Qt Linguist.
• .qph Qt 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 non-translated 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.
  • Copy from source text Ctrl+B
    copies the source text into the translation.
• Validation (See Validation Tests)
  • 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.
• Tools
  • Batch Translation...
    Opens a dialog which let you automatically insert translations for source texts which are in a phrase book.
  • Open/Refresh Form Preview F3
    Opens the Form Preview. This window let you instantly see translations for forms created with Qt Designer.
• View
  • Revert Sorting
    puts the items in the context list and in the string list into their original order.
  • Display Guesses
    turns the display of phrases and guesses on or off.
  • Statistics
    toggles the visibility of the Statistics dialog.
  • Views
    toggles the visibility of the Context Window, Strings Window, Phrases and Guesses Window, Warnings Window, or Sources and Forms Window.
  • Toolbars
    toggles the visibility of the different toolbars.
• Help
  • Manual F1
    opens this manual.
  • About Qt Linguist
    Shows information about Qt Linguist.
  • About Qt
    Shows information about Qt.
  • What's This? Shift+F1
    Click on one item in the main window to get additional information about it.

The Toolbar

• 
  Pops up the open file dialog to open a new translation source TS file.
• 
  Saves the current translation source TS file.
• 
  Prints the current translation source TS file.
• 
  Pops up the file open dialog to open a new phrase book .qph file.
• 
  Undoes the last editing action in the translation pane.
• 
  Redoes the last editing action in the translation pane.
• 
  Deletes any highlighted text in the translation pane and save a copy to the clipboard.
• 
  Copies the highlighted text in the translation pane to the clipboard.
• 
  Pastes the clipboard text into the translation pane.
• 
  Pops up the Find dialog .
• 
  Moves to the previous source phrase.
• 
  Moves to the next source phrase.
• 
  Moves to the previous unfinished source phrase.
• 
  Moves to the next unfinished source phrase.
• 
  Marks the phrase as 'done' (translated) and move to the next unfinished source phrase.
• 
  Toggles accelerator validation on and off.
• 
  Toggles phrase ending punctuation validation on and off.
• 
  Toggles phrase book validation on or off.
• 
  Toggles place marker validation on or off.