/****************************************************************************

**

** Copyright (C) 2009 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 runtime translation files for use by the released

    application.

    The \l{linguist-translators.html}{Translators} chapter is for

    translators. It describes the use of the \QL tool.

    No computer knowledge beyond the ability to start a program and

    use a text editor or word processor is required.

    The \l{linguist-programmers.html}{Programmers} chapter is for Qt

    programmers. It explains how to create Qt applications that are

    able to use translated text. It also provides guidance on how to

    help the translator identify the context in which phrases appear.

    This chapter's three short tutorials cover everything the

    programmer needs to do.

    \section1 Overview of the Translation Process

    Most of the text that must be translated in an application program

    consists of either single words or short phrases. These typically

    appear as window titles, menu items, pop-up help text (balloon help),

    and labels to buttons, check boxes and radio buttons.

    The phrases are entered into the source code by the programmer in

    their native language using a simple but special syntax to identify

    that the phrases require translation. The Qt tools provide context

    information for each of the phrases to help the translator, and the

    programmer is able to add additional context information to phrases

    when necessary. The release manager generates a set of translation

    files that are produced from the source files and passes these to the

    translator. The translator opens the translation files using \QL, 

    enters their translations and saves the results back into

    the translation files, which they pass back to the release manager.

    The release manager then generates fast compact versions of these

    translation files ready for use by the application. The tools are

    designed to be used in repeated cycles as applications change and

    evolve, preserving existing translations and making it easy to

    identify which new translations are required. \QL also

    provides a phrase book facility to help ensure consistent

    translations across multiple applications and projects.

    Translators and programmers must address a number of issues because

    of the subtleties and complexities of human language:

    \list

    \o A single phrase may need to be translated into several

    different forms depending on context, e.g. \e open in English

    might become \e{\ouml\c{}ffnen}, "open file", or \e aufbauen,

    "open internet connection", in German.

    \o Keyboard accelerators may need to be changed but without

    introducing conflicts, e.g. "\&Quit" in English becomes "Avslutt"

    in Norwegian which doesn't contain a "Q". We cannot use a letter

    that is already in use - unless we change several accelerators.

    \o Phrases that contain variables, for example, "The 25 files

    selected will take 63 seconds to process", where the two numbers

    are inserted programmatically at runtime may need to be reworded

    because in a different language the word order and therefore the

    placement of the variables may have to change.

    \endlist

    The Qt translation tools provide clear and simple solutions to these

    issues.

    Chapters:

    \list

    \o \l{Qt Linguist Manual: Release Manager}{Release Manager}

    \o \l{Qt Linguist Manual: Translators}{Translators}

    \o \l{Qt Linguist Manual: Programmers}{Programmers}

    \o \l{Qt Linguist Manual: TS File Format}{TS File Format}

    \endlist

    \QL and \c lupdate are able to import and export XML Localization

    Interchange File Format (XLIFF) files, making it possible to take

    advantage of tools and translation services that work with this

    format. See the \l{Qt Linguist Manual: Translators} {Translators}

    section for more information on working with these files.

    \table

    \row \o{1,2} \inlineimage wVista-Cert-border-small.png

    \o \e{Qt Linguist 4.3 is Certified for Windows Vista}

    \row \o Windows Vista and the Windows Vista Start button are

    trademarks or registered trademarks of Microsoft Corporation in

    the United States and/or other countries.

    \endtable

*/

/*!

    \page linguist-manager.html

    \title Qt Linguist Manual: Release Manager

    \contentspage {Qt Linguist Manual}{Contents}

    \previouspage Qt Linguist Manual

    \nextpage Qt Linguist Manual: Translators

    \keyword lupdate

    \keyword lrelease

    Two tools are provided for the release manager, \l lupdate and \l

    lrelease. These tools can process \l qmake project files, or operate

    directly on the file system.

    \section1 Qt Project Files

    The easiest method to use \l{#lupdate} {lupdate} and \l{#lrelease}

    {lrelease} is by specifing a \c .pro Qt project file. There must

    be an entry in the \c TRANSLATIONS section of the project file for

    each language that is additional to the native language. A typical

    entry looks like this:

    \snippet examples/linguist/arrowpad/arrowpad.pro 1

    Using a locale within the translation file name is useful for

    determining which language to load at runtime. This is explained

    in the \l{linguist-programmers.html} {Programmers} chapter.

    An example of a complete \c .pro file with four translation source

    files:

    \snippet doc/src/snippets/code/doc_src_linguist-manual.qdoc 0

    \snippet doc/src/snippets/code/doc_src_linguist-manual.qdoc 1

    QTextCodec::setCodecForTr() makes it possible to choose a 8-bit

    encoding for literal strings that appear within \c tr() calls.

    This is useful for applications whose source language is, for

    example, Chinese or Japanese. If no encoding is set, \c tr() uses

    Latin1.

    If you do use the QTextCodec::codecForTr() mechanism in your

    application, \QL needs you to set the \c CODECFORTR

    entry in the \c .pro file as well. For example:

    \snippet doc/src/snippets/code/doc_src_linguist-manual.qdoc 1

    Also, if your compiler uses a different encoding for its runtime

    system as for its source code and you want to use  non-ASCII

    characters in string literals, you will need to set the \c

    CODECFORSRC. For example:

    \snippet doc/src/snippets/code/doc_src_linguist-manual.qdoc 2

    Microsoft Visual Studio 2005 .NET appears to be the only compiler

    for which this is necessary. However, if you want to write

    portable code, we recommend that you avoid non-ASCII characters

    in your source files. You can still specify non-ASCII characters

    portably using escape sequences, for example:

    \snippet doc/src/snippets/code/doc_src_linguist-manual.qdoc 3

    \target lupdate manual

    \section1 lupdate

    Usage: \c {lupdate myproject.pro}

    \l lupdate is a command line tool that finds the translatable

    strings in the specified source, header and \e {Qt Designer}

    interface files, and produces or updates \c .ts translation

    files. The files to process and the files to update can be set at

    the command line, or provided in a \c .pro file specified as an

    command line argument. The produced translation files are given to

    the translator who uses \QL to read the files and insert the

    translations.

    Companies that have their own translators in-house may find it

    useful to run \l lupdate regularly, perhaps monthly, as the

    application develops. This will lead to a fairly low volume of

    translation work spread evenly over the life of the project and

    will allow the translators to support a number of projects

    simultaneously.

    Companies that hire in translators as required may prefer to run

    \l lupdate only a few times in the application's life cycle, the

    first time might be just before the first test phase. This will

    provide the translator with a substantial single block of work and

    any bugs that the translator detects may easily be included with

    those found during the initial test phase. The second and any

    subsequent \l lupdate runs would probably take place during the

    final beta phase.

    The TS file format is a simple human-readable XML format that

    can be used with version control systems if required. \c lupdate

    can also process Localization Interchange File Format (XLIFF)

    format files; files in this format typically have file names that

    end with the \c .xlf suffix.

    Pass the \c -help option to \c lupdate to obtain the list of

    supported options:

    \snippet doc/src/snippets/code/doc_src_linguist-manual.qdoc 4

    \QL is also able to import and export XLIFF files. See the

    \l{Qt Linguist Manual: Translators}{Translators} section for more

    information.

    \section1 lrelease

    Usage: \c {lrelease myproject.pro}

    \l lrelease is a command line tool that produces QM files out

    of TS files. The QM file format is a compact binary format

    that is used by the localized application. It provides extremely

    fast lookups for translations. The TS files \l lrelease

    processes can be specified at the command line, or given

    indirectly by a Qt \c .pro project file.

    This tool is run whenever a release of the application is to be

    made, from initial test version through to final release

    version. If the QM files are not created, e.g. because an

    alpha release is required before any translation has been

    undertaken, the application will run perfectly well using the text

    the programmers placed in the source files. Once the QM files

    are available the application will detect them and use them

    automatically.

    Note that lrelease will only incorporate translations that are

    marked as "finished". Otherwise the original text will be used

    instead.

    Pass the \c -help option to \c lrelease to obtain the list of

    supported options:

    \snippet doc/src/snippets/code/doc_src_linguist-manual.qdoc 5

    \section1 Missing Translations

    Both \l lupdate and \l lrelease may be used with TS

    translation source files which are incomplete. Missing

    translations will be replaced with the native language phrases at

    runtime.  

*/

/*!

    \page linguist-translators.html

    \title Qt Linguist Manual: Translators

    \contentspage {Qt Linguist Manual}{Contents}

    \previouspage Qt Linguist Manual: Release Manager

    \nextpage Qt Linguist Manual: Programmers

    Contents

    \tableofcontents

    \section1 The One Minute Guide to Using Qt Linguist

    \QL is a tool for adding translations to Qt applications. Run \QL

    from the taskbar menu, or by double clicking the desktop icon, or

    by entering the command \c {linguist} at the command line. Once

    \QL has started, choose \menu{File|Open} from the \l{menubar}

    {menu bar} and select a translation source (TS file) to

    load. If you do not have a TS file, see the \l {Qt Linguist

    Manual: Release Manager} {release manager manual} to learn how to

    generate one.

    The \QL main window is divided into several, dockable subwindows

    arranged around a central \l{The Translation Area} {translation

    area}. The \l{Context Window} {context list} is normally shown

    on the left, and the \l{Sources and Forms Window} {source code},

    \l{Strings Window} {string list}, and either the \l{Phrases and 

    Guesses Window} {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