| /**************************************************************************** |
| ** |
| ** Copyright (C) 2016 The Qt Company Ltd. |
| ** Contact: https://www.qt.io/licensing/ |
| ** |
| ** This file is part of the documentation of the Qt Toolkit. |
| ** |
| ** $QT_BEGIN_LICENSE:FDL$ |
| ** Commercial License Usage |
| ** Licensees holding valid commercial Qt licenses may use this file in |
| ** accordance with the commercial license agreement provided with the |
| ** Software or, alternatively, in accordance with the terms contained in |
| ** a written agreement between you and The Qt Company. For licensing terms |
| ** and conditions see https://www.qt.io/terms-conditions. For further |
| ** information use the contact form at https://www.qt.io/contact-us. |
| ** |
| ** GNU Free Documentation License Usage |
| ** Alternatively, this file may be used under the terms of the GNU Free |
| ** Documentation License version 1.3 as published by the Free Software |
| ** Foundation and appearing in the file included in the packaging of |
| ** this file. Please review the following information to ensure |
| ** the GNU Free Documentation License version 1.3 requirements |
| ** will be met: https://www.gnu.org/licenses/fdl-1.3.html. |
| ** $QT_END_LICENSE$ |
| ** |
| ****************************************************************************/ |
| |
| /*! |
| \example trollprint |
| \ingroup examples-linguist |
| \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 |
| |
| 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 |
| |
| 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 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 |
| |
| 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 MainWindow |
| \list |
| \li Troll Print 1.0 - marked "(obs.)", obsolete |
| \li About Troll Print 1.0 - marked "(obs.)", obsolete |
| \li Troll Print 1.0. Copyright 1999 Software, Inc. - |
| marked obsolete |
| \li Troll Print 1.1 - automatically translated as |
| "Troll Imprimir 1.1" |
| \li About Troll Print 1.1 - automatically translated as |
| "Troll Imprimir 1.1" |
| \li Troll Print 1.1. Copyright 1999-2000 Software, |
| Inc. - automatically translated as "Troll Imprimir 1.1. |
| Copyright 1999-2000 Software, Inc." |
| \endlist |
| \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 |
| |
| 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 \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 |
| |
| 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 |
| */ |