/****************************************************************************+
−
**+
−
** 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$+
−
**+
−
****************************************************************************/+
−
+
−
/*!+
−
    \example linguist/trollprint+
−
    \title Troll Print Example+
−
+
−
    Troll Print is an example application that lets the user choose+
−
    printer settings. It comes in two versions: English and+
−
    Portuguese.+
−
+
−
    \image linguist-trollprint_10_en.png+
−
+
−
    We've included a translation file, \c trollprint_pt.ts, which contains some+
−
    Portuguese translations for this example.+
−
+
−
    We will consider two releases of the same application: Troll Print+
−
    1.0 and 1.1. We will learn to reuse the translations created for one+
−
    release in a subsequent release. (In this tutorial, you need to edit+
−
    some source files. It's probably best to copy all the files to a new+
−
    temporary directory and work from there.)+
−
+
−
    See the \l{Qt Linguist manual} for more information about+
−
    translating Qt application.+
−
+
−
    \section1 Line by Line Walkthrough+
−
+
−
    The \c PrintPanel class is defined in \c printpanel.h.+
−
+
−
    \snippet examples/linguist/trollprint/printpanel.h 0+
−
+
−
    \c PrintPanel is a QWidget. It needs the \c Q_OBJECT macro for \c+
−
    tr() to work properly.+
−
+
−
    The implementation file is \c printpanel.cpp.+
−
+
−
    \snippet examples/linguist/trollprint/printpanel.cpp 0+
−
+
−
    Some of the code is commented out in Troll Print 1.0; you will+
−
    uncomment it later, for Troll Print 1.1.+
−
+
−
    \snippet examples/linguist/trollprint/printpanel.cpp 1+
−
    \snippet examples/linguist/trollprint/printpanel.cpp 2+
−
+
−
    Notice the two occurrences of \c tr("Enabled") and of \c+
−
    tr("Disabled") in PrintPanel. Since both "Enabled"s and "Disabled"s+
−
    appear in the same context \e {Qt Linguist} will only display one+
−
    occurrence of each and will use the same translations for the+
−
    duplicates that it doesn't display. Whilst this is a useful+
−
    timesaver, in some languages, such as Portuguese, the second+
−
    occurrence requires a separate translation. We will see how \e {Qt+
−
    Linguist} can be made to display all the occurrences for separate+
−
    translation shortly.+
−
+
−
    The header file for \c MainWindow, \c mainwindow.h, contains no+
−
    surprises. In the implementation, \c mainwindow.cpp, we have some+
−
    user-visible source texts that must be marked for translation.+
−
+
−
    \snippet examples/linguist/trollprint/mainwindow.cpp 0+
−
+
−
    We must translate the window title.+
−
+
−
    \snippet examples/linguist/trollprint/mainwindow.cpp 1+
−
    \snippet examples/linguist/trollprint/mainwindow.cpp 3+
−
+
−
    We also need to translate the actions and menus. Note that the+
−
    two argument form of \c tr() is used for the keyboard+
−
    accelerator, "Ctrl+Q", since the second argument is the only clue+
−
    the translator has to indicate what function that accelerator+
−
    will perform.+
−
+
−
    \snippet examples/linguist/trollprint/main.cpp 0+
−
+
−
    The \c main() function in \c main.cpp is the same as the one in+
−
    the \l{linguist/arrowpad}{Arrow Pad} example. In particular, it+
−
    chooses a translation file based on the current locale.+
−
+
−
    \section1 Running Troll Print 1.0 in English and in Portuguese+
−
+
−
    We will use the translations in the \c trollprint_pt.ts file that is provided.+
−
+
−
    Set the \c LANG environment variable to \c pt, and then run \c+
−
    trollprint. You should still see the English version. Now run \c+
−
    lrelease, e.g. \c {lrelease trollprint.pro}, and then run the+
−
    example again. Now you should see the Portuguese edition (Troll+
−
    Imprimir 1.0):+
−
+
−
    \image linguist-trollprint_10_pt_bad.png+
−
+
−
    Whilst the translation has appeared correctly, it is in fact wrong. In+
−
    good Portuguese, the second occurrence of "Enabled" should be+
−
    "Ativadas", not "Ativado" and the ending for the second translation of+
−
    "Disabled" must change similarly too.+
−
+
−
    If you open \c trollprint_pt.ts using \e {Qt Linguist}, you will see that+
−
    there is just one occurrence of "Enabled" and of "Disabled" in the+
−
    translation source file, even though there are two of each in the+
−
    source code. This is because \e {Qt Linguist} tries to minimize the+
−
    translator's work by using the same translation for duplicate source+
−
    texts. In cases such as this where an identical translation is wrong,+
−
    the programmer must disambiguate the duplicate occurrences. This is+
−
    easily achieved by using the two argument form of \c tr().+
−
+
−
    We can easily determine which file must be changed because the+
−
    translator's "context" is in fact the class name for the class where+
−
    the texts that must be changed appears. In this case the file is \c+
−
    printpanel.cpp, where there are four lines to change. Add the+
−
    second argument "two-sided" in the appropriate \c tr() calls to the+
−
    first pair of radio buttons:+
−
+
−
    \snippet doc/src/snippets/code/doc_src_examples_trollprint.qdoc 0+
−
+
−
    and add the second argument "colors" in the appropriate \c tr() calls+
−
    for the second pair of radio buttons:+
−
+
−
    \snippet doc/src/snippets/code/doc_src_examples_trollprint.qdoc 1+
−
+
−
    Now run \c lupdate and open \c trollprint_pt.ts with \e {Qt Linguist}. You+
−
    should now see two changes.+
−
+
−
    First, the translation source file now contains \e three "Enabled",+
−
    "Disabled" pairs. The first pair is marked "(obs.)" signifying that they+
−
    are obsolete. This is because these texts appeared in \c tr() calls that+
−
    have been replaced by new calls with two arguments. The second pair has+
−
    "two-sided" as their comment, and the third pair has "colors" as their+
−
    comment. The comments are shown in the \gui {Source text and comments}+
−
    area in \e {Qt Linguist}.+
−
+
−
    Second, the translation text "Ativado" and "Desativado" have been+
−
    automatically used as translations for the new "Enabled" and "Disabled"+
−
    texts, again to minimize the translator's work. Of course in this case+
−
    these are not correct for the second occurrence of each word, but they+
−
    provide a good starting point.+
−
+
−
    Change the second "Ativado" into "Ativadas" and the second+
−
    "Desativado" into "Desativadas", then save and quit. Run \c lrelease+
−
    to obtain an up-to-date binary \c trollprint_pt.qm file, and run Troll Print+
−
    (or rather Troll Imprimir).+
−
+
−
    \image linguist-trollprint_10_pt_good.png+
−
+
−
    The second argument to \c tr() calls, called "comments" in \e {Qt+
−
    Linguist}, distinguish between identical source texts that occur in+
−
    the same context (class). They are also useful in other cases to give+
−
    clues to the translator, and in the case of Ctrl key accelerators are+
−
    the only means of conveying the function performed by the accelerator to+
−
    the translator.+
−
+
−
    An additional way of helping the translator is to provide information on+
−
    how to navigate to the particular part of the application that contains+
−
    the source texts they must translate. This helps them see the context+
−
    in which the translation appears and also helps them to find and test+
−
    the translations. This can be achieved by using a \c TRANSLATOR comment+
−
    in the source code:+
−
+
−
    \snippet doc/src/snippets/code/doc_src_examples_trollprint.qdoc 2+
−
+
−
    Try adding these comments to some source files, particularly to+
−
    dialog classes, describing the navigation necessary to reach the+
−
    dialogs. You could also add them to the example files, e.g. \c+
−
    mainwindow.cpp and \c printpanel.cpp are appropriate files. Run \c+
−
    lupdate and then start \e {Qt Linguist} and load in \c trollprint_pt.ts.+
−
    You should see the comments in the \gui {Source text and comments} area+
−
    as you browse through the list of source texts.+
−
+
−
    Sometimes, particularly with large programs, it can be difficult for+
−
    the translator to find their translations and check that they're+
−
    correct. Comments that provide good navigation information can save+
−
    them time:+
−
+
−
    \snippet doc/src/snippets/code/doc_src_examples_trollprint.qdoc 3+
−
+
−
    \section1 Troll Print 1.1+
−
+
−
    We'll now prepare release 1.1 of Troll Print. Start your favorite text+
−
    editor and follow these steps:+
−
+
−
    \list+
−
    \o Uncomment the two lines that create a QLabel with the text+
−
         "\<b\>TROLL PRINT\</b\>" in \c printpanel.cpp.+
−
    \o Word-tidying: Replace "2-sided" by "Two-sided" in \c printpanel.cpp.+
−
    \o Replace "1.0" with "1.1" everywhere it occurs in \c mainwindow.cpp.+
−
    \o Update the copyright year to 1999-2000 in \c mainwindow.cpp.+
−
    \endlist+
−
+
−
    (Of course the version number and copyright year would be consts or+
−
    #defines in a real application.)+
−
+
−
    Once finished, run \c lupdate, then open \c trollprint_pt.ts in \e {Qt+
−
    Linguist}. The following items are of special interest:+
−
+
−
    \list+
−
    \o \c MainWindow+
−
         \list+
−
         \o Troll Print 1.0 - marked "(obs.)", obsolete+
−
         \o About Troll Print 1.0 - marked "(obs.)", obsolete+
−
         \o Troll Print 1.0. Copyright 1999 Software, Inc. -+
−
       marked obsolete+
−
         \o Troll Print 1.1 - automatically translated as+
−
       "Troll Imprimir 1.1"+
−
         \o About Troll Print 1.1 - automatically translated as+
−
       "Troll Imprimir 1.1"+
−
         \o Troll Print 1.1. Copyright 1999-2000 Software,+
−
       Inc. - automatically translated as "Troll Imprimir 1.1.+
−
       Copyright 1999-2000 Software, Inc."+
−
         \endlist+
−
    \o \c PrintPanel+
−
         \list+
−
         \o 2-sided - marked "(obs.)", obsolete+
−
         \o \<b\>TROLL PRINT\</b\> - unmarked, i.e. untranslated+
−
         \o Two-sided - unmarked, i.e. untranslated.+
−
         \endlist+
−
    \endlist+
−
+
−
    Notice that \c lupdate works hard behind the scenes to make revisions+
−
    easier, and it's pretty smart with numbers.+
−
+
−
    Go over the translations in \c MainWindow and mark these as "done".+
−
    Translate "\<b\>TROLL PRINT\</b\>" as "\<b\>TROLL IMPRIMIR\</b\>".+
−
    When you're translating "Two-sided", press the \gui {Guess Again}+
−
    button to translate "Two-sided", but change the "2" into "Dois".+
−
+
−
    Save and quit, then run \c lrelease. The Portuguese version+
−
    should look like this:+
−
+
−
    \image linguist-trollprint_11_pt.png+
−
+
−
    Choose \gui{Ajuda|Sobre} (\gui{Help|About}) to see the about box.+
−
+
−
    If you choose \gui {Ajuda|Sobre Qt} (\gui {Help|About Qt}), you'll get+
−
    an English dialog. Oops! Qt itself needs to be translated. See+
−
    \l{Internationalization with Qt} for details.+
−
+
−
    Now set \c LANG=en to get the original English version:+
−
+
−
    \image linguist-trollprint_11_en.png+
−
*/+
−