/**************************************************************************** ** ** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). ** Contact: Nokia Corporation (qt-info@nokia.com) ** ** This file is part of the documentation of the Qt Toolkit. ** ** $QT_BEGIN_LICENSE:LGPL$ ** No Commercial Usage ** This file contains pre-release code and may not be distributed. ** You may use this file in accordance with the terms and conditions ** contained in the Technology Preview License Agreement accompanying ** this package. ** ** GNU Lesser General Public License Usage ** Alternatively, this file may be used under the terms of the GNU Lesser ** General Public License version 2.1 as published by the Free Software ** Foundation and appearing in the file LICENSE.LGPL included in the ** packaging of this file. Please review the following information to ** ensure the GNU Lesser General Public License version 2.1 requirements ** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. ** ** In addition, as a special exception, Nokia gives you certain ** additional rights. These rights are described in the Nokia Qt LGPL ** Exception version 1.1, included in the file LGPL_EXCEPTION.txt in this ** package. ** ** If you have questions regarding the use of this file, please contact ** Nokia at qt-info@nokia.com. ** ** ** ** ** ** ** ** ** $QT_END_LICENSE$ ** ****************************************************************************/ /*! \page linguist-manual.html \title Qt Linguist Manual \ingroup qttools \startpage {index.html}{Qt Reference Documentation} \nextpage Qt Linguist Manual: Release Manager \keyword Qt Linguist Qt provides excellent support for translating applications into local languages. This Guide explains how to use Qt's translation tools for each of the roles involved in translating an application. The Guide begins with a brief overview of the issues that must be considered, followed by chapters devoted to each role and the supporting tools provided. The \l{linguist-manager.html}{Release Manager} chapter is aimed at the person with overall responsibility for the release of the application. They will typically coordinate the work of the software engineers and the translator. The chapter describes the use of two tools. The \l{lupdate} tool is used to synchronize source code and translations. The \l{lrelease} tool is used to create runtime translation files for use by the released application. The \l{linguist-translators.html}{Translators} chapter is for translators. It describes the use of the \QL tool. No computer knowledge beyond the ability to start a program and use a text editor or word processor is required. The \l{linguist-programmers.html}{Programmers} chapter is for Qt programmers. It explains how to create Qt applications that are able to use translated text. It also provides guidance on how to help the translator identify the context in which phrases appear. This chapter's three short tutorials cover everything the programmer needs to do. \section1 Overview of the Translation Process Most of the text that must be translated in an application program consists of either single words or short phrases. These typically appear as window titles, menu items, pop-up help text (balloon help), and labels to buttons, check boxes and radio buttons. The phrases are entered into the source code by the programmer in their native language using a simple but special syntax to identify that the phrases require translation. The Qt tools provide context information for each of the phrases to help the translator, and the programmer is able to add additional context information to phrases when necessary. The release manager generates a set of translation files that are produced from the source files and passes these to the translator. The translator opens the translation files using \QL, enters their translations and saves the results back into the translation files, which they pass back to the release manager. The release manager then generates fast compact versions of these translation files ready for use by the application. The tools are designed to be used in repeated cycles as applications change and evolve, preserving existing translations and making it easy to identify which new translations are required. \QL also provides a phrase book facility to help ensure consistent translations across multiple applications and projects. Translators and programmers must address a number of issues because of the subtleties and complexities of human language: \list \o A single phrase may need to be translated into several different forms depending on context, e.g. \e open in English might become \e{\ouml\c{}ffnen}, "open file", or \e aufbauen, "open internet connection", in German. \o Keyboard accelerators may need to be changed but without introducing conflicts, e.g. "\&Quit" in English becomes "Avslutt" in Norwegian which doesn't contain a "Q". We cannot use a letter that is already in use - unless we change several accelerators. \o Phrases that contain variables, for example, "The 25 files selected will take 63 seconds to process", where the two numbers are inserted programmatically at runtime may need to be reworded because in a different language the word order and therefore the placement of the variables may have to change. \endlist The Qt translation tools provide clear and simple solutions to these issues. Chapters: \list \o \l{Qt Linguist Manual: Release Manager}{Release Manager} \o \l{Qt Linguist Manual: Translators}{Translators} \o \l{Qt Linguist Manual: Programmers}{Programmers} \o \l{Qt Linguist Manual: TS File Format}{TS File Format} \endlist \QL and \c lupdate are able to import and export XML Localization Interchange File Format (XLIFF) files, making it possible to take advantage of tools and translation services that work with this format. See the \l{Qt Linguist Manual: Translators} {Translators} section for more information on working with these files. \table \row \o{1,2} \inlineimage wVista-Cert-border-small.png \o \e{Qt Linguist 4.3 is Certified for Windows Vista} \row \o Windows Vista and the Windows Vista Start button are trademarks or registered trademarks of Microsoft Corporation in the United States and/or other countries. \endtable */ /*! \page linguist-manager.html \title Qt Linguist Manual: Release Manager \contentspage {Qt Linguist Manual}{Contents} \previouspage Qt Linguist Manual \nextpage Qt Linguist Manual: Translators \keyword lupdate \keyword lrelease Two tools are provided for the release manager, \l lupdate and \l lrelease. These tools can process \l qmake project files, or operate directly on the file system. \section1 Qt Project Files The easiest method to use \l{#lupdate} {lupdate} and \l{#lrelease} {lrelease} is by specifing a \c .pro Qt project file. There must be an entry in the \c TRANSLATIONS section of the project file for each language that is additional to the native language. A typical entry looks like this: \snippet examples/linguist/arrowpad/arrowpad.pro 1 Using a locale within the translation file name is useful for determining which language to load at runtime. This is explained in the \l{linguist-programmers.html} {Programmers} chapter. An example of a complete \c .pro file with four translation source files: \snippet doc/src/snippets/code/doc_src_linguist-manual.qdoc 0 \snippet doc/src/snippets/code/doc_src_linguist-manual.qdoc 1 QTextCodec::setCodecForTr() makes it possible to choose a 8-bit encoding for literal strings that appear within \c tr() calls. This is useful for applications whose source language is, for example, Chinese or Japanese. If no encoding is set, \c tr() uses Latin1. If you do use the QTextCodec::codecForTr() mechanism in your application, \QL needs you to set the \c CODECFORTR entry in the \c .pro file as well. For example: \snippet doc/src/snippets/code/doc_src_linguist-manual.qdoc 1 Also, if your compiler uses a different encoding for its runtime system as for its source code and you want to use non-ASCII characters in string literals, you will need to set the \c CODECFORSRC. For example: \snippet doc/src/snippets/code/doc_src_linguist-manual.qdoc 2 Microsoft Visual Studio 2005 .NET appears to be the only compiler for which this is necessary. However, if you want to write portable code, we recommend that you avoid non-ASCII characters in your source files. You can still specify non-ASCII characters portably using escape sequences, for example: \snippet doc/src/snippets/code/doc_src_linguist-manual.qdoc 3 \target lupdate manual \section1 lupdate Usage: \c {lupdate myproject.pro} \l lupdate is a command line tool that finds the translatable strings in the specified source, header and \e {Qt Designer} interface files, and produces or updates \c .ts translation files. The files to process and the files to update can be set at the command line, or provided in a \c .pro file specified as an command line argument. The produced translation files are given to the translator who uses \QL to read the files and insert the translations. Companies that have their own translators in-house may find it useful to run \l lupdate regularly, perhaps monthly, as the application develops. This will lead to a fairly low volume of translation work spread evenly over the life of the project and will allow the translators to support a number of projects simultaneously. Companies that hire in translators as required may prefer to run \l lupdate only a few times in the application's life cycle, the first time might be just before the first test phase. This will provide the translator with a substantial single block of work and any bugs that the translator detects may easily be included with those found during the initial test phase. The second and any subsequent \l lupdate runs would probably take place during the final beta phase. The TS file format is a simple human-readable XML format that can be used with version control systems if required. \c lupdate can also process Localization Interchange File Format (XLIFF) format files; files in this format typically have file names that end with the \c .xlf suffix. Pass the \c -help option to \c lupdate to obtain the list of supported options: \snippet doc/src/snippets/code/doc_src_linguist-manual.qdoc 4 \QL is also able to import and export XLIFF files. See the \l{Qt Linguist Manual: Translators}{Translators} section for more information. \section1 lrelease Usage: \c {lrelease myproject.pro} \l lrelease is a command line tool that produces QM files out of TS files. The QM file format is a compact binary format that is used by the localized application. It provides extremely fast lookups for translations. The TS files \l lrelease processes can be specified at the command line, or given indirectly by a Qt \c .pro project file. This tool is run whenever a release of the application is to be made, from initial test version through to final release version. If the QM files are not created, e.g. because an alpha release is required before any translation has been undertaken, the application will run perfectly well using the text the programmers placed in the source files. Once the QM files are available the application will detect them and use them automatically. Note that lrelease will only incorporate translations that are marked as "finished". Otherwise the original text will be used instead. Pass the \c -help option to \c lrelease to obtain the list of supported options: \snippet doc/src/snippets/code/doc_src_linguist-manual.qdoc 5 \section1 Missing Translations Both \l lupdate and \l lrelease may be used with TS translation source files which are incomplete. Missing translations will be replaced with the native language phrases at runtime. */ /*! \page linguist-translators.html \title Qt Linguist Manual: Translators \contentspage {Qt Linguist Manual}{Contents} \previouspage Qt Linguist Manual: Release Manager \nextpage Qt Linguist Manual: Programmers Contents \tableofcontents \section1 The One Minute Guide to Using Qt Linguist \QL is a tool for adding translations to Qt applications. Run \QL from the taskbar menu, or by double clicking the desktop icon, or by entering the command \c {linguist} at the command line. Once \QL has started, choose \menu{File|Open} from the \l{menubar} {menu bar} and select a translation source (TS file) to load. If you do not have a TS file, see the \l {Qt Linguist Manual: Release Manager} {release manager manual} to learn how to generate one. The \QL main window is divided into several, dockable subwindows arranged around a central \l{The Translation Area} {translation area}. The \l{Context Window} {context list} is normally shown on the left, and the \l{Sources and Forms Window} {source code}, \l{Strings Window} {string list}, and either the \l{Phrases and Guesses Window} {prhrases and guesses}, or the \l{Warnings Window} {warnings} are shown above and below the \l{The Translation Area} {translations area}. With a translation file loaded, select a context from the \l{Context Window} {context list} on the left. Selecting a context loads the translatable strings found in that context into the \l{Strings Window} {string list}. Selecting one of the strings copies that string as the \key{Source text} in the \l{The Translation Area} {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 \key{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 \inlineimage linguist-check-on.png or \inlineimage linguist-check-warning.png . Then select the next context and continue. Translation options are shown in the \l{Phrases and Guesses Window} {phrases and guesses window}. If the phrases and guesses window is not visible, click the \key{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 (\menu{Phrases|Open Phrase Book...}). The current string's current translation is also shown here. To select a guess, double click it in the prases and guesses window or use the keyboard shortcut shown to the right of the guess. \QL can automatically check whether your translation strings pass a list of \l{Validation Tests} {validation tests}. Validation test failures are shown in the \l{Warnings Window} {warnings window}. If the warnings window is not visible, click the \key{Warnings} tab at the bottom of the main window. Finally, if the source code for the contexts is accessible, the \l{Sources and Forms Window} {source code window} shows the context where the current string is used. If the source code window is not visible, click the \key{Sources and Forms} tab at the bottom of the main window. At the end of the session choose \menu{File|Save} from the menu bar and then \menu{File|Exit} to quit. \section1 The Qt Linguist Window \image linguist-linguist.png "Linguist UI Snapshot" This \QL main window is divided into dockable subwindows arranged around a central \l{The Translation Area} {translation area}. The subwindows are: \l{Context Window} {Context}, \l{Sources and Forms Window} {Sources and Forms}, \l{Strings Window} {Strings}, \l{Phrases and Guesses Window} {Phrases and guesses}, and \l{Warnings Window} {Warnings} (hidden in the UI snapsot). The translation area is always visible, but the dockable subwindows can be activated or deactivated in the \menu{View|Views} menu, and dragged around by their title bars and dropped in the translation area or even outside the main window. \section2 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 \e{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 \e{}, which contains strings that aren't in a subclass of QObject. To the left of the \e{Context} column is a column labeled \inlineimage linguist-check-obsolete.png . This column uses the following list of icons to summarize the current translation state for each context: \list \o \inlineimage linguist-check-on.png All strings in the context have been translated, and all the translations passed the \l{Validation Tests} {validation tests}. \o \inlineimage linguist-check-warning.png All strings in the context have been translated or marked as translated, but at least one translation failed the \l{Validation Tests} {validation tests}. \o \inlineimage linguist-check-off.png At least one string in the context has not been translated or is not marked as translated. \o \inlineimage linguist-check-obsolete.png None of the translated strings still appears in the context. This usually means the context itself no longer exists in the application. \endlist To the right of the \e{Context} column is the \e{Items} column. Each entry in the \e{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 \bold{MessageEditor} context is selected. Its \e{Items} entry shows \bold{18/18}, which means it has 18 translatable strings and all 18 strings currently have translations. However, the context has been marked with the \inlineimage linguist-check-warning.png icon, which means that at least one of the current translations failed a \l{Validation Tests} {validation test}. In the \l{Strings Window} {strings window} to the right, we see that one of the strings is indeed marked with the \inlineimage linguist-check-warning.png 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, \QL 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 \key{F6}. \section2 Strings Window The strings window normally appears on the right in the main window, above the \l{The Translation Area} {translation area}. Its \e{Source text} column lists all the translatable strings found in the current context. Selecting a string makes that string the current string in the \l{The Translation Area} {translation area}. To the left of the \e{Source text} column is a column labeled \inlineimage linguist-check-obsolete.png . This column is similar to the one in the \l{Context Window} {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: \target String Translation States \table \header \o State \o Icon \o Description \row \o Accepted/Correct \o \inlineimage linguist-check-on.png \o The source string has a translation (possibly empty); the user has accepted the translation, and the translation passes all the \l{Validation Tests} {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 \e{Items} column of the \l{Context Window} {context list} by 1. The state is reset to \inlineimage linguist-check-off.png if the string has a translation, or to \inlineimage linguist-check-empty.png if the string's translation is empty. If \c{lupdate} changes the contents of a string, its acceptance state is automatically reset to \inlineimage linguist-check-off.png . \row \o Accepted/Warnings \o \inlineimage linguist-check-warning.png \o The user has accepted the translation, but the translation does not pass all the \l{Validation Tests} {validation tests}. The validation test failures are shown in the \l{Warnings Window} {warnings window}. Click the icon to revoke acceptance of the translation. The state is reset to \inlineimage linguist-danger.png , and the number of accepted translations in the \e{Items} column of the \l{Context Window} {context list} is decremented by 1. \row \o Not Accepted \o \inlineimage linguist-check-off.png \o The string has a non-empty translation that passes all the \l{Validation Tests} {validation tests}, but the user has not yet accepted the translation. Click the icon or press \key{Ctrl+Enter} to accept the translation. The state is reset to \inlineimage linguist-check-on.png , and the number of accepted translations in the \e{Items} column of the \l{Context Window} {context list} is incremented by 1. \row \o No Translation \o \inlineimage linguist-check-empty.png \o The string does not have a translation. Click the icon to accpet the empty translation anyway. The state is reset to \inlineimage linguist-check-on.png , and the number of accepted translations in the \e{Items} column of the \l{Context Window} {context list} is incremented by 1. \row \o Validation Failures \o \inlineimage linguist-danger.png \o The string has a translation, but the translation does not pass all the \l{Validation Tests} {validation tests}. Validation test failures are shown in the \l{Warnings Window} {warnings} window. Click on the icon or press \key{Ctrl+Return} to accept the translation even with validation failures. The state is reset to \inlineimage linguist-check-warning.png . We recommended editing the translation to fix the causes of the validation failures. The state will reset automatically to \inlineimage linguist-check-off.png , when all the failures have been fixed. \row \o Obsolete \o \inlineimage linguist-check-obsolete.png \o The string is obsolete. It is no longer used in the context. See the \l{Qt Linguist Manual: Release Manager} {Release Manager} for instructions on how to remove obsolete messages from the file. \endtable The string list is a dockable subwindow. If it has been closed, restored it by pressing \key{F7}. \section2 The Translation Area The translation area is in the middle of the main window, to the right of the \l{Context Window} {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 \l{Strings Window} {string list} appears at the top of the translation area, under the label \menu{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 \l{QObject::tr()} {disambiguating comment}, it will appear below the source text area, under the label \menu{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 \l{Translating Multiple Languages Simultaneously} {multiple languages} are being translated, this sequence of fields is repeated for each language. See aso \l {Changing the Target Locale}. \section2 Phrases and Guesses Window If the current string in the \l{Strings Window} {string list} appears in one or more of the \l{Phrase Books} {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 \e{Guess} hotkey on the right. You can also press \key{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 and then press \key{Enter} to copy it to the translation area. If you decide that you don't want to copy a phrase after all, press \key{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 \e{Phrases and guesses} tab at the bottom of the window, or by pressing \key{F10}. \section2 Sources and Forms Window If the source files containing the translatable strings are available to \QL, this window shows the source context of the current string in the \l{Strings Window} {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 \l{lupdate manual} {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 \e{Sources and Forms} tab at the bottom of the window, or by pressing \key{F9}. \section2 Warnings Window If the translation you enter for the current string fails any of the active \l{Validation Tests} {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 \e{active} validation tests are reported. To see which validation tests are currently active, or to activate or deactivate tests, use the \menu{Validation} menu from the \l{menubar}{menu bar}. The Warnings window is a dockable window. If it has been closed, it can be made visible by pressing the \e{Warnings} tab at the bottom of the window, or by pressing \key{F8}. \target multiple languages \section2 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 \e{Polish} and \e{Japanese} translation files loaded. \image linguist-linguist_2.png The first thing to notice is that the \l{The Translation Area} {translation area} has text editing areas for both Polish and Japanese, and these are color-coded for easier separation. Second, the \l{Context Window} and the \l{Strings Window} both have two clomuns labeled \inlineimage linguist-check-obsolete.png 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 \l{The Translation Area} {translation area}, and the right-most column applies to the bottom language area. The \e{Items} column in the \l{Context Window} combines the values for both languages. The best way to see this is to look at the value for the \bold{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 \e{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 \bold{MessageEditor} context are now \e{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 \inlineimage linguist-check-off.png 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 \e{18/18} in the \e{Items} column when all 18 strings have accepted translations for all the loaded translation files, e.g., both Polish and Japanese in the snapshot. \section1 Common Tasks \section2 Leaving a Translation for Later If you wish to leave a translation press \key{Ctrl+L} (Next Unfinished) to move to the next unfinished translation. To move to the next translation (whether finished or unfinished) press \key{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 \l{Strings Window} {string list}. \section2 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, \QL notes that the translation has been made and when the translator reaches a later occurrence of the same phrase \QL will provide the previous translation as a possible translation candidate in the \l{Phrases and Guesses Window}. If a phrase occurs more than once in a particular context it will only be shown once in \QL's \l{Context Window} {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 \l{Context Window} {context list}. The programmers comments will appear in the \l{The Translation Area} {translation area} on a light blue background. \section2 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. \section3 Alt Key Accellerators 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 \e{File} menu with the "F" in the word "File" underlined. In these applications the \e{File} menu can be invoked either by clicking the word "File" on the menu bar or by pressing \e{Alt+F}. To identify an accelerator key in the translation text ("File") precede it with an ampersand, e.g. \e{\&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. \section3 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 \e{File} menu have a \e{New} submenu item in the \e{File} menu. The \e{New} item might appear as "\underline{N}ew Ctrl+N" in the \e{File} menu, meaning the \e{New} menu can be invoked by simply pressing \key{Ctrl+N}, instead of either clicking \e{File} with the mouse and then clicking \e{New} with the mouse, or by entering \e{Alt+F} and \e{N}. Each Ctrl key accelerator is shown in the \l{Strings Window} {string list} as a separte string, e.g. \key{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 \l{QObject::tr()} {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 \e{Developer comments} in the \l{The Translation Area} {translation area} under the \e{Source text} area. Ideally Ctrl key accelerators are translated simply by copying them directly using \e {Copy from source text} in the \menu{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. \e{Qt} will automatically display the correct name at runtime. 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. \e{Qt} relies on these strings being there. For supported languages, \e {Qt} automatically translates these strings. \section2 Handling Numbered Arguments Some phrases contain numbered arguments. A numbered argument is a placeholder that will be replaced with text at runtime. A numbered argument appears in a source string as a percent sign followed by a digit. Consider an example: \c{After processing file %1, file %2 is next in line}. In this string to be translated, \c{%1} and \c{%2} are numbered arguments. At runtime, \c{%1} and \c{%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. \c{Datei %2 wird bearbeitet, wenn Datei %1 fertig ist}. Both numbered arguments appear in the translation, but in the reverse order. \c{%i} will always be replaced by the same text in the translation stringss, regardless of where argument \e{i} appears in the argument sequence in the source string. \section2 Reusing Translations If the translated text is similar to the source text, choose the \e {Copy from source text} entry in the \menu Translation menu (press \key{Ctrl+B}) which will copy the source text into the \l{The Translation Area} {translation area}. \QL automatically lists possible translations from any open \l{Phrase Books} {phrase books} in the \l{Phrases and Guesses Window}, as well as similar or identical phrases that have already been translated. \section2 Changing the Target Locale \QL displays the target language in the \l{The Translation Area} {translation area}, and adapts the number of input fields for plural forms accordingly. If not explicitly set, \QL guesses the target language and country by evaluating the translation source file name: E.g. \c app_de.ts sets the target language to German, and \c 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 \l{linguist-programmers.html}{Programmers Manual} for details). If your files do not follow this convention, you can also set the locale information explicitly using \e {Translation File Settings} in the \menu Edit menu. \image linguist-translationfilesettings.png \section1 Phrase Books A \QL 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, \QL will show the phrase book entry in the \l {Phrases and Guesses Window}. \section2 Creating and Editing Phrase Books \image linguist-phrasebookdialog.png Before a phrase book can be edited it must be created or, if it already exists, opened. Create a new phrase book by selecting \menu{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 \menu{Phrase|Open Phrase Book} from the menu bar. The phrase book contents can be displayed and changed by selecting \menu{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 \gui{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 \gui Close button (press Esc) once you've finished adding (and removing) phrases. \section2 Shortcuts for Editing Phrase Books You can also create a new phrase book entry directly out of the translation you are working on: Clicking \menu{Phrases|Add to Phrase Book} or pressing \key{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 \l{Phrases and Guesses Window}, you can also edit it in place by right clicking on the entry, and selecting \menu{Edit}. After fixing the error press \key{Return} to leave the editing mode. \section2 Batch Translation \image linguist-batchtranslation.png Use the batch translation feature of \QL to automatically translate source texts that are also in a phrase book. Selecting \menu{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 \l {String Translation States}). \section1 Validation Tests \QL provides four kinds of validation tests for translations. \list 1 \o \e {Accelerator validation} detects translated phrases that do not have an ampersand when the source phrase does and vice versa. \o \e {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. \o \e {Phrases validation} detects source phrases that are also in the phrase book but whose translation differs from that given in the phrase book. \o \e {Place marker validation} detects whether the same variables (like \c %1, \c %2) are used both in the source text and in the translation. \endlist 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, \QL will recheck all phrases and mark any that fail validation. See also \l{String Translation States}. \section1 Form Preview \image linguist-previewtool.png Forms created by \e{Qt Designer} are stored in special UI files. \QL 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 \menu{Tools|Open/Refresh Form Preview} to open the window shown above. The list of UI files \QL 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 \menu{File|Open Form...}. Double-click on an entry in the Forms List to display the Form File. Select \e{} from the toolbar to display the untranslated form. \section1 Qt Linguist Reference \section2 File Types \QL makes use of four kinds of files: \list \o TS \e {translation source files} \BR are human-readable XML files containing source phrases and their translations. These files are usually created and updated by \l lupdate and are specific to an application. \o \c .xlf \e {XLIFF files} \BR are human-readable XML files that adhere to the international XML Localization Interchange File Format. \QL can be used to edit XLIFF files generated by other programs. For standard Qt projects, however, only the TS file format is used. \o QM \e {Qt message files} \BR are binary files that contain translations used by an application at runtime. These files are generated by \l lrelease, but can also be generated by \QL. \o \c .qph \e {Qt phrase book files} \BR are human-readable XML files containing standard phrases and their translations. These files are created and updated by \QL and may be used by any number of projects and applications. \endlist \target menubar \section2 The Menu Bar \image linguist-menubar.png \list \o \gui {File} \list \o \gui {Open... Ctrl+O} \BR pops up an open file dialog from which a translation source \c .ts or \c .xlf file can be chosen. \o \gui {Recently opened files} \BR shows the TS files that have been opened recently, click one to open it. \o \gui {Save Ctrl+S} \BR saves the current translation source file. \o \gui {Save As...} \BR 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. \o \gui {Release} \BR create a Qt message QM file with the same base name as the current translation source file. The release manager's command line tool \l lrelease performs the same function on \e all of an application's translation source files. \o \gui {Release As...} \BR 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 \l lrelease performs the same function on \e all of an application's translation source files. \o \gui {Print... Ctrl+P} \BR pops up a print dialog. If you click OK the translation source and the translations will be printed. \o \gui {Exit Ctrl+Q} \BR closes \QL. \endlist \o \gui {Edit} \list \o \gui {Undo Ctrl+Z} \BR undoes the last editing action in the translation pane. \o \gui {Redo Ctrl+Y} \BR redoes the last editing action in the translation pane. \o \gui {Cut Ctrl+X} \BR deletes any highlighted text in the translation pane and saves a copy to the clipboard. \o \gui {Copy Ctrl+C} \BR copies the highlighted text in the translation pane to the clipboard. \o \gui {Paste Ctrl+V} \BR pastes the clipboard text into the translation pane. \omit \o \gui {Delete} \BR deletes the highlighted text in the translation pane. \endomit \o \gui {Select All Ctrl+A} \BR selects all the text in the translation pane ready for copying or deleting. \o \gui {Find... Ctrl+F} \BR pops up the Find dialog. When the dialog pops up enter the text to be found and click the \gui {Find Next} button. Source phrases, translations and comments may be searched. \o \gui {Find Next F3} \BR finds the next occurrence of the text that was last entered in the Find dialog. \o \gui {Search and Translate...} \BR pops up the Search and Replace Dialog. Use this dialog to translate the same text in multiple items. \o \gui {Translation File Settings...} \BR let you configure the target language and the country/region of a translation source file. \endlist \o \gui {Translation} \list \o \gui {Prev Unfinished Ctrl+K} \BR moves to the nearest previous unfinished source phrase (unfinished means untranslated or translated but failed validation). \o \gui {Next Unfinished Ctrl+L} \BR moves to the next unfinished source phrase. \o \gui {Prev Shift+Ctrl+K} \BR moves to the previous source phrase. \o \gui {Next Shift+Ctrl+L} \BR moves to the next source phrase. \o \gui {Done \& Next Ctrl+Enter} \BR mark this phrase as 'done' (translated) and move to the next unfinished source phrase. \o \gui {Copy from source text Ctrl+B} \BR copies the source text into the translation. \endlist \o \gui {Validation} (See \l{Validation Tests}) \list \o \gui {Accelerators} \BR toggles validation on or off for Alt accelerators. \o \gui {Ending Punctuation} \BR switches validation on or off for phrase ending punctuation, e.g. ellipsis, exclamation mark, question mark, etc. \o \gui {Phrase Matches} \BR sets validation on or off for matching against translations that are in the current phrase book. \o \gui {Place Marker Matches} \BR sets validation on or off for the use of the same place markers in the source and translation. \endlist \o \gui {Phrases} (See the section \l {Phrase Books} for details.) \list \o \gui {New Phrase Book... Ctrl+N} \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. \o \gui {Open Phrase Book... Ctrl+H} \BR pops up an open file dialog. Find and choose a phrase book to open. \o \gui {Close Phrase Book} \BR 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 \QL should save the changes. \o \gui {Edit Phrase Book...} \BR displays the list of phrase books currently opened. Clicking on one of the items will open the \l{Creating and Editing Phrase Books}{Phrase Book Dialog} where you can add, edit or delete phrases. \o \gui {Print Phrase Book...} \BR 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. \o \gui {Add to Phrase Book Ctrl+T} \BR Adds the source text and translation currently shown in the \l{The Translation Area} {translation area} to a phrase book. If multiple phrase books are loaded, a dialog box let you specify select one. \endlist \o \gui {Tools} \list \o \gui {Batch Translation...} \BR Opens a \l{Batch Translation}{dialog} which let you automatically insert translations for source texts which are in a phrase book. \o \gui {Open/Refresh Form Preview F3} \BR Opens the \l{Form Preview}. This window let you instantly see translations for forms created with \QD. \endlist \o \gui {View} \list \o \gui {Revert Sorting} \BR puts the items in the \l{Context Window} {context list} and in the \l{Strings Window} {string list} into their original order. \o \gui {Display Guesses} \BR turns the display of phrases and guesses on or off. \o \gui {Statistics} \BR toggles the visibility of the Statistics dialog. \o \gui {Views} \BR toggles the visibility of the \l{Context Window}, \l{Strings Window}, \l{Phrases and Guesses Window}, \l{Warnings Window}, or \l{Sources and Forms Window}. \o \gui {Toolbars} \BR toggles the visibility of the different toolbars. \endlist \o \gui {Help} \list \o \gui {Manual F1} \BR opens this manual. \o \gui {About Qt Linguist} \BR Shows information about \QL. \o \gui {About Qt} \BR Shows information about \e{Qt}. \o \gui {What's This? Shift+F1} \BR Click on one item in the main window to get additional information about it. \endlist \endlist \section2 The Toolbar \image linguist-toolbar.png \list \o \inlineimage linguist-fileopen.png \BR Pops up the open file dialog to open a new translation source TS file. \o \inlineimage linguist-filesave.png \BR Saves the current translation source TS file. \o \inlineimage linguist-fileprint.png \BR Prints the current translation source TS file. \o \inlineimage linguist-phrasebookopen.png \BR Pops up the file open dialog to open a new phrase book \c .qph file. \o \inlineimage linguist-editundo.png \BR Undoes the last editing action in the translation pane. \o \inlineimage linguist-editredo.png \BR Redoes the last editing action in the translation pane. \o \inlineimage linguist-editcut.png \BR Deletes any highlighted text in the translation pane and save a copy to the clipboard. \o \inlineimage linguist-editcopy.png \BR Copies the highlighted text in the translation pane to the clipboard. \o \inlineimage linguist-editpaste.png \BR Pastes the clipboard text into the translation pane. \o \inlineimage linguist-editfind.png \BR Pops up the Find dialog . \o \inlineimage linguist-prev.png \BR Moves to the previous source phrase. \o \inlineimage linguist-next.png \BR Moves to the next source phrase. \o \inlineimage linguist-prevunfinished.png \BR Moves to the previous unfinished source phrase. \o \inlineimage linguist-nextunfinished.png \BR Moves to the next unfinished source phrase. \o \inlineimage linguist-doneandnext.png \BR Marks the phrase as 'done' (translated) and move to the next unfinished source phrase. \o \inlineimage linguist-validateaccelerators.png \BR Toggles accelerator validation on and off. \o \inlineimage linguist-validatepunctuation.png \BR Toggles phrase ending punctuation validation on and off. \o \inlineimage linguist-validatephrases.png \BR Toggles phrase book validation on or off. \o \inlineimage linguist-validateplacemarkers.png \BR Toggles place marker validation on or off. \endlist */ /*! \page linguist-programmers.html \title Qt Linguist Manual: Programmers \contentspage {Qt Linguist Manual}{Contents} \previouspage Qt Linguist Manual: Translators \nextpage Qt Linguist Manual: TS File Format Support for multiple languages is extremely simple in Qt applications, and adds little overhead to the programmer's workload. Qt minimizes the performance cost of using translations by translating the phrases for each window as they are created. In most applications the main window is created just once. Dialogs are often created once and then shown and hidden as required. Once the initial translation has taken place there is no further runtime overhead for the translated windows. Only those windows that are created, destroyed and subsequently created will have a translation performance cost. Creating applications that can switch language at runtime is possible with Qt, but requires a certain amount of programmer intervention and will of course incur some runtime performance cost. \section1 Making the Application Translation-Aware Programmers should make their application look for and load the appropriate translation file and mark user-visible text and Ctrl keyboard accelerators as targets for translation. Each piece of text that requires translating requires context to help the translator identify where in the program the text occurs. In the case of multiple identical texts that require different translations, the translator also requires some information to disambiguate the source texts. Marking text for translation will automatically cause the class name to be used as basic context information. In some cases the programmer may be required to add additional information to help the translator. \section2 Creating Translation Files Translation files consist of all the user-visible text and Ctrl key accelerators in an application and translations of that text. Translation files are created as follows: \list 1 \o Run \l lupdate initially to generate the first set of TS translation source files with all the user-visible text but no translations. \o The TS files are given to the translator who adds translations using \QL. \QL takes care of any changed or deleted source text. \o Run \l lupdate to incorporate any new text added to the application. \l lupdate synchronizes the user-visible text from the application with the translations; it does not destroy any data. \o Steps 2 and 3 are repeated as often as necessary. \o When a release of the application is needed \l lrelease is run to read the TS files and produce the QM files used by the application at runtime. \endlist For \l lupdate to work successfully, it must know which translation files to produce. The files are simply listed in the application's \c .pro Qt project file, for example: \snippet examples/linguist/arrowpad/arrowpad.pro 1 If your sources contain genuine non-Latin1 strings, \l lupdate needs to be told about it in the \c .pro file by using, for example, the following line: \code CODECFORTR = UTF-8 \endcode See the \l lupdate and \l lrelease sections. \section2 Loading Translations \snippet examples/linguist/hellotr/main.cpp 1 \snippet examples/linguist/hellotr/main.cpp 3 This is how a simple \c main() function of a Qt application begins. \snippet examples/linguist/hellotr/main.cpp 1 \snippet examples/linguist/hellotr/main.cpp 4 For a translation-aware application a translator object is created, a translation is loaded and the translator object installed into the application. \snippet examples/linguist/arrowpad/main.cpp 0 \snippet examples/linguist/arrowpad/main.cpp 1 For non-Latin1 strings in the sources you will also need for example: \code QTextCodec::setCodecForTr(QTextCodec::codecForName("utf8")); \endcode In production applications a more flexible approach, for example, loading translations according to locale, might be more appropriate. If the TS files are all named according to a convention such as \e appname_locale, e.g. \c tt2_fr, \c tt2_de etc, then the code above will load the current locale's translation at runtime. If there is no translation file for the current locale the application will fall back to using the original source text. Note that if you need to programmatically add translations at runtime, you can reimplement QTranslator::translate(). \section2 Making the Application Translate User-Visible Strings User-visible strings are marked as translation targets by wrapping them in a \c tr() call, for example: \snippet doc/src/snippets/code/doc_src_linguist-manual.qdoc 6 would become \snippet doc/src/snippets/code/doc_src_linguist-manual.qdoc 7 All QObject subclasses that use the \c Q_OBJECT macro implement the \c tr() function. Although the \c tr() call is normally made directly since it is usually called as a member function of a QObject subclass, in other cases an explicit class name can be supplied, for example: \snippet doc/src/snippets/code/doc_src_linguist-manual.qdoc 8 or \snippet doc/src/snippets/code/doc_src_linguist-manual.qdoc 9 \section2 Distinguishing Identical Strings That Require Different Translations The \l lupdate program automatically provides a \e context for every source text. This context is the class name of the class that contains the \c tr() call. This is sufficient in the vast majority of cases. Sometimes however, the translator will need further information to uniquely identify a source text; for example, a dialog that contained two separate frames, each of which contained an "Enabled" option would need each identified because in some languages the translation would differ between the two. This is easily achieved using the two argument form of the \c tr() call, e.g. \snippet doc/src/snippets/code/doc_src_linguist-manual.qdoc 10 and \snippet doc/src/snippets/code/doc_src_linguist-manual.qdoc 11 Ctrl key accelerators are also translatable: \snippet examples/linguist/trollprint/mainwindow.cpp 2 It is strongly recommended that the two argument form of \c tr() is used for Ctrl key accelerators. The second argument is the only clue the translator has as to the function performed by the accelerator. \section2 Helping the Translator with Navigation Information In large complex applications it may be difficult for the translator to see where a particular source text comes from. This problem can be solved by adding a comment using the keyword \e TRANSLATOR which describes the navigation steps to reach the text in question; e.g. \snippet doc/src/snippets/code/doc_src_linguist-manual.qdoc 12 These comments are particularly useful for widget classes. \section2 Handling Plural Forms Qt includes a \c tr() overload that will make it very easy to write "plural-aware" internationalized applications. This overload has the following signature: \snippet doc/src/snippets/code/doc_src_linguist-manual.qdoc 17 Depending on the value of \c n, the \c tr() function will return a different translation, with the correct grammatical number for the target language. Also, any occurrence of \c %n is replaced with \c{n}'s value. For example: \snippet doc/src/snippets/code/doc_src_linguist-manual.qdoc 18 If a French translation is loaded, this will expand to "0 item remplac\unicode{233}", "1 item remplac\unicode{233}", "2 items remplac\unicode{233}s", etc., depending on \c{n}'s value. And if no translation is loaded, the orignal string is used, with \c %n replaced with count's value (e.g., "6 item(s) replaced"). To handle plural forms in the native language, you need to load a translation file for this language, too. \l lupdate has the \c -pluralonly command line option, which allows the creation of TS files containing only entries with plural forms. See the \l{http://qt.nokia.com/doc/qq/}{Qt Quarterly} Article \l{http://qt.nokia.com/doc/qq/qq19-plurals.html}{Plural Forms in Translations} for further details on this issue. \section2 Coping With C++ Namespaces C++ namespaces and the \c {using namespace} statement can confuse \l lupdate. It will interpret \c MyClass::tr() as meaning just that, not as \c MyNamespace::MyClass::tr(), even if \c MyClass is defined in the \c MyNamespace namespace. Runtime translation of these strings will fail because of that. You can work around this limitation by putting a \e TRANSLATOR comment at the beginning of the source files that use \c MyClass::tr(): \snippet doc/src/snippets/code/doc_src_linguist-manual.qdoc 13 After the comment, all references to \c MyClass::tr() will be understood as meaning \c MyNamespace::MyClass::tr(). \section2 Translating Text That is Outside of a QObject Subclass \section3 Using QCoreApplication::translate() If the quoted text is not in a member function of a QObject subclass, use either the tr() function of an appropriate class, or the QCoreApplication::translate() function directly: \snippet doc/src/snippets/code/doc_src_linguist-manual.qdoc 14 \section3 Using QT_TR_NOOP() and QT_TRANSLATE_NOOP() If you need to have translatable text completely outside a function, there are two macros to help: QT_TR_NOOP() and QT_TRANSLATE_NOOP(). These macros merely mark the text for extraction by \l{lupdate}. The macros expand to just the text (without the context). Example of QT_TR_NOOP(): \snippet doc/src/snippets/code/doc_src_linguist-manual.qdoc 15 Example of QT_TRANSLATE_NOOP(): \snippet doc/src/snippets/code/doc_src_linguist-manual.qdoc 16 \section1 Tutorials Three tutorials are presented: \list 1 \o \l{linguist/hellotr}{Hello tr()} demonstrates the creation of a \l QTranslator object. It also shows the simplest use of the \c tr() function to mark user-visible source text for translation. \o \l{linguist/arrowpad}{Arrow Pad} explains how to make the application load the translation file applicable to the current locale. It also shows the use of the two-argument form of \c tr() which provides additional information to the translator. \o \l{linguist/trollprint}{Troll Print} explains how identical source texts can be distinguished even when they occur in the same context. This tutorial also discusses how the translation tools help minimize the translator's work when an application is upgraded. \endlist These tutorials cover all that you need to know to prepare your Qt applications for translation. At the beginning of a project add the translation source files to be used to the project file and add calls to \l lupdate and \l lrelease to the makefile. During the project all the programmer must do is wrap any user-visible text in \c tr() calls. They should also use the two argument form for Ctrl key accelerators, or when asked by the translator for the cases where the same text translates into two different forms in the same context. The programmer should also include \c TRANSLATION comments to help the translator navigate the application. */ /*! \page linguist-ts-file-format.html \title Qt Linguist Manual: TS File Format \contentspage {Qt Linguist Manual}{Contents} \previouspage Qt Linguist Manual: Programmers The TS file format used by \QL is described by the \l{http://www.w3.org/TR/1998/REC-xml-19980210}{DTD} presented below, which we include for your convenience. Be aware that the format may change in future Qt releases. \quotefile tools/linguist/shared/ts.dtd */