summaryrefslogtreecommitdiffstats
path: root/tools/linguist/book
diff options
context:
space:
mode:
authorTimothy Pearson <kb9vqf@pearsoncomputing.net>2011-11-08 12:31:36 -0600
committerTimothy Pearson <kb9vqf@pearsoncomputing.net>2011-11-08 12:31:36 -0600
commitd796c9dd933ab96ec83b9a634feedd5d32e1ba3f (patch)
tree6e3dcca4f77e20ec8966c666aac7c35bd4704053 /tools/linguist/book
downloadtqt3-d796c9dd933ab96ec83b9a634feedd5d32e1ba3f.tar.gz
tqt3-d796c9dd933ab96ec83b9a634feedd5d32e1ba3f.zip
Test conversion to TQt3 from Qt3 8c6fc1f8e35fd264dd01c582ca5e7549b32ab731
Diffstat (limited to 'tools/linguist/book')
-rw-r--r--tools/linguist/book/images/doneandnext.pngbin0 -> 445 bytes
-rw-r--r--tools/linguist/book/images/editcopy.pngbin0 -> 587 bytes
-rw-r--r--tools/linguist/book/images/editcut.pngbin0 -> 480 bytes
-rw-r--r--tools/linguist/book/images/editfind.pngbin0 -> 776 bytes
-rw-r--r--tools/linguist/book/images/editpaste.pngbin0 -> 664 bytes
-rw-r--r--tools/linguist/book/images/editredo.pngbin0 -> 362 bytes
-rw-r--r--tools/linguist/book/images/editundo.pngbin0 -> 353 bytes
-rw-r--r--tools/linguist/book/images/fileopen.pngbin0 -> 523 bytes
-rw-r--r--tools/linguist/book/images/fileprint.pngbin0 -> 767 bytes
-rw-r--r--tools/linguist/book/images/filesave.pngbin0 -> 510 bytes
-rw-r--r--tools/linguist/book/images/finddialog.pngbin0 -> 3165 bytes
-rw-r--r--tools/linguist/book/images/linguist.pngbin0 -> 22819 bytes
-rw-r--r--tools/linguist/book/images/menubar.pngbin0 -> 511 bytes
-rw-r--r--tools/linguist/book/images/next.pngbin0 -> 418 bytes
-rw-r--r--tools/linguist/book/images/nextunfinished.pngbin0 -> 456 bytes
-rw-r--r--tools/linguist/book/images/phrasebookdialog.pngbin0 -> 4857 bytes
-rw-r--r--tools/linguist/book/images/phrasebookopen.pngbin0 -> 883 bytes
-rw-r--r--tools/linguist/book/images/prev.pngbin0 -> 412 bytes
-rw-r--r--tools/linguist/book/images/prevunfinished.pngbin0 -> 449 bytes
-rw-r--r--tools/linguist/book/images/toolbar.pngbin0 -> 5397 bytes
-rw-r--r--tools/linguist/book/images/tt1_en.pngbin0 -> 872 bytes
-rw-r--r--tools/linguist/book/images/tt1_la.pngbin0 -> 894 bytes
-rw-r--r--tools/linguist/book/images/tt2_en.pngbin0 -> 1615 bytes
-rw-r--r--tools/linguist/book/images/tt2_fr.pngbin0 -> 1854 bytes
-rw-r--r--tools/linguist/book/images/tt2_nl.pngbin0 -> 1881 bytes
-rw-r--r--tools/linguist/book/images/tt3_10_en.pngbin0 -> 2286 bytes
-rw-r--r--tools/linguist/book/images/tt3_10_pt_bad.pngbin0 -> 2411 bytes
-rw-r--r--tools/linguist/book/images/tt3_10_pt_good.pngbin0 -> 2485 bytes
-rw-r--r--tools/linguist/book/images/tt3_11_about_pt.pngbin0 -> 2720 bytes
-rw-r--r--tools/linguist/book/images/tt3_11_en.pngbin0 -> 2368 bytes
-rw-r--r--tools/linguist/book/images/tt3_11_pt.pngbin0 -> 2537 bytes
-rw-r--r--tools/linguist/book/images/validateaccelerators.pngbin0 -> 387 bytes
-rw-r--r--tools/linguist/book/images/validatephrases.pngbin0 -> 293 bytes
-rw-r--r--tools/linguist/book/images/validatepunctuation.pngbin0 -> 373 bytes
-rw-r--r--tools/linguist/book/linguist-manager.leaf138
-rw-r--r--tools/linguist/book/linguist-manual.book90
-rw-r--r--tools/linguist/book/linguist-programmer.leaf1145
-rw-r--r--tools/linguist/book/linguist-translator.leaf582
38 files changed, 1955 insertions, 0 deletions
diff --git a/tools/linguist/book/images/doneandnext.png b/tools/linguist/book/images/doneandnext.png
new file mode 100644
index 000000000..47efaec76
--- /dev/null
+++ b/tools/linguist/book/images/doneandnext.png
Binary files differ
diff --git a/tools/linguist/book/images/editcopy.png b/tools/linguist/book/images/editcopy.png
new file mode 100644
index 000000000..efe8d03ee
--- /dev/null
+++ b/tools/linguist/book/images/editcopy.png
Binary files differ
diff --git a/tools/linguist/book/images/editcut.png b/tools/linguist/book/images/editcut.png
new file mode 100644
index 000000000..146388a29
--- /dev/null
+++ b/tools/linguist/book/images/editcut.png
Binary files differ
diff --git a/tools/linguist/book/images/editfind.png b/tools/linguist/book/images/editfind.png
new file mode 100644
index 000000000..59c63bf97
--- /dev/null
+++ b/tools/linguist/book/images/editfind.png
Binary files differ
diff --git a/tools/linguist/book/images/editpaste.png b/tools/linguist/book/images/editpaste.png
new file mode 100644
index 000000000..13f9a0f41
--- /dev/null
+++ b/tools/linguist/book/images/editpaste.png
Binary files differ
diff --git a/tools/linguist/book/images/editredo.png b/tools/linguist/book/images/editredo.png
new file mode 100644
index 000000000..6a30e2648
--- /dev/null
+++ b/tools/linguist/book/images/editredo.png
Binary files differ
diff --git a/tools/linguist/book/images/editundo.png b/tools/linguist/book/images/editundo.png
new file mode 100644
index 000000000..38a735758
--- /dev/null
+++ b/tools/linguist/book/images/editundo.png
Binary files differ
diff --git a/tools/linguist/book/images/fileopen.png b/tools/linguist/book/images/fileopen.png
new file mode 100644
index 000000000..44107d36c
--- /dev/null
+++ b/tools/linguist/book/images/fileopen.png
Binary files differ
diff --git a/tools/linguist/book/images/fileprint.png b/tools/linguist/book/images/fileprint.png
new file mode 100644
index 000000000..2936658f2
--- /dev/null
+++ b/tools/linguist/book/images/fileprint.png
Binary files differ
diff --git a/tools/linguist/book/images/filesave.png b/tools/linguist/book/images/filesave.png
new file mode 100644
index 000000000..03e10f917
--- /dev/null
+++ b/tools/linguist/book/images/filesave.png
Binary files differ
diff --git a/tools/linguist/book/images/finddialog.png b/tools/linguist/book/images/finddialog.png
new file mode 100644
index 000000000..c3b0f4332
--- /dev/null
+++ b/tools/linguist/book/images/finddialog.png
Binary files differ
diff --git a/tools/linguist/book/images/linguist.png b/tools/linguist/book/images/linguist.png
new file mode 100644
index 000000000..519c185ab
--- /dev/null
+++ b/tools/linguist/book/images/linguist.png
Binary files differ
diff --git a/tools/linguist/book/images/menubar.png b/tools/linguist/book/images/menubar.png
new file mode 100644
index 000000000..7ba43c60d
--- /dev/null
+++ b/tools/linguist/book/images/menubar.png
Binary files differ
diff --git a/tools/linguist/book/images/next.png b/tools/linguist/book/images/next.png
new file mode 100644
index 000000000..7434fa21d
--- /dev/null
+++ b/tools/linguist/book/images/next.png
Binary files differ
diff --git a/tools/linguist/book/images/nextunfinished.png b/tools/linguist/book/images/nextunfinished.png
new file mode 100644
index 000000000..618fc947d
--- /dev/null
+++ b/tools/linguist/book/images/nextunfinished.png
Binary files differ
diff --git a/tools/linguist/book/images/phrasebookdialog.png b/tools/linguist/book/images/phrasebookdialog.png
new file mode 100644
index 000000000..d1a323a5a
--- /dev/null
+++ b/tools/linguist/book/images/phrasebookdialog.png
Binary files differ
diff --git a/tools/linguist/book/images/phrasebookopen.png b/tools/linguist/book/images/phrasebookopen.png
new file mode 100644
index 000000000..4f76b7d4c
--- /dev/null
+++ b/tools/linguist/book/images/phrasebookopen.png
Binary files differ
diff --git a/tools/linguist/book/images/prev.png b/tools/linguist/book/images/prev.png
new file mode 100644
index 000000000..f9fbd935d
--- /dev/null
+++ b/tools/linguist/book/images/prev.png
Binary files differ
diff --git a/tools/linguist/book/images/prevunfinished.png b/tools/linguist/book/images/prevunfinished.png
new file mode 100644
index 000000000..25cc1a266
--- /dev/null
+++ b/tools/linguist/book/images/prevunfinished.png
Binary files differ
diff --git a/tools/linguist/book/images/toolbar.png b/tools/linguist/book/images/toolbar.png
new file mode 100644
index 000000000..5e6021f05
--- /dev/null
+++ b/tools/linguist/book/images/toolbar.png
Binary files differ
diff --git a/tools/linguist/book/images/tt1_en.png b/tools/linguist/book/images/tt1_en.png
new file mode 100644
index 000000000..66e54e027
--- /dev/null
+++ b/tools/linguist/book/images/tt1_en.png
Binary files differ
diff --git a/tools/linguist/book/images/tt1_la.png b/tools/linguist/book/images/tt1_la.png
new file mode 100644
index 000000000..a70134908
--- /dev/null
+++ b/tools/linguist/book/images/tt1_la.png
Binary files differ
diff --git a/tools/linguist/book/images/tt2_en.png b/tools/linguist/book/images/tt2_en.png
new file mode 100644
index 000000000..c71e2010b
--- /dev/null
+++ b/tools/linguist/book/images/tt2_en.png
Binary files differ
diff --git a/tools/linguist/book/images/tt2_fr.png b/tools/linguist/book/images/tt2_fr.png
new file mode 100644
index 000000000..acc25157e
--- /dev/null
+++ b/tools/linguist/book/images/tt2_fr.png
Binary files differ
diff --git a/tools/linguist/book/images/tt2_nl.png b/tools/linguist/book/images/tt2_nl.png
new file mode 100644
index 000000000..4631de21f
--- /dev/null
+++ b/tools/linguist/book/images/tt2_nl.png
Binary files differ
diff --git a/tools/linguist/book/images/tt3_10_en.png b/tools/linguist/book/images/tt3_10_en.png
new file mode 100644
index 000000000..e95bff9e1
--- /dev/null
+++ b/tools/linguist/book/images/tt3_10_en.png
Binary files differ
diff --git a/tools/linguist/book/images/tt3_10_pt_bad.png b/tools/linguist/book/images/tt3_10_pt_bad.png
new file mode 100644
index 000000000..05cb5f3cf
--- /dev/null
+++ b/tools/linguist/book/images/tt3_10_pt_bad.png
Binary files differ
diff --git a/tools/linguist/book/images/tt3_10_pt_good.png b/tools/linguist/book/images/tt3_10_pt_good.png
new file mode 100644
index 000000000..b0f855f5a
--- /dev/null
+++ b/tools/linguist/book/images/tt3_10_pt_good.png
Binary files differ
diff --git a/tools/linguist/book/images/tt3_11_about_pt.png b/tools/linguist/book/images/tt3_11_about_pt.png
new file mode 100644
index 000000000..446731445
--- /dev/null
+++ b/tools/linguist/book/images/tt3_11_about_pt.png
Binary files differ
diff --git a/tools/linguist/book/images/tt3_11_en.png b/tools/linguist/book/images/tt3_11_en.png
new file mode 100644
index 000000000..7d98b98cc
--- /dev/null
+++ b/tools/linguist/book/images/tt3_11_en.png
Binary files differ
diff --git a/tools/linguist/book/images/tt3_11_pt.png b/tools/linguist/book/images/tt3_11_pt.png
new file mode 100644
index 000000000..02910cf0d
--- /dev/null
+++ b/tools/linguist/book/images/tt3_11_pt.png
Binary files differ
diff --git a/tools/linguist/book/images/validateaccelerators.png b/tools/linguist/book/images/validateaccelerators.png
new file mode 100644
index 000000000..68201fec8
--- /dev/null
+++ b/tools/linguist/book/images/validateaccelerators.png
Binary files differ
diff --git a/tools/linguist/book/images/validatephrases.png b/tools/linguist/book/images/validatephrases.png
new file mode 100644
index 000000000..62fe5f281
--- /dev/null
+++ b/tools/linguist/book/images/validatephrases.png
Binary files differ
diff --git a/tools/linguist/book/images/validatepunctuation.png b/tools/linguist/book/images/validatepunctuation.png
new file mode 100644
index 000000000..8ce2648d9
--- /dev/null
+++ b/tools/linguist/book/images/validatepunctuation.png
Binary files differ
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:
+"\&#xf8;". 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.