diff options
| author | Timothy Pearson <kb9vqf@pearsoncomputing.net> | 2011-11-08 12:31:36 -0600 |
|---|---|---|
| committer | Timothy Pearson <kb9vqf@pearsoncomputing.net> | 2011-11-08 12:31:36 -0600 |
| commit | d796c9dd933ab96ec83b9a634feedd5d32e1ba3f (patch) | |
| tree | 6e3dcca4f77e20ec8966c666aac7c35bd4704053 /tools/linguist/book | |
| download | tqt3-d796c9dd933ab96ec83b9a634feedd5d32e1ba3f.tar.gz tqt3-d796c9dd933ab96ec83b9a634feedd5d32e1ba3f.zip | |
Test conversion to TQt3 from Qt3 8c6fc1f8e35fd264dd01c582ca5e7549b32ab731
Diffstat (limited to 'tools/linguist/book')
38 files changed, 1955 insertions, 0 deletions
diff --git a/tools/linguist/book/images/doneandnext.png b/tools/linguist/book/images/doneandnext.png Binary files differnew file mode 100644 index 000000000..47efaec76 --- /dev/null +++ b/tools/linguist/book/images/doneandnext.png diff --git a/tools/linguist/book/images/editcopy.png b/tools/linguist/book/images/editcopy.png Binary files differnew file mode 100644 index 000000000..efe8d03ee --- /dev/null +++ b/tools/linguist/book/images/editcopy.png diff --git a/tools/linguist/book/images/editcut.png b/tools/linguist/book/images/editcut.png Binary files differnew file mode 100644 index 000000000..146388a29 --- /dev/null +++ b/tools/linguist/book/images/editcut.png diff --git a/tools/linguist/book/images/editfind.png b/tools/linguist/book/images/editfind.png Binary files differnew file mode 100644 index 000000000..59c63bf97 --- /dev/null +++ b/tools/linguist/book/images/editfind.png diff --git a/tools/linguist/book/images/editpaste.png b/tools/linguist/book/images/editpaste.png Binary files differnew file mode 100644 index 000000000..13f9a0f41 --- /dev/null +++ b/tools/linguist/book/images/editpaste.png diff --git a/tools/linguist/book/images/editredo.png b/tools/linguist/book/images/editredo.png Binary files differnew file mode 100644 index 000000000..6a30e2648 --- /dev/null +++ b/tools/linguist/book/images/editredo.png diff --git a/tools/linguist/book/images/editundo.png b/tools/linguist/book/images/editundo.png Binary files differnew file mode 100644 index 000000000..38a735758 --- /dev/null +++ b/tools/linguist/book/images/editundo.png diff --git a/tools/linguist/book/images/fileopen.png b/tools/linguist/book/images/fileopen.png Binary files differnew file mode 100644 index 000000000..44107d36c --- /dev/null +++ b/tools/linguist/book/images/fileopen.png diff --git a/tools/linguist/book/images/fileprint.png b/tools/linguist/book/images/fileprint.png Binary files differnew file mode 100644 index 000000000..2936658f2 --- /dev/null +++ b/tools/linguist/book/images/fileprint.png diff --git a/tools/linguist/book/images/filesave.png b/tools/linguist/book/images/filesave.png Binary files differnew file mode 100644 index 000000000..03e10f917 --- /dev/null +++ b/tools/linguist/book/images/filesave.png diff --git a/tools/linguist/book/images/finddialog.png b/tools/linguist/book/images/finddialog.png Binary files differnew file mode 100644 index 000000000..c3b0f4332 --- /dev/null +++ b/tools/linguist/book/images/finddialog.png diff --git a/tools/linguist/book/images/linguist.png b/tools/linguist/book/images/linguist.png Binary files differnew file mode 100644 index 000000000..519c185ab --- /dev/null +++ b/tools/linguist/book/images/linguist.png diff --git a/tools/linguist/book/images/menubar.png b/tools/linguist/book/images/menubar.png Binary files differnew file mode 100644 index 000000000..7ba43c60d --- /dev/null +++ b/tools/linguist/book/images/menubar.png diff --git a/tools/linguist/book/images/next.png b/tools/linguist/book/images/next.png Binary files differnew file mode 100644 index 000000000..7434fa21d --- /dev/null +++ b/tools/linguist/book/images/next.png diff --git a/tools/linguist/book/images/nextunfinished.png b/tools/linguist/book/images/nextunfinished.png Binary files differnew file mode 100644 index 000000000..618fc947d --- /dev/null +++ b/tools/linguist/book/images/nextunfinished.png diff --git a/tools/linguist/book/images/phrasebookdialog.png b/tools/linguist/book/images/phrasebookdialog.png Binary files differnew file mode 100644 index 000000000..d1a323a5a --- /dev/null +++ b/tools/linguist/book/images/phrasebookdialog.png diff --git a/tools/linguist/book/images/phrasebookopen.png b/tools/linguist/book/images/phrasebookopen.png Binary files differnew file mode 100644 index 000000000..4f76b7d4c --- /dev/null +++ b/tools/linguist/book/images/phrasebookopen.png diff --git a/tools/linguist/book/images/prev.png b/tools/linguist/book/images/prev.png Binary files differnew file mode 100644 index 000000000..f9fbd935d --- /dev/null +++ b/tools/linguist/book/images/prev.png diff --git a/tools/linguist/book/images/prevunfinished.png b/tools/linguist/book/images/prevunfinished.png Binary files differnew file mode 100644 index 000000000..25cc1a266 --- /dev/null +++ b/tools/linguist/book/images/prevunfinished.png diff --git a/tools/linguist/book/images/toolbar.png b/tools/linguist/book/images/toolbar.png Binary files differnew file mode 100644 index 000000000..5e6021f05 --- /dev/null +++ b/tools/linguist/book/images/toolbar.png diff --git a/tools/linguist/book/images/tt1_en.png b/tools/linguist/book/images/tt1_en.png Binary files differnew file mode 100644 index 000000000..66e54e027 --- /dev/null +++ b/tools/linguist/book/images/tt1_en.png diff --git a/tools/linguist/book/images/tt1_la.png b/tools/linguist/book/images/tt1_la.png Binary files differnew file mode 100644 index 000000000..a70134908 --- /dev/null +++ b/tools/linguist/book/images/tt1_la.png diff --git a/tools/linguist/book/images/tt2_en.png b/tools/linguist/book/images/tt2_en.png Binary files differnew file mode 100644 index 000000000..c71e2010b --- /dev/null +++ b/tools/linguist/book/images/tt2_en.png diff --git a/tools/linguist/book/images/tt2_fr.png b/tools/linguist/book/images/tt2_fr.png Binary files differnew file mode 100644 index 000000000..acc25157e --- /dev/null +++ b/tools/linguist/book/images/tt2_fr.png diff --git a/tools/linguist/book/images/tt2_nl.png b/tools/linguist/book/images/tt2_nl.png Binary files differnew file mode 100644 index 000000000..4631de21f --- /dev/null +++ b/tools/linguist/book/images/tt2_nl.png diff --git a/tools/linguist/book/images/tt3_10_en.png b/tools/linguist/book/images/tt3_10_en.png Binary files differnew file mode 100644 index 000000000..e95bff9e1 --- /dev/null +++ b/tools/linguist/book/images/tt3_10_en.png diff --git a/tools/linguist/book/images/tt3_10_pt_bad.png b/tools/linguist/book/images/tt3_10_pt_bad.png Binary files differnew file mode 100644 index 000000000..05cb5f3cf --- /dev/null +++ b/tools/linguist/book/images/tt3_10_pt_bad.png diff --git a/tools/linguist/book/images/tt3_10_pt_good.png b/tools/linguist/book/images/tt3_10_pt_good.png Binary files differnew file mode 100644 index 000000000..b0f855f5a --- /dev/null +++ b/tools/linguist/book/images/tt3_10_pt_good.png diff --git a/tools/linguist/book/images/tt3_11_about_pt.png b/tools/linguist/book/images/tt3_11_about_pt.png Binary files differnew file mode 100644 index 000000000..446731445 --- /dev/null +++ b/tools/linguist/book/images/tt3_11_about_pt.png diff --git a/tools/linguist/book/images/tt3_11_en.png b/tools/linguist/book/images/tt3_11_en.png Binary files differnew file mode 100644 index 000000000..7d98b98cc --- /dev/null +++ b/tools/linguist/book/images/tt3_11_en.png diff --git a/tools/linguist/book/images/tt3_11_pt.png b/tools/linguist/book/images/tt3_11_pt.png Binary files differnew file mode 100644 index 000000000..02910cf0d --- /dev/null +++ b/tools/linguist/book/images/tt3_11_pt.png diff --git a/tools/linguist/book/images/validateaccelerators.png b/tools/linguist/book/images/validateaccelerators.png Binary files differnew file mode 100644 index 000000000..68201fec8 --- /dev/null +++ b/tools/linguist/book/images/validateaccelerators.png diff --git a/tools/linguist/book/images/validatephrases.png b/tools/linguist/book/images/validatephrases.png Binary files differnew file mode 100644 index 000000000..62fe5f281 --- /dev/null +++ b/tools/linguist/book/images/validatephrases.png diff --git a/tools/linguist/book/images/validatepunctuation.png b/tools/linguist/book/images/validatepunctuation.png Binary files differnew file mode 100644 index 000000000..8ce2648d9 --- /dev/null +++ b/tools/linguist/book/images/validatepunctuation.png diff --git a/tools/linguist/book/linguist-manager.leaf b/tools/linguist/book/linguist-manager.leaf new file mode 100644 index 000000000..9380c4709 --- /dev/null +++ b/tools/linguist/book/linguist-manager.leaf @@ -0,0 +1,138 @@ +\chapter Release Manager + +\index Release Manager + +Two tools are provided for the release manager, \l lupdate and \l +lrelease. These tools depend on \e qmake project files. You don't +have to use \e qmake, though. + +A third tool, \c qm2ts, can be used for converting Qt 2.x message +files to \c .ts files. + +\section1 Qt Project Files + +\index .pro Files +\index Project Files +\index qmake!Project Files + +\l lupdate and \l lrelease depend on information in the application's +\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: + +\index TRANSLATIONS!in Project Files + +\quotefile tt2/tt2.pro +\skipto TRANSLATIONS +\printline tt2_fr +\printline tt2_nl + +Using a locale within the translation file name is useful for +determining which language to load at runtime. This is explained in +\link Programmers Chapter 4: Programmers \endlink. + +\index HEADERS!in Project Files +\index SOURCES!in Project Files +\index FORMS!in Project Files +\index TRANSLATIONS!in Project Files + +An example of a complete \c .pro file with four translation source files: +\code + HEADERS = main-dlg.h \ + options-dlg.h + SOURCES = main-dlg.cpp \ + options-dlg.cpp \ + main.cpp + FORMS = search-dlg.ui + TRANSLATIONS = superapp_dk.ts \ + superapp_fi.ts \ + superapp_no.ts \ + superapp_se.ts +\endcode + +\index QApplication!defaultCodec() +\index defaultCodec()!QApplication +\index DEFAULTCODEC!in Project Files +\index Chinese Language +\index Japanese Language + +\l 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 Latin-1. + +If you do use the \l QTextCodec::codecForTr() mechanism in your +application, \e {Qt Linguist} needs you to set the \c DEFAULTCODEC +entry in the \c .pro file as well. For example: +\code + DEFAULTCODEC = ISO-8859-5 +\endcode + +\section1 lupdate + +\index lupdate + +Usage: \c {lupdate myproject.pro} + + \index Qt Designer + +This is a simple command line tool. \l lupdate reads a Qt \c .pro +project file, finds the translatable strings in the specified source, +header and \e {Qt Designer} interface files, and produces or updates +the \c .ts translation files listed in the project file. The +translation files are given to the translator who uses \e {Qt +Linguist} 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 retquired 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. + +\index .ts Files +\index Translation Source Files +\index XML + +The \c .ts file format is a simple human-readable XML format that can +be used with version control systems if retquired. + +\section1 lrelease + +\index lrelease + +Usage: \c {lrelease myproject.pro} + +\index .qm Files +\index Qt Message Files + +This is another simple command line tool. It reads a Qt \c .pro +project file and produces the \c .qm files used by the application, +one for each \c .ts translation source file listed in the project +file. The \c .qm file format is a compact binary format that provides +extremely fast lookups for translations. + +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 \c +.qm files are not created, e.g. because an alpha release is retquired +before any translation has been undertaken, the application will run +perfectly well using the text the programmers placed in the source +files. Once the \c .qm files are available the application will +detect them and use them automatically. + +Note that \l lrelease will only incorporate translations that are +marked as "done". If a translation is missing, or has failed +validation, the original text will be used instead. + +\section1 Missing Translations + +Both \l lupdate and \l lrelease may be used with \c .ts translation +source files which are incomplete. Missing translations will be replaced +with the native language phrases at runtime. diff --git a/tools/linguist/book/linguist-manual.book b/tools/linguist/book/linguist-manual.book new file mode 100644 index 000000000..04dec8713 --- /dev/null +++ b/tools/linguist/book/linguist-manual.book @@ -0,0 +1,90 @@ +\title Guide to the Qt Translation Tools +\granularity chapter + +\chapter Introduction + +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. + +\link Release... Chapter 2: Release Manager \endlink 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. + +\link Translators Chapter 3: Translators \endlink is for translators. +It describes the use of the \e {Qt Linguist} tool. No computer +knowledge beyond the ability to start a program and use a text editor +or word processor is retquired. + +\link Programmers Chapter 4: Programmers \endlink 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 retquire 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 \e {Qt +Linguist}, 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 retquired. \e {Qt Linguist} 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 +\i A single phrase may need to be translated into several different +forms depending on context, e.g. \e open in English might become \e +\OEFFNEN, "open file", or \e aufbauen, "open internet connection", in +German. +\i 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. +\i 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. + +\RULE + +Please send comments and suggestions regarding this tutorial to the +\link mailto:doc@trolltech.com?subject=Translation_Tutorial Qt doc +team \endlink. Bugs in the tools should be sent to \link +mailto:qt-bugs@trolltech.com?subject=Translation_Tutorial +qt-bugs\endlink. + +\input linguist-manager.leaf +\input linguist-translator.leaf +\input linguist-programmer.leaf diff --git a/tools/linguist/book/linguist-programmer.leaf b/tools/linguist/book/linguist-programmer.leaf new file mode 100644 index 000000000..d74fdf1fe --- /dev/null +++ b/tools/linguist/book/linguist-programmer.leaf @@ -0,0 +1,1145 @@ +\chapter Programmers + +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 retquired. 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 retquires 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 retquires translating retquires context to help +the translator identify where in the program the text occurs. In the +case of multiple identical texts that retquire different translations, +the translator also retquires 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 retquired to add additional information to help +the translator. + +\section2 Creating Translation Files + +\index .ts Files +\index Translation Source 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: + +\index lupdate +\index lrelease + +\list 1 +\i Run \l lupdate initially to generate the first set of \c .ts +translation source files with all the user-visible text but no +translations. +\i The \c .ts files are given to the translator who adds translations +using \e {Qt Linguist}. \e {Qt Linguist} takes care of any changed +or deleted source text. +\i 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. +\i Steps 2 and 3 are repeated as often as necessary. +\i When a release of the application is needed \l lrelease is run to +read the \c .ts files and produce the \c .qm files used by the +application at runtime. +\endlist + +\index .pro Files +\index Project Files +\index qmake!Project Files + +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: +\quotefile tt2/tt2.pro +\skipto TRANSLATIONS +\printline TRANSLATIONS +\printline + +See the \link lupdate "lupdate" \endlink and \link lrelease +"lrelease" \endlink sections. + +\section2 Loading Translations + +\quotefile tt1/main.cpp +\skipto main( +\printline main( +\printuntil QApplication + +\index main() + +This is how a simple \c main() function of a Qt application begins. + +\index QTranslator!load() +\index load()!QTranslator +\index QApplication!installTranslator() +\index installTranslator()!QApplication + +\quotefile tt1/main.cpp +\skipto main( +\printline main( +\printuntil app.installTrans + +For a translation-aware application a translator object is created, a +translation is loaded and the translator object installed into the +application. + +\quotefile tt2/main.cpp +\skipto main( +\printline main( +\printuntil app.installTrans + +In production applications a more flexible approach, for example, +loading translations according to locale, might be more appropriate. If +the \c .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. + +\section2 Making the Application Translate User-Visible Strings + +\index tr() +\index QObject!tr() + +User-visible strings are marked as translation targets by wrapping them +in a \c tr() call, for example: +\code + button = new QPushButton( "&Quit", this ); +\endcode + +would become + +\code + button = new QPushButton( tr("&Quit"), this); +\endcode + +\index Q_OBJECT + +All \l 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 \l QObject subclass, in +other cases an explicit class name can be supplied, for example: + +\code + QPushButton::tr("&Quit") +\endcode + +or + +\code + QObject::tr("&Quit") +\endcode + +\section2 Distinguishing Identical Strings That Retquire Different +Translations + +\index Translation Contexts +\index Contexts!for Translation +\index lupdate + +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. + +\code + rbc = new QRadioButton( tr("Enabled", "Color frame"), this ); +\endcode + +and + +\code + rbh = new QRadioButton( tr("Enabled", "Hue frame"), this ); +\endcode + +\index Ctrl Key + +Ctrl key accelerators are also translatable: + +\quotefile tt3/mainwindow.cpp +\skipto tquit() +\printline tquit() +\printuntil Quit + +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 + +\index TRANSLATOR!in Comments +\index Translator Comments +\index Comments!for Translators + +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. + +\code + /* TRANSLATOR FindDialog + + Choose Edit|Find from the menu bar or press Ctrl+F to pop up the + Find dialog. + */ +\endcode + +These comments are particularly useful for widget classes. + +\section2 Coping With C++ Namespaces + +\index Namespaces +\index C++!Namespaces +\index lupdate + +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. + +\index TRANSLATOR!in Comments +\index Translator Comments +\index Comments!for Translators + +You can work around this limitation by putting a \e TRANSLATOR +comment at the beginning of the source files that use \c +MyClass::tr(): +\code + /* TRANSLATOR MyNamespace::MyClass */ +\endcode +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 QApplication::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 +QApplication::translate() function directly: + +\code + void some_global_function( LoginWidget *logwid ) + { + QLabel *label = new QLabel( + LoginWidget::tr("Password:"), logwid ); + } + + void same_global_function( LoginWidget *logwid ) + { + QLabel *label = new QLabel( + qApp->translate("LoginWidget", "Password:"), + logwid ); + } +\endcode + +\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(): +\code + QString FriendlyConversation::greeting( int greet_type ) + { + static const char* greeting_strings[] = { + QT_TR_NOOP( "Hello" ), + QT_TR_NOOP( "Goodbye" ) + }; + return tr( greeting_strings[greet_type] ); + } +\endcode + +Example of QT_TRANSLATE_NOOP(): +\code + static const char* greeting_strings[] = { + QT_TRANSLATE_NOOP( "FriendlyConversation", "Hello" ), + QT_TRANSLATE_NOOP( "FriendlyConversation", "Goodbye" ) + }; + + QString FriendlyConversation::greeting( int greet_type ) + { + return tr( greeting_strings[greet_type] ); + } + + QString global_greeting( int greet_type ) + { + return qApp->translate( "FriendlyConversation", + greeting_strings[greet_type] ); + } +\endcode + +\section1 Tutorials + +Three tutorials are presented. The first 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. The +second tutorial 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. The third tutorial 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. + +\section2 Tutorial 1: Loading and Using Translations + +\img tt1_en.png +\caption Tutorial 1 Screenshot, English version + +\include tt1/tt1.pro +\caption \c tt1.pro + +\include tt1/main.cpp +\caption \c main.cpp + +This example is a reworking of the \link tutorial1-01.html +"hello-world" \endlink example from \link tutorial.html Tutorial +#1\endlink, with a Latin translation. The \e {Tutorial 1 Screenshot, +English version}, above, shows the English version. + +\quotefile tt1/main.cpp + +\section3 Line by Line Walk-through + +\quotefile tt1/main.cpp + +\skipto qtranslator +\printline qtranslator + +\index QTranslator + +This line includes the definition of the \l QTranslator class. +Objects of this class provide translations for user-visible text. + +\skipto QTranslator +\printuntil tor + +Creates a \l QTranslator object without a parent. + +\printline load + +\index tt1_la.qm + +Tries to load a file called \c tt1_la.qm (the \c .qm file extension is +implicit) that contains Latin translations for the source texts used in +the program. No error will occur if the file is not found. + +\index QApplication!installTranslator() +\index installTranslator()!QApplication + +\printline installTranslator + +Adds the translations from \c tt1_la.qm to the pool of translations used +by the program. + +\index Hello World + +\printline hello + +Creates a push button that displays "Hello world!". If \c tt1_la.qm +was found and contains a translation for "Hello world!", the +translation appears; if not, the source text appears. + +\index tr() +\index QObject!tr() + +All classes that inherit \l QObject have a \c tr() function. Inside +a member function of a \l QObject class, we simply write \c tr("Hello +world!") instead of \c QPushButton::tr("Hello world!") or \c +QObject::tr("Hello world!"). + +\section3 Running the Application in English + +\index English Language + +Since we haven't made the translation file \c tt1_la.qm, the source text +is shown when we run the application: + +\img tt1_en.png +\caption Tutorial 1 Screenshot, English version + +\section3 Creating a Latin Message File + +\index tt1.pro +\index Latin + +The first step is to create a project file, \c tt1.pro, that lists +all the source files for the project. The project file can be a qmake +project file, or even an ordinary makefile. Any file that contains + +\index SOURCES!in Project Files +\index TRANSLATIONS!in Project Files + +\quotefile tt1/tt1.pro +\skipto SOURCES +\printline SOURCES +\skipto TRANSLATIONS +\printline TRANSLATIONS + +will work. \e TRANSLATIONS specifies the message files we want to +maintain. In this example, we just maintain one set of translations, +namely Latin. + +\index .ts Files +\index Translation Source Files +\index .qm Files +\index Qt Message Files + +Note that the file extension is \c .ts, not \c .qm. The \c .ts +translation source format is designed for use during the +application's development. Programmers or release managers run the \l +lupdate program to generate and update \c .ts files with the source +text that is extracted from the source code. Translators read and +update the \c .ts files using \e {Qt Linguist} adding and editing +their translations. + +\index XML + +The \c .ts format is human-readable XML that can be emailed directly +and is easy to put under version control. If you edit this file +manually, be aware that the default encoding for XML is UTF-8, not +Latin-1 (ISO 8859-1). One way to type in a Latin-1 character such as +'\OSLASH' (Norwegian o with slash) is to use an XML entity: +"\ø". This will work for any Unicode character. + +Once the translations are complete the \l lrelease program is used to +convert the \c .ts files into the \c .qm Qt message file format. The +\c .qm format is a compact binary format designed to deliver very +fast lookup performance. Both \l lupdate and \l lrelease read all the +project's source and header files (as specified in the HEADERS and +SOURCES lines of the project file) and extract the strings that +appear in \c tr() function calls. + +\index lupdate + +\l lupdate is used to create and update the message files (\c tt1_la.ts +in this case) to keep them in sync with the source code. It is safe to +run \l lupdate at any time, as \l lupdate does not remove any +information. For example, you can put it in the makefile, so the \c .ts +files are updated whenever the source changes. + +\index .ts Files +\index Translation Source Files +\index XML + +Try running \l lupdate right now, like this: +\code + lupdate -verbose tt1.pro +\endcode +(The \c -verbose option instructs \c lupdate to display messages that +explain what it is doing.) You should now have a file \c tt1_la.ts in +the current directory, containing this: +\code + <!DOCTYPE TS><TS> + <context> + <name>QPushButton</name> + <message> + <source>Hello world!</source> + <translation type="unfinished"></translation> + </message> + </context> + </TS> +\endcode +You don't need to understand the file format since it is read and +updated using tools (\l lupdate, \e {Qt Linguist}, \l lrelease). + +\section3 Translating to Latin with Qt Linguist + +\index Qt Linguist +\index Linguist + +We will use \e {Qt Linguist} to provide the translation, although +you can use any XML or plain text editor to enter a translation into a +\c .ts file. + +To start \e {Qt Linguist}, type +\code + linguist tt1_la.ts +\endcode + +You should now see the text "QPushButton" in the top left pane. +Double-click it, then click on "Hello world!" and enter "Orbis, te +saluto!" in the \e Translation pane (the middle right of the +window). Don't forget the exclamation mark! + +Click the \e Done checkbox and choose \e File|Save from the +menu bar. The \c .ts file will no longer contain +\code + <translation type='unfinished'></translation> +\endcode +but instead will have +\code + <translation>Orbis, te saluto!</translation> +\endcode + +\section3 Running the Application in Latin + +\index Latin +\index lrelease + +To see the application running in Latin, we have to generate a \c .qm +file from the \c .ts file. Generating a \c .qm file can be achieved +either from within \e {Qt Linguist} (for a single \c .ts file), or +by using the command line program \l lrelease which will produce one \c +.qm file for each of the \c .ts files listed in the project file. +Generate \c tt1_la.qm from \c tt1_la.ts by choosing +\e File|Release from \e {Qt Linguist}'s menu bar and pressing +\e Save in the file save dialog that pops up. Now run the \e tt1 example +program again. This time the button will be labelled "Orbis, te +saluto!". + +\img tt1_la.png +\caption Tutorial 1 Screenshot, Latin version + +\section2 Tutorial 2: Using Two or More Languages + +\img tt2_en.png +\caption Tutorial 2 Screenshot, English version + +\index .pro Files +\index Project Files +\index qmake!Project Files + +\include tt2/tt2.pro +\caption tt2.pro + +\index Translation Contexts +\index Contexts!for Translation + +This example is a slightly more involved and introduces a key +\e {Qt Linguist} concept: "contexts". + +\list +\i \c arrowpad.h contains the definition of \c ArrowPad, a custom widget; +\i \c arrowpad.cpp contains the implementation of \c ArrowPad; +\i \c mainwindow.h contains the definition of \c MainWindow, a subclass of + \l QMainWindow +\i \c mainwindow.cpp contains the implementation of \c MainWindow; +\i \c main.cpp contains main(). +\endlist + +\index tt2.pro +\index French Language +\index Dutch Language + +We will use two translations, French and Dutch, although there is no +effective limit on the number of possible translations that can be used +with an application. The relevant lines of \c tt2.pro are + +\quotefile tt2/tt2.pro +\skipto HEADERS +\printuntil tt2_nl.ts + +\index lupdate +\index tt2_fr.ts +\index tt2_nl.ts + +Run \l lupdate; it should produce two identical message files +\c tt2_fr.ts and \c tt2_nl.ts. These files will contain all the source +texts marked for translation with \c tr() calls and their contexts. + +\section3 Line by Line Walk-through + +\index ArrowPad!in Translation Tutorial +\index English Language + +In \c arrowpad.h we define the \c ArrowPad subclass which is a +subclass of \l QWidget. In the \e {Tutorial 2 Screenshot, English +version}, above, the central widget with the four buttons is an +\c ArrowPad. + +\quotefile tt2/arrowpad.h +\skipto class ArrowPad +\printline class ArrowPad + +\index Q_OBJECT +\index tr() +\index QObject!tr() +\index Translation Contexts +\index Contexts!for Translation + +When \l lupdate is run it not only extracts the source texts but it +also groups them into contexts. A context is the name of the class in +which the source text appears. Thus, in this example, "ArrowPad" is a +context: it is the context of the texts in the \c ArrowPad class. +The \c Q_OBJECT macro defines \c tr(x) in \c ArrowPad like this + +\index QApplication!translate() +\index translate()!QApplication + +\code + qApp->translate( "ArrowPad", x ) +\endcode + +Knowing which class each source text appears in enables \e {Qt +Linguist} to group texts that are logically related together, e.g. +all the text in a dialog will have the context of the dialog's class +name and will be shown together. This provides useful information for +the translator since the context in which text appears may influence how +it should be translated. For some translations keyboard +accelerators may need to be changed and having all the source texts in a +particular context (class) grouped together makes it easier for the +translator to perform any accelerator changes without introducing +conflicts. + +In \c arrowpad.cpp we implement the \c ArrowPad class. + +\quotefile tt2/arrowpad.cpp +\skipto QPushButton +\printline QPushButton + +We call \c ArrowPad::tr() for each button's label since the labels are +user-visible text. + +\img tt2_en.png +\caption Tutorial 2 Screenshot, English version + +\index Q_OBJECT +\index MainWindow!in Translation Tutorial + +\quotefile tt2/mainwindow.h +\skipto QMainWindow +\printline QMainWindow +\printuntil Q_OBJECT + +In the \e {Tutorial 2 Screenshot, English version}, above, the whole +window is a \c MainWindow. This is defined in the \c mainwindow.h +header file. Here too, we use \c Q_OBJECT, so that \c MainWindow will +become a context in \e {Qt Linguist}. + +In the implementation of \c MainWindow, \c mainwindow.cpp, we create +an instance of our \c ArrowPad class + +\quotefile tt2/mainwindow.cpp +\skipto arrow pad +\printline arrow pad + +We also call \c MainWindow::tr() twice, once for the menu item and +once for the accelerator. + +\index Ctrl Key +\index Alt Key + +\skipto tquit() +\printline tquit() +\printuntil Ctrl+Q + +Note the use of \c tr() to support different keys in other languages. +"Ctrl+Q" is a good choice for Quit in English, but a Dutch translator +might want to use "Ctrl+A" (for Afsluiten) and a German translator +"Strg+E" (for Beenden). When using \c tr() for Ctrl key accelerators, +the two argument form should be used with the second argument +describing the function that the accelerator performs. + +\index main() + +Our \c main() function is defined in \c main.cpp as usual. + +\quotefile tt2/main.cpp +\skipto QTranslator +\printline QTranslator +\printuntil install + +\index QTextCodec!locale() +\index locale()!QTextCodec +\index LANG!Environment Variable +\index Environment Variables!LANG + +We choose which translation to use according to the current locale. +\l QTextCodec::locale() can be influenced by setting the \c LANG +environment variable, for example. Notice that the use of a naming +convention that incorporates the locale for \c .qm message files, +(and \c .ts files), makes it easy to implement choosing the +translation file according to locale. + +If there is no \c .qm message file for the locale chosen the original +source text will be used and no error raised. + +\section3 Translating to French and Dutch + +We'll begin by translating the example application into French. Start +\e {Qt Linguist} with \c tt2_fr.ts. You should get the seven source +texts ("\&Up", "\&Left", etc.) grouped in two contexts ("ArrowPad" +and "MainWindow"). + +Now, enter the following translations: + +\list +\i \c ArrowPad + \list + \i \&Up - \&Haut + \i \&Left - \&Gauche + \i \&Right - \&Droite + \i \&Down - \&Bas + \endlist +\i \c MainWindow + \list + \i E\&xit - \&Quitter + \i Ctrl+Q - Ctrl+Q + \i \&File - \&Fichier + \endlist +\endlist + +It's tquickest to press \Key Alt+D (which clicks the \e {Done \& Next} +button) after typing each translation, since this marks the +translation as done and moves on to the next source text. + +Save the file and do the same for Dutch working with \c tt2_nl.ts: + +\list +\i \c ArrowPad + \list + \i \&Up - \&Boven + \i \&Left - \&Links + \i \&Right - \&Rechts + \i \&Down - \&Onder + \endlist +\i \c MainWindow + \list + \i E\&xit - \&Afsluiten + \i Ctrl+Q - Ctrl+A + \i File - \&Bestand + \endlist +\endlist + +We have to convert the \c tt1_fr.ts and \c tt1_nl.ts translation source +files into \c .qm files. We could use \e {Qt Linguist} as we've done +before; however using the command line tool \l lrelease ensures that +\e all the \c .qm files for the application are created without us +having to remember to load and \e File|Release each one +individually from \e {Qt Linguist}. + +In practice we would include calls to \l lupdate and \l lrelease in the +application's makefile to ensure that the latest translations are +used. + +\omit +an example of a makefile or .pro file that did this would be nice +\endomit + +Type + +\code + lrelease tt2.pro +\endcode + +\index LANG!Environment Variable +\index export!Unix Command +\index setenv!Unix Command + +This should create both \c tt2_fr.qm and \c tt2_nl.qm. Set the \c +LANG environment variable to \c fr. In Unix, one of the two following +commands should work + +\code + export LANG=fr + setenv LANG fr +\endcode + +\index + +\index autoexec.bat +\index set!Windows Command + +In Windows, either modify \c autoexec.bat or run + +\code + set LANG=fr +\endcode + +When you run the program, you should now see the French version: + +\img tt2_fr.png +\caption Tutorial 2 Screenshot, French version + +Try the same with Dutch, by setting \c LANG=nl. Now the Dutch +version should appear: + +\img tt2_nl.png +\caption Tutorial 2 Screenshot, Dutch version + +\section3 Exercises + +Mark one of the translations in \e {Qt Linguist} as not done, i.e. +by unchecking the "done" checkbox; run \l lupdate, then \l lrelease, +then the example. What effect did this change have? + +\index Canada +\index French Canada + +Set \c LANG=fr_CA (French Canada) and run the example program again. +Explain why the result is the same as with \c LANG=fr. + +Change one of the accelerators in the Dutch translation to eliminate the +conflict between \e \&Bestand and \e \&Boven. + + +\section2 Tutorial 3: Disambiguating Identical Strings + +\img tt3_10_en.png +\caption Tutorial 3 Screenshot, "Troll Print 1.0", English version + +\include tt3/tt3.pro +\caption \c tt3.pro + +\index Portuguese Language +\index Brazilian Language + +We've included a translation file, \c tt3_pt.ts, which contains some +Portuguese translations for this example. + +\index Troll Print + +We will consider two releases of the same application: Troll Print +1.0 and 1.1. We will learn to reuse the translations created for one +release in a subsequent release. (In this tutorial, you need to edit +some source files. It's probably best to copy all the files to a new +temporary directory and work from there.) + +Troll Print is a toy example application that lets the user choose +printer settings. It comes in two versions: English and Portuguese. + +Version 1.0 consists of these files: + +\index tt3.pro +\index tt3_pt.ts + +\list +\i \c printpanel.h contains the definition of PrintPanel; +\i \c printpanel.cpp contains the implementation of PrintPanel; +\i \c mainwindow.h contains the definition of \c MainWindow; +\i \c mainwindow.cpp contains the implementation of \c MainWindow; +\i \c main.cpp contains main(); +\i \c tt3.pro is the \e qmake project file. +\i \c tt3_pt.ts is the Portuguese message file. +\endlist + +\section3 Line by Line Walk-through + +The PrintPanel is defined in \c printpanel.h. + +\quotefile tt3/printpanel.h +\skipto QVBox +\printline QVBox +\printuntil Q_OBJECT + +\index Q_OBJECT + +\index PrintPanel!in Translation Tutorial + +PrintPanel is a \l QWidget. It needs the \c Q_OBJECT macro for \c +tr() to work properly. + +The implementation file is \c printpanel.cpp. + +\quotefile tt3/printpanel.cpp +\skipto setSpacing +\skipto / +\printline / +\printline +\printline +\printline + +\index Troll Print + +Some of the code is commented out in Troll Print 1.0; you will uncomment +it later, for Troll Print 1.1. + +\quotefile tt3/printpanel.cpp +\skipto twoSided +\printline twoSided +\printuntil toggle +\printline +\printuntil toggle + +Notice the two occurrences of \c tr("Enabled") and of \c +tr("Disabled") in PrintPanel. Since both "Enabled"s and "Disabled"s +appear in the same context \e {Qt Linguist} will only display one +occurrence of each and will use the same translations for the +duplicates that it doesn't display. Whilst this is a useful +timesaver, in some languages, such as Portuguese, the second +occurrence retquires a separate translation. We will see how \e {Qt +Linguist} can be made to display all the occurrences for separate +translation shortly. + +\index MainWindow!in Translation Tutorial + +The header file for \c MainWindow, \c mainwindow.h, contains no +surprises. In the implementation, \c mainwindow.cpp, we have some +user-visible source texts that must be marked for translation. + +\quotefile tt3/mainwindow.cpp +\skipto setCaption +\printline setCaption + +We must translate the window's caption. + +\skipto tquit +\printline tquit +\printuntil Help + +We also need to translate the menu items. Note that the two argument +form of \c tr() is used for the keyboard accelerator, "Ctrl+Q", since +the second argument is the only clue the translator has to indicate +what function that accelerator will perform. + +\quotefile tt3/main.cpp +\skipto QTranslator +\printuntil installTranslator + +\index main() + +The \c main() function in \c main.cpp is the same as the one in \link +{Tutorial 2...} Tutorial 2 \endlink. In particular it chooses a +translation file based on the current locale. + +\section3 Running Troll Print 1.0 in English and in Portuguese + +We will use the translations in the \c tt3_pt.ts file that is provided. + +Set the \c LANG environment variable to \c pt, and then run \c tt3. +You should still see the English version, as shown in the \e +{Tutorial 3 Screenshot, "Troll Print 1.0", English version}, above. +Now run \l lrelease, e.g. \c {lrelease tt3.pro}, and then run the +example again. Now you should see the Portuguese edition (Troll +Imprimir 1.0): + +\img tt3_10_pt_bad.png +\caption Tutorial 3 Screenshot, "Troll Imprimir 1.0", (Bad) Portuguese version + +Whilst the translation has appeared correctly, it is in fact wrong. In +good Portuguese, the second occurrence of "Enabled" should be +"Ativadas", not "Ativado" and the ending for the second translation of +"Disabled" must change similarly too. + +If you open \c tt3_pt.ts using \e {Qt Linguist}, you will see that +there is just one occurrence of "Enabled" and of "Disabled" in the +translation source file, even though there are two of each in the +source code. This is because \e {Qt Linguist} tries to minimize the +translator's work by using the same translation for duplicate source +texts. In cases such as this where an identical translation is wrong, +the programmer must disambiguate the duplicate occurrences. This is +easily achieved by using the two argument form of \c tr(). + +We can easily determine which file must be changed because the +translator's "context" is in fact the class name for the class where +the texts that must be changed appears. In this case the file is \c +printpanel.cpp, where the there are four lines to change. Add the +second argument "two-sided" in the appropriate \c tr() calls to the +first pair of radio buttons: + +\code + but = new QRadioButton( tr("Enabled", "two-sided"), twoSided ); + but = new QRadioButton( tr("Disabled", "two-sided"), twoSided ); +\endcode + +and add the second argument "colors" in the appropriate \c tr() calls +for the second pair of radio buttons: + +\code + but = new QRadioButton( tr("Enabled", "colors"), colors ); + but = new QRadioButton( tr("Disabled", "colors"), colors ); +\endcode + +\index lupdate +\index tt3_pt.ts + +Now run \l lupdate and open \c tt3_pt.ts with \e {Qt Linguist}. You +should now see two changes. + +First, the translation source file now contains \e three "Enabled", +"Disabled" pairs. The first pair is marked "(obs.)" signifying that they +are obsolete. This is because these texts appeared in \c tr() calls that +have been replaced by new calls with two arguments. The second pair has +"two-sided" as their comment, and the third pair has "colors" as their +comment. The comments are shown in the \e {Source text and comments} +area in \e {Qt Linguist}. + +Second, the translation text "Ativado" and "Desativado" have been +automatically used as translations for the new "Enabled" and "Disabled" +texts, again to minimize the translator's work. Of course in this case +these are not correct for the second occurrence of each word, but they +provide a good starting point. + +Change the second "Ativado" into "Ativadas" and the second +"Desativado" into "Desativadas", then save and tquit. Run \l lrelease +to obtain an up-to-date binary \c tt3_pt.qm file, and run Troll Print +(or rather Troll Imprimir). + +\img tt3_10_pt_good.png +\caption Tutorial 3 Screenshot, "Troll Imprimir 1.0", (Good) Portuguese version + +\index Translator Comments +\index Comments!for Translators + +The second argument to \c tr() calls, called "comments" in \e {Qt +Linguist}, distinguish between identical source texts that occur in +the same context (class). They are also useful in other cases to give +clues to the translator, and in the case of Ctrl key accelerators are +the only means of conveying the function performed by the accelerator to +the translator. + +\index TRANSLATOR!in Comments +\index Translator Comments +\index Comments!for Translators + +An additional way of helping the translator is to provide information on +how to navigate to the particular part of the application that contains +the source texts they must translate. This helps them see the context +in which the translation appears and also helps them to find and test +the translations. This can be achieved by using a \e TRANSLATOR comment +in the source code: +\code + /* TRANSLATOR MainWindow + + In this application the whole application is a MainWindow. + Choose Help|About from the menu bar to see some text + belonging to MainWindow. + */ +\endcode + +Try adding these comments to some source files, particularly to +dialog classes, describing the navigation necessary to reach the +dialogs. You could also add them to the example files, e.g. \c +mainwindow.cpp and \c printpanel.cpp are appropriate files. Run \l +lupdate and then start \e {Qt Linguist} and load in \c tt3_pt.ts. +You should see the comments in the \e {Source text and comments} area +as you browse through the list of source texts. + +Sometimes, particularly with large programs, it can be difficult for +the translator to find their translations and check that they're +correct. Comments that provide good navigation information can save +them time: + +\code + /* TRANSLATOR ZClientErrorDialog + + Choose Client|Edit to reach the Client Edit dialog, then choose + Client Specification from the drop down list at the top and pick + client Bartel Leendert van der Waerden. Now check the Profile + checkbox and then click the Start Processing button. You should + now see a pop up window with the text "Error: Name too long!". + This window is a ZClientErrorDialog. + */ +\endcode + + +\section3 Troll Print 1.1 + +We'll now prepare release 1.1 of Troll Print. Start your favorite text +editor and follow these steps: + +\list +\i Uncomment the two lines that create a \l QLabel with the text + "\<b\>TROLL PRINT\</b\>" in \c printpanel.cpp. +\i Word-tidying: Replace "2-sided" by "Two-sided" in \c printpanel.cpp. +\i Replace "1.0" with "1.1" everywhere it occurs in \c mainwindow.cpp. +\i Update the copyright year to 1999-2000 in \c mainwindow.cpp. +\endlist + +(Of course the version number and copyright year would be consts or +#defines in a real application.) + +Once finished, run \l lupdate, then open \c tt3_pt.ts in \e {Qt +Linguist}. The following items are of special interest: + +\list +\i \c MainWindow + \list + \i Troll Print 1.0 - marked "(obs.)", obsolete + \i About Troll Print 1.0 - marked "(obs.)", obsolete + \i Troll Print 1.0. Copyright 1999 Macroshaft, Inc. - + marked "(obs.)", obsolete + \i Troll Print 1.1 - automatically translated as + "Troll Imprimir 1.1" + \i About Troll Print 1.1 - automatically translated as + "Troll Imprimir 1.1" + \i Troll Print 1.1. Copyright 1999-2000 Macroshaft, + Inc. - automatically translated as "Troll Imprimir 1.1. + Copyright 1999-2000 Macroshaft, Inc." + \endlist +\i \c PrintPanel + \list + \i 2-sided - marked "(obs.)", obsolete + \i \<b\>TROLL PRINT\</b\> - unmarked, i.e. untranslated + \i Two-sided - unmarked, i.e. untranslated. + \endlist +\endlist + +Notice that \l lupdate works hard behind the scenes to make revisions +easier, and it's pretty smart with numbers. + +Go over the translations in \c MainWindow and mark these as "done". +Translate "\<b\>TROLL PRINT\</b\>" as "\<b\>TROLL IMPRIMIR\</b\>". +When you're translating "Two-sided", press the \e {Guess Again} +button to translate "Two-sided", but change the "2" into "Dois". + +Save and tquit, then run \l lrelease. The Portuguese version +should look like this: + +\img tt3_11_pt.png +\caption Tutorial 3 Screenshot, "Troll Imprimir 1.1", Portuguese version + +Choose \e{Ajuda|Sobre}, (\e{Help|About}), to see the about box + +\img tt3_11_about_pt.png +\caption Tutorial 3 Screenshot, About box, Portuguese version + +\index English Language +\index Translating Qt +\index Qt!Translating Qt + +If you choose \e {Ajuda|Sobre Qt}, (\e {Help|About Qt}), you'll get +an English dialog. Oops! Qt itself needs to be translated. See the +document \link i18n.html#qt-itself Internationalization with Qt +\endlink for details. + +Now set \c LANG=en to get the original English version: + +\img tt3_11_en.png +\caption Tutorial 3 Screenshot, "Troll Print 1.1", English version + +\section2 Summary + +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 make file. + +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 \e TRANSLATION comments to +help the translator navigate the application. diff --git a/tools/linguist/book/linguist-translator.leaf b/tools/linguist/book/linguist-translator.leaf new file mode 100644 index 000000000..e20d7921a --- /dev/null +++ b/tools/linguist/book/linguist-translator.leaf @@ -0,0 +1,582 @@ +\chapter Translators + +\img linguist.png +\caption Linguist Main Window + +\section1 The One Minute Guide to Using Qt Linguist + +\index Linguist +\index Qt Linguist +\index Contexts!for Translation + +\e {Qt Linguist} is a tool for adding translations to Qt +applications. It introduces the concept of a translation "context" +which means a group of phrases that appear together on the screen +e.g. in the same menu or dialog. + +To start, run \e {Qt Linguist}, either from the taskbar menu, or by +double clicking the desktop icon, or type \c {linguist} (followed by +\Key Enter) at the command line. Once \e {Qt Linguist} has started +choose \Menu File|Open from the menu bar and select a \c .ts +translation source file to work on. + +\e {Qt Linguist}'s main window is divided into four main areas. The +left hand side contains the Context list, the top right is the Source +text area, the middle right is the translation area and the bottom +right is the phrases and guesses area. We'll describe them in detail +later. + +Click on one of the contexts in the context list (left hand side) and +then click on one of the phrases that appears in the Source text area +(top right). The phrase will be copied into the translation area +(middle right). Click under the word 'Translation' and type in the +translation. Click \Key Ctrl+Enter (Done \& Next) to confirm that you +have completed the translation and to move on to the next phrase that +retquires translation. + +The cycle of entering a translation then pressing \Key Ctrl+Enter can +be repeated until all the translations are done or until you finish +the session. Linguist will attempt to fill the "phrases and guesses" +area with possible translations from any open phrase books and any +previous translations. Each has a keyboard shortcut, e.g. +\Key Ctrl+1, \Key Ctrl+2, etc., which you can use to copy the +guess into the Translation area. (Mouse users can double click a +phrase or guess to move it into the Translation area.) At the end of +the session choose \Menu File|Save from the menu bar and then +\Menu File|Exit to tquit. + +\section1 Qt Linguist's Main Window + +\section2 Context List + +\index Contexts!for Translation + +This appears at the left hand side of the main window by default. The +first column, 'Done', identifies whether or not the translations for the +context have been done. A tick indicates that all the translations have +been done and are valid. A question mark indicates that one or more +translations have not been done or have failed validation. The second +column, 'Context' is the name of the context in which the translation +phrases appear. The third column, 'Items' shows two numbers, the first +is the number of translations that have been done, and the second is the +number of phrases that are in the context; if the numbers are equal then +all the translations have been done. Note that a greyed out tick +indicates an obsolete translation, i.e. a phrase that was translated in +a previous version of the application but which does not occur in the +new version. + +The contexts are ordered alphabetically. The phrases within each context +are in the order in which they appear in the source program and this may +not be the order in which they are shown on screen. + +The Context List is a dockable window so it can be dragged to another +position in the main window, or dragged out of the main window to be a +window in its own right. If you move the Context List, \e {Qt +Linguist} will remember its position and restore it whenever you +start the program. + +\section2 Source Text Area + +This appears at the top right of the main window by default. The first +column, 'Done', signifies the status of the translation. A tick +indicates that the phrase has been translated and passed validation. A +question mark indicates that the translation has not been done. An +exclamation mark indicates that the translation has failed validation. +The second column 'Source text' shows the text that must be translated. +The third column shows the translation. + +\e{Qt Linguist} provides three kinds of validation: accelerator, +punctuation and phrase. If the source text contains an accelerator +i.e. an ampersand, '\&' and the translated text does not contain an +ampersand the translation will fail the accelerator validation. +Similarly, if the source text ends with a particular punctuation +mark, e.g. '?', '!' or '.' and the translation ends with a different +punctuation mark the translation will fail the punctuation +validation. If the source text has a translation in one of the open +phrase books that differs from the translation used the translation +will fail phrase validation. (See \l Validation.) + +The Source Text Area is a dockable window. + +\section2 Translation Area + +This area appears at the middle right of the main window by default. It +is comprised of three vertical sections. The first section is labelled +'Source text' below which the source text appears. The second section +contains contextual information on a light blue background that the +programmer has added to assist the translator. If no contextual +information has been given this section does not appear. The third +section is labelled 'Translation' and this is where you enter the +translation of the source text. + +\section2 Phrases and Guesses Area + +\index Phrases!in Qt Linguist +\index Guesses!in Qt Linguist + +This area appears at the bottom right of the main window by default. +When you move to a new phrase if the phrase is in one of the phrase +books that has been loaded the phrase will appear in this area with its +translation. If the phrase is the same or similar to another phrase that +has already been translated the phrase and translation will be shown in +this area. To copy a translation from the phrases and guesses area press +\Key F6 to move to the phrases and guesses area, use the up and down arrow +keys to move to the phrase you want to use and press Enter to copy it. +If you decide that you don't want to copy a phrase after all, press Esc. +In both cases the focus will return to the Translation area. +Alternatively, double click the translation you want to use and it will +be copied into the translation area. + +The Phrases and Guesses Area is a dockable window. + +\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. An unfinished translation is +one that either has not been translated at all or one which fails +validation. To move to the next phrase press \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 Source Text area. + +\section2 Phrases That Retquire Multiple Translations Depending on Context + +\index Contexts!for Translation +\index Comments!for Translators + +The same phrase may occur in two or more contexts without conflict. Once +a phrase has been translated in one context, \e {Qt Linguist} notes +that the translation has been made and when the translator reaches a +later occurrence of the same phrase \e {Qt Linguist} will provide +the previous translation as a possible translation candidate in the +phrases and guesses area. If the +previous translation is acceptable just click the \e {Done \& Next} +button (press \Key Ctrl+Enter) to move on to the next unfinished phrase. + +If a phrase occurs more than once in a particular context it will only +be shown once in \e {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. + +\section2 Changing Keyboard Accelerators + +\index Accelerators +\index Keyboard Accelerators + +A keyboard accelerator is a key combination that when pressed will +cause an application to perform an action. Keyboard accelerators +normally come in two forms: Alt key and Ctrl key accelerators. + +\index Alt Key + +Alt key accelerators are used for menus and buttons. The underlining +signifies that pressing the Alt key with the underlined letter is the +same as clicking the menu item with the mouse. For example, most +applications have a \e File menu with the "F" in the word "file" +underlined. In these applications the file menu can be invoked either by +clicking the word "File" on the menu bar or by pressing Alt+F. The +accelerator key which is underlined is signified by preceeding it with +an ampersand, e.g. \e \&File. If a source phrase appears with an +ampersand in it then the translation should also contain an ampersand, +preferably in front of the same letter. The meaning of Alt key +accelerators can be determined from the phrase in which the ampersand is +embedded. The translator may need to change the letter used with the Alt +key, e.g. if the translated phrase does not contain the original +accelerator letter. Conflicts with other keys, i.e. having two Alt key +accelerators using the same letter in the same context, must be avoided. +Note that some Alt key accelerators, usually those on the menu bar, may +apply in other contexts. + +\index Ctrl Key + +Ctrl key accelerators can exist independently of any visual control. +They are often used to invoke actions in menus that would otherwise +take several keystrokes or mouse clicks. They may also be used to +perform actions that do not appear in any menu or on any button. For +example, most applications that have a \e File menu have a submenu +item called \e New. In many applications this will appear as "\NEW +Ctrl+N". This menu option could be invoked by clicking \e File then +clicking \e New with the mouse. Or you could press Alt+F then press N +since these letters are underlined. But the same thing can be achieved +simply by pressing \Key Ctrl+N. Accelerators that use the Ctrl key are +shown literally in the source text, e.g. \Key Ctrl+Enter. Ctrl key +accelerators have no phrase so the translator \index Comments!for +Translators must rely on the programmer to add a "comment" which +appears in the top right hand pane. This comment should explain what +action the Ctrl key accelerator performs. Ideally Ctrl key +accelerators are translated simply by copying them by chossing the \e +{Begin from Source} entry in the \Menu Translations menu. However in +some cases the letter will not make sense in the target language and +must be changed. Whatever letter (or digit) is chosen, the translation +should always be in the form "Ctrl+" followed by the letter or digit +in upper case. As with Alt key accelerators, if the translator changes +the key it must not conflict with any other Ctrl key accelerator. + +Later versions of \e {Qt Linguist} are expected to help the +translator avoid accelerator conflicts. + +\section2 Dealing with Phrases that Contain Variables + +Some phrases contain variables. Variables are placeholders for items of +text that are filled in at runtime. They are signified in the source +text with a percent sign followed by a digit, e.g. \e {After processing +file %1, file %2 is next in line}. In this example, \c %1 will be +replaced at runtime with the name of the first file to be processed and +\c %2 with the name of the next file to be processed. In the translated +version the variables must still appear. For example a German +translation might reverse the phrases, e.g. \e {Datei %2 wird +bearbeitet, wenn. Datei %1 fertig ist}. Note that both variables +are still used but their order has changed. The order in which variables +appear does not matter; \c %1 will always be replaced by the same text +at runtime no matter where it appears in the source text or translation +and similarly \c %2, etc. + +\section2 Reusing Translations + +If the translated text is similar to the source text, choose the \e +{Begin from Source} entry in the \Menu Translations menu (press \Key +Ctrl+B) which will copy the source text into the translation area. + +\e {Qt Linguist} automatically lists phrases from the open phrase +books and similar or identical phrases that have already been translated +in the Phrases and guesses area. + +\section1 Creating and Using Phrase Books + +\index Phrases!in Qt Linguist +\index Phrase Books + +\img phrasebookdialog.png +\caption Phrase Book Dialog + +A \e {Qt Linguist} phrase book is a set of source phrases, target +(translated) phrases, and optional definitions. Phrase Books are created +independently of any application, although typically one phrase book +will be created per application or family of applications. + +If the translator reaches an untranslated phrase that is the same as a +source phrase in the phrase book, \e {Qt Linguist} will show the +phrase book entry in the \e {Relevant phrases} panel at the bottom +right of the main window. Phrases which have translations that conflict +with those given in the phrase book are marked with a question mark in +the source text pane. Phrase Books are used to provide a common set of +translations to help ensure consistency. They can also be used to avoid +duplication of effort since the translations for a family of +applications can be produced once in the phrase book and the phrase book +used for the majority of translations in each application. + +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. + +To add a new phrase click the \Button {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 \e Save button (press Alt+S) and then click the \e Close +button (press Esc) once you've finished adding (and removing) phrases. + +When a phrase or set of phrases appears in the phrase book double +clicking the retquired target phrase will copy it to the translation +pane at the text cursor position. If you want to \e replace the text +in the translation pane with the target phrase, click the translation +pane, choose \Menu {Edit|Select All} (press \Key Alt+A) and then +double click the target phrase. + +\section1 Validation + +\index Validation of Translations +\index Accelerators!Validation +\index Punctuation!Validation +\index Phrases!Validation + +\e {Qt Linguist} provides three kinds of validation on translated +phrases. + +\list 1 +\i \e {Accelerator validation} detects translated phrases +that do not have an ampersand when the source phrase does and vice +versa. +\i \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. +\i \e {Phrases validation} detects source phrases that are +also in the phrase book but whose translation differs from that given in +the phrase book. +\endlist + +Validation may be switched on or off from the menu bar's Validation item +or using the toolbar buttons. Phrases that fail validation are marked +with a question mark in the source text pane. If you switch validation +off and then switch it on later, \e{Qt Linguist} will recheck all +phrases and mark any that fail validation. + +If any phrase in a context is invalid then the context itself will be +marked with a question mark; if all the phrases in a context are done +and are valid the context will be marked with a tick. + +Note that only phrases which are marked as done (with a tick) will +appear in the application. Invalid phrases and phrases which are +translated but not marked as done are kept in the translation source +file but are not used by the application. + +\section1 Qt Linguist Reference + +\section2 File Types + +\e {Qt Linguist} makes use of three kinds of file: + +\index .ts Files +\index Translation Source Files +\index .qm Files +\index Qt Message Files +\index .qph Files +\index Qt Phrase Book Files + +\list +\i \c .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. +\i \c .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 \e {Qt +Linguist}. +\i \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 \e {Qt Linguist} and may be used by any +number of projects and applications. +\endlist + +\section2 The Menu Bar + +\img menubar.png +\caption Menu Bar + +\list +\i \e {File} + \list + \i \e {Open... Ctrl+O} \BR pops up an open file dialog from which a + translation source \c .ts file can be chosen. + \i \e {Save Ctrl+S} \BR saves the current translation source \c .ts file. + \i \e {Save As...} \BR pops up a save as file dialog so that the + current translation source \c .ts file may be saved with a different + name and/or put in a different location. + \i \e {Release...} \BR pops up a save as file dialog. The + filename entered will be a Qt message \c .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. + \i \e {Print... Ctrl+P} \BR pops up a print dialog. If you click + OK the translation source and the translations will be printed. + \i \e {Recently opened files} \BR shows the \c .ts files that + have been opened recently, click one to open it. + \i \e {Exit Ctrl+Q} \BR closes \e {Qt Linguist}. + \endlist + +\i \e {Edit} + \list + \i \e {Undo Ctrl+Z} \BR undoes the last editing action in the + translation pane. + \i \e {Redo Ctrl+Y} \BR redoes the last editing action in the + translation pane. + \i \e {Cut Ctrl+X} \BR deletes any highlighted text in the + translation pane and saves a copy to the clipboard. + \i \e {Copy Ctrl+C} \BR copies the highlighted text in the + translation pane to the clipboard. + \i \e {Paste Ctrl+V} \BR pastes the clipboard text into the + translation pane. +\omit + \i \e {Delete} \BR deletes the highlighted text in the + translation pane. +\endomit + \i \e {Select All Ctrl+A} \BR selects all the text in the + translation pane ready for copying or deleting. + \i \e {Find... Ctrl+F} \BR pops up the + \link {The Find Dialog} Find dialog \endlink. When the dialog pops up + enter the text to be found and click the \e {Find Next} button. + Source phrases, translations and comments may be searched. + \i \e {Find Next F3} \BR finds the next occurrence of the text that + was last entered in the Find dialog. + \endlist + +\i \e {Translation} + \list + \i \e {Prev Unfinished Ctrl+K} \BR moves to the nearest previous + unfinished source phrase (unfinished means untranslated or + translated but failed validation). + \i \e {Next Unfinished Ctrl+L} \BR moves to the next unfinished source + phrase. + \i \e {Prev Shift+Ctrl+K} \BR moves to the previous source phrase. + \i \e {Next Shift+Ctrl+L} \BR moves to the next source phrase. + \i \e {Done \& NextCtrl+Enter} \BR mark this phrase as 'done' + (translated) and move to the next unfinished source phrase. + \i \e {Begin from Source Ctrl+B} \BR copies the source text into + the translation. + \endlist + +\i \e {Validation} (See the \l Validation section) + \list + \i \e {Accelerators} \BR toggles validation on or off for Alt + accelerators. + \i \e {Ending Punctuation} \BR switches validation on or off + for phrase ending punctuation, e.g. ellipsis, exclamation mark, + question mark, etc. + \i \e {Phrase Matches} \BR sets validation on or off for + matching against translations that are in the current phrase book. + \endlist + +\i \e {Phrase} (See the section \l {Creating ... Phrase +Books} for details.) + \list + \i \e {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. + \i \e {Open Phrase Book... Ctrl+H} \BR pops up an open file dialog. + Find and choose a phrase book to open. + \i \e {Close Phrase Book} \BR closes the current phrase book. + This will stop any further phrase validation taking place. + The same effect can be achieved by switching off phrase validation + using the Validation menu or the phrase toolbar button. + \i \e {Edit Phrase Book...} \BR pops up the + \link {The Phrase Dialog} phrase book dialog \endlink where you can + add, edit or delete phrases. + \i \e {Print Phrase Book...} \BR pops up a print dialog. If + you click OK the phrase book will be printed. + \endlist + +\i \e {View} + \list + \i \e {Revert Sorting} \BR puts the phrases in the source text + pane into their original order. + \i \e {Display Guesses} \BR turns the display of phrases and + guesses on or off. + \i \e {Statistics} \BR toggles the visibility of the Statistics dialog. + \i \e {Views} \BR toggles the visibility of the Context, Source text and + Phrase views. + \i \e {Toolbars} \BR toggles the visibility of the different toolbars. +\omit + \i \e {Large Icons} \BR switches between large or standard + size icons on the toolbar. + \i \e {Text Labels} \BR toggles the use of text labels on the + toolbar icons. +\endomit + \endlist + +\endlist + +\section2 The Toolbar + +\img toolbar.png +\caption Toolbar + +\list +\i \img fileopen.png +\BR +Pops up the open file dialog to open a new translation source \c .ts +file. + +\i \img filesave.png +\BR +Saves the current translation source \c .ts file. + +\i \img fileprint.png +\BR +Prints the current translation source \c .ts file. + +\i \img phrasebookopen.png +\BR +Pops up the file open dialog to open a new phrase book \c .qph file. + +\i \img editundo.png +\BR +Undoes the last editing action in the translation pane. + +\i \img editredo.png +\BR +Redoes the last editing action in the translation pane. + +\i \img editcut.png +\BR +Deletes any highlighted text in the translation pane and save a copy to +the clipboard. + +\i \img editcopy.png +\BR +Copies the highlighted text in the translation pane to the clipboard. + +\i \img editpaste.png +\BR +Pastes the clipboard text into the translation pane. + +\i \img editfind.png +\BR +Pops up the \link {The Find Dialog} Find dialog \endlink. + +\i \img prev.png +\BR +Moves to the previous source phrase. + +\i \img next.png +\BR +Moves to the next source phrase. + +\i \img prevunfinished.png +\BR +Moves to the previous unfinished source phrase. + +\i \img nextunfinished.png +\BR +Moves to the next unfinished source phrase. + +\i \img doneandnext.png +\BR +Marks the phrase as 'done' (translated) and move to the next +unfinished source phrase. + +\i \img validateaccelerators.png +\BR +Toggles accelerator validation on and off. + +\i \img validatepunctuation.png +\BR +Toggles phrase ending punctuation validation on and off. + +\i \img validatephrases.png +\BR +Toggles phrase book validation on or off. +\endlist + +\section2 The Find Dialog + +\img finddialog.png +\caption The Find Dialog + +Choose \Menu Edit|Find from the menu bar or press \Key Ctrl+F to pop +up the Find dialog. Press \Key F3 to repeat the last search. By +default the source phrases, translations and comments will all be +searched and the search will be case-insensitive. These settings can +be changed by checking or unchecking the checkboxes to reflect your +preferences. + +\section2 The Phrase Dialog + +This dialog is explained in the \l {Creating and Using Phrase Books} +section. |
