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