Revision control
++ // Copyright (C) 2016 The Qt Company Ltd.
++ // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
++
++ /*!
++ \example trollprint
++ \ingroup examples-linguist
++ \examplecategory {User Interface Components}
++
++ \title Troll Print Example
++
++ \brief Updating translations for later releases.
++
++ 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 {Screenshot showing the Troll Print
++ example UI in English}
++
++ 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 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 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 trollprint/printpanel.cpp 1
++ \snippet 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 trollprint/mainwindow.cpp 0
++
++ We must translate the window title.
++
++ \snippet trollprint/mainwindow.cpp 1
++ \snippet 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 trollprint/main.cpp 0
++
++ The \c main() function in \c main.cpp is the same as the one in
++ the \l{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 {Screenshot showing the troll
++ print UI in Portuguese}
++
++ 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/snippets/doc_src_examples_trollprint.cpp 0
++
++ and add the second argument "colors" in the appropriate \c tr() calls
++ for the second pair of radio buttons:
++
++ \snippet doc/snippets/doc_src_examples_trollprint.cpp 1
++
++ Now recompile, 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 \uicontrol {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 {Screenshot showing the troll print
++ in portuguese}
++
++ 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/snippets/doc_src_examples_trollprint.cpp 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 \uicontrol {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/snippets/doc_src_examples_trollprint.cpp 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
++ \li Uncomment the two lines that create a QLabel with the text
++ "\<b\>TROLL PRINT\</b\>" in \c printpanel.cpp.
++ \li Word-tidying: Replace "2-sided" by "Two-sided" in \c printpanel.cpp.
++ \li Replace "1.0" with "1.1" everywhere it occurs in \c mainwindow.cpp.
++ \li 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
++ \li \c PrintPanel
++ \list
++ \li 2-sided - marked "(obs.)", obsolete
++ \li \<b\>TROLL PRINT\</b\> - unmarked, i.e. untranslated
++ \li Two-sided - unmarked, i.e. untranslated.
++ \endlist
++ \endlist
++
++ In order to make revisions easier, instead of tr("Troll Print 1.0")
++ you can use tr("Troll Print %1").arg("1.0") or such to avoid having to update
++ the string on every release.
++
++ 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 \uicontrol {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 {Screenshot showing the troll print
++ in portuguese}
++
++ Choose \uicontrol{Ajuda|Sobre} (\uicontrol{Help|About}) to see the about box.
++
++ If you choose \uicontrol {Ajuda|Sobre Qt} (\uicontrol {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 {Screenshot showing the troll print
++ in english}
++ */