/****************************************************************************
**
** Copyright (C) 2004-2007 Trolltech ASA. All rights reserved.
**
** This file is part of the documentation of the Qt Toolkit.
**
** This file may be used under the terms of the GNU General Public
** License version 2.0 as published by the Free Software Foundation
** and appearing in the file LICENSE.GPL included in the packaging of
** this file.  Please review the following information to ensure GNU
** General Public Licensing requirements will be met:
** http://trolltech.com/products/qt/licenses/licensing/opensource/
**
** If you are unsure which license is appropriate for your use, please
** review the following information:
** http://trolltech.com/products/qt/licenses/licensing/licensingoverview
** or contact the sales department at sales@trolltech.com.
**
** In addition, as a special exception, Trolltech gives you certain
** additional rights. These rights are described in the Trolltech GPL
** Exception version 1.0, which can be found at
** http://www.trolltech.com/products/qt/gplexception/ and in the file
** GPL_EXCEPTION.txt in this package.
**
** In addition, as a special exception, Trolltech, as the sole copyright
** holder for Qt Designer, grants users of the Qt/Eclipse Integration
** plug-in the right for the Qt/Eclipse Integration to link to
** functionality provided by Qt Designer and its related libraries.
**
** Trolltech reserves all rights not expressly granted herein.
**
** This file is provided AS IS with NO WARRANTY OF ANY KIND, INCLUDING THE
** WARRANTY OF DESIGN, MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
**
****************************************************************************/

/*!
    \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 \e {Qt Linguist} 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 \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 required. \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
    \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

    \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 depend on \e qmake project files. You don't
    have to use \e qmake, though.

    \section1 Qt 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:

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

    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:
    \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

     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, \e {Qt Linguist} needs you to set the \c CODECFORTR
    entry in the \c .pro file as well. For example:

    \code
        CODECFORTR      = ISO-8859-5
    \endcode

    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:

    \code
        CODECFORSRC     = UTF-8
    \endcode

    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:

    \code
        label->setText(tr("F\374r \310lise"));
    \endcode

    \section1 lupdate

    Usage: \c {lupdate myproject.pro}

    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 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 \c .ts file format is a simple human-readable XML format that can
    be used with version control systems if required.

    Qt Linguist is also 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.

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

    \code
    Usage:
        lupdate [options] [project-file]
        lupdate [options] [source-file|path]... -ts ts-files
    Options:
        -help  Display this information and exit.
        -noobsolete
               Drop all obsolete strings.
        -extensions <ext>[,<ext>]...
               Process files with the given extensions only.
               The extension list must be separated with commas, not with whitespace.
               Default: 'ui,c,c++,cc,cpp,cxx,ch,h,h++,hh,hpp,hxx'.
        -silent
               Don't explain what is being done.
        -version
               Display the version of lupdate and exit.
    \endcode

    \section1 lrelease

    Usage: \c {lrelease myproject.pro}

    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 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 \c .qm files are available the application will
    detect them and use them automatically.

    Note that 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.

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

    \code
        Usage:
            lrelease [options] project-file
            lrelease [options] ts-files [-qm qm-file]
        Options:
            -help  Display this information and exit
            -compress
                   Compress the .qm files
            -nounfinished
                   Do not include unfinished translations
            -silent
                   Don't explain what is being done
            -version
                   Display the version of lrelease and exit
    \endcode

    \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.
*/

/*!
    \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

    \image linguist-linguist.png
    \caption Linguist Main Window

    \section1 The One Minute Guide to Using Qt Linguist

    \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
    requires 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 quit.

    \section1 Qt Linguist's Main Window

    \section2 Context List

    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

    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 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, \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+Return}) 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

    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.

    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.

    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 "\underline{N}ew 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 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 choosing the \e {Begin from Source}
    entry in the \gui Translation 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 \gui Translation 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

    \image linguist-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 \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 \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 required 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

    \e {Qt Linguist} provides three kinds of validation on translated
    phrases.

    \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.
    \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:

    \list
    \o \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.
    \o \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}.
    \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 \e {Qt Linguist} and may be used by any
    number of projects and applications.
    \endlist

    \section2 The Menu Bar

    \image linguist-menubar.png
    \caption Menu Bar

    \list
    \o \e {File}
        \list
        \o \e {Open... Ctrl+O} \BR pops up an open file dialog from which a
        translation source \c .ts file can be chosen.
        \o \e {Save Ctrl+S} \BR saves the current translation source \c .ts file.
        \o \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.
        \o \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.
        \o \e {Print... Ctrl+P} \BR pops up a print dialog. If you click
        OK the translation source and the translations will be printed.
        \o \e {Recently opened files} \BR shows the \c .ts files that
        have been opened recently, click one to open it.
        \o \e {Exit Ctrl+Q} \BR closes \e {Qt Linguist}.
        \endlist

    \o \e {Edit}
        \list
        \o \e {Undo Ctrl+Z} \BR undoes the last editing action in the
        translation pane.
        \o \e {Redo Ctrl+Y} \BR redoes the last editing action in the
        translation pane.
        \o \e {Cut Ctrl+X} \BR deletes any highlighted text in the
        translation pane and saves a copy to the clipboard.
        \o \e {Copy Ctrl+C} \BR copies the highlighted text in the
        translation pane to the clipboard.
        \o \e {Paste Ctrl+V} \BR pastes the clipboard text into the
        translation pane.
    \omit
        \o \e {Delete} \BR deletes the highlighted text in the
        translation pane.
    \endomit
        \o \e {Select All Ctrl+A} \BR selects all the text in the
        translation pane ready for copying or deleting.
        \o \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.
        \o \e {Find Next F3} \BR finds the next occurrence of the text that
        was last entered in the Find dialog.
        \endlist

    \o \e {Translation}
        \list
        \o \e {Prev Unfinished Ctrl+K} \BR moves to the nearest previous
        unfinished source phrase (unfinished means untranslated or
        translated but failed validation).
        \o \e {Next Unfinished Ctrl+L} \BR moves to the next unfinished source
        phrase.
        \o \e {Prev Shift+Ctrl+K} \BR moves to the previous source phrase.
        \o \e {Next Shift+Ctrl+L} \BR moves to the next source phrase.
        \o \e {Done \& NextCtrl+Enter} \BR mark this phrase as 'done'
        (translated) and move to the next unfinished source phrase.
        \o \e {Begin from Source Ctrl+B} \BR copies the source text into
        the translation.
        \endlist

    \o \e {Validation} (See the \l Validation section)
        \list
        \o \e {Accelerators} \BR toggles validation on or off for Alt
        accelerators.
        \o \e {Ending Punctuation} \BR switches validation on or off
        for phrase ending punctuation, e.g. ellipsis, exclamation mark,
        question mark, etc.
        \o \e {Phrase Matches} \BR sets validation on or off for
        matching against translations that are in the current phrase book.
        \endlist

    \o \e {Phrase} (See the section \l {Creating and Using Phrase Books}
    for details.)
        \list
        \o \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.
        \o \e {Open Phrase Book... Ctrl+H} \BR pops up an open file dialog.
        Find and choose a phrase book to open.
        \o \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.
        \o \e {Edit Phrase Book...} \BR pops up the
        \link {The Phrase Dialog} phrase book dialog \endlink where you can
        add, edit or delete phrases.
        \o \e {Print Phrase Book...} \BR pops up a print dialog. If
        you click OK the phrase book will be printed.
        \endlist

    \o \e {View}
        \list
        \o \e {Revert Sorting} \BR puts the phrases in the source text
        pane into their original order.
        \o \e {Display Guesses} \BR turns the display of phrases and
        guesses on or off.
        \o \e {Statistics} \BR toggles the visibility of the Statistics dialog.
        \o \e {Views} \BR toggles the visibility of the Context, Source text and
         Phrase views.
        \o \e {Toolbars} \BR toggles the visibility of the different toolbars.
    \omit
        \o \e {Large Icons} \BR switches between large or standard
        size icons on the toolbar.
        \o \e {Text Labels} \BR toggles the use of text labels on the
        toolbar icons.
    \endomit
        \endlist

    \endlist

    \section2 The Toolbar

    \image linguist-toolbar.png
    \caption Toolbar

    \list
    \o \inlineimage linguist-fileopen.png
    \BR
    Pops up the open file dialog to open a new translation source \c .ts
    file.

    \o \inlineimage linguist-filesave.png
    \BR
    Saves the current translation source \c .ts file.

    \o \inlineimage linguist-fileprint.png
    \BR
    Prints the current translation source \c .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 \link {The Find Dialog} Find dialog \endlink.

    \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.
    \endlist

    \section2 The Find Dialog

    \inlineimage linguist-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.
*/

/*!
    \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 \c .ts
    translation source files with all the user-visible text but no
    translations.
    \o 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.
    \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 \c .ts files and produce the \c .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
    \snippet examples/linguist/arrowpad/arrowpad.pro 2

    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

    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.

    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:
    \code
        button = new QPushButton("&Quit", this);
    \endcode

    would become

    \code
        button = new QPushButton(tr("&Quit"), this);
    \endcode

    All \l QObject subclasses that use the 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 Require Different Translations

    The \l lupdate program automatically provides a \e context for every
    source text. This context is the class name of the class that contains
    the \c tr() call. This is sufficient in the vast majority of cases.
    Sometimes however, the translator will need further information to
    uniquely identify a source text; for example, a dialog that contained
    two separate frames, each of which contained an "Enabled" option would
    need each identified because in some languages the translation would
    differ between the two. This is easily achieved using the
    two argument form of the \c tr() call, e.g.

    \code
           rbc = new QRadioButton(tr("Enabled", "Color frame"), this);
    \endcode

    and

    \code
           rbh = new QRadioButton(tr("Enabled", "Hue frame"), this);
    \endcode

    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.

    \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

    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():

    \code
        /*
            TRANSLATOR MyNamespace::MyClass

            Necessary for lupdate.

            ...
    \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 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:

    \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:

    \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 \c .ts file format used by Qt Linguist 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
    
*/
