| /**************************************************************************** |
| ** |
| ** 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 arrowpad |
| \title Arrow Pad Example |
| \ingroup examples-linguist |
| \brief Understanding the Qt Linguist \e contexts concept and using two |
| or more languages. |
| |
| \image linguist-arrowpad_en.png |
| |
| We will use two translations, French and Dutch, although there is no |
| effective limit on the number of possible translations that can be used |
| with an application. The relevant lines of \c arrowpad.pro are |
| |
| \snippet arrowpad/arrowpad.pro 0 |
| \codeline |
| \snippet arrowpad/arrowpad.pro 1 |
| |
| Run \c lupdate; it should produce two identical message files |
| \c arrowpad_fr.ts and \c arrowpad_nl.ts. These files will contain all the source |
| texts marked for translation with \c tr() calls and their contexts. |
| |
| See the \l{Qt Linguist Manual} for more information about |
| translating Qt application. |
| |
| \section1 Line by Line Walkthrough |
| |
| In \c arrowpad.h we define the \c ArrowPad subclass which is a |
| subclass of QWidget. In the screenshot above, the central |
| widget with the four buttons is an \c ArrowPad. |
| |
| \snippet arrowpad/arrowpad.h 0 |
| \snippet arrowpad/arrowpad.h 1 |
| \snippet arrowpad/arrowpad.h 2 |
| |
| When \c lupdate is run it not only extracts the source texts but it |
| also groups them into contexts. A context is the name of the class in |
| which the source text appears. Thus, in this example, "ArrowPad" is a |
| context: it is the context of the texts in the \c ArrowPad class. |
| The \c Q_OBJECT macro defines \c tr(x) in \c ArrowPad like this: |
| |
| \snippet doc/snippets/doc_src_examples_arrowpad.cpp 0 |
| |
| Knowing which class each source text appears in enables \e {Qt |
| Linguist} to group texts that are logically related together, e.g. |
| all the text in a dialog will have the context of the dialog's class |
| name and will be shown together. This provides useful information for |
| the translator since the context in which text appears may influence how |
| it should be translated. For some translations keyboard |
| accelerators may need to be changed and having all the source texts in a |
| particular context (class) grouped together makes it easier for the |
| translator to perform any accelerator changes without introducing |
| conflicts. |
| |
| In \c arrowpad.cpp we implement the \c ArrowPad class. |
| |
| \snippet arrowpad/arrowpad.cpp 0 |
| \snippet arrowpad/arrowpad.cpp 1 |
| \snippet arrowpad/arrowpad.cpp 2 |
| \snippet arrowpad/arrowpad.cpp 3 |
| |
| We call \c ArrowPad::tr() for each button's label since the labels are |
| user-visible text. |
| |
| \image linguist-arrowpad_en.png |
| |
| \snippet arrowpad/mainwindow.h 0 |
| \snippet arrowpad/mainwindow.h 1 |
| |
| In the screenshot above, the whole window is a \c MainWindow. |
| This is defined in the \c mainwindow.h header file. Here too, we |
| use \c Q_OBJECT, so that \c MainWindow will become a context in |
| \e {Qt Linguist}. |
| |
| \snippet arrowpad/mainwindow.cpp 0 |
| |
| In the implementation of \c MainWindow, \c mainwindow.cpp, we create |
| an instance of our \c ArrowPad class. |
| |
| \snippet arrowpad/mainwindow.cpp 1 |
| |
| We also call \c MainWindow::tr() twice, once for the action and |
| once for the shortcut. |
| |
| Note the use of \c tr() to support different keys in other |
| languages. "Ctrl+Q" is a good choice for Quit in English, but a |
| Dutch translator might want to use "Ctrl+A" (for Afsluiten) and a |
| German translator "Strg+E" (for Beenden). When using \c tr() for |
| \uicontrol Ctrl key accelerators, the two argument form should be used |
| with the second argument describing the function that the |
| accelerator performs. |
| |
| Our \c main() function is defined in \c main.cpp as usual. |
| |
| \snippet arrowpad/main.cpp 2 |
| \snippet arrowpad/main.cpp 3 |
| |
| We choose which translation to use according to the current locale. |
| QLocale::system() can be influenced by setting the \c LANG |
| environment variable, for example. Notice that the use of a naming |
| convention that incorporates the locale for \c .qm message files, |
| (and TS files), makes it easy to implement choosing the |
| translation file according to locale. |
| |
| If there is no QM message file for the locale chosen the original |
| source text will be used and no error raised. |
| |
| \section1 Translating to French and Dutch |
| |
| We'll begin by translating the example application into French. Start |
| \e {Qt Linguist} with \c arrowpad_fr.ts. You should get the seven source |
| texts ("\&Up", "\&Left", etc.) grouped in two contexts ("ArrowPad" |
| and "MainWindow"). |
| |
| Now, enter the following translations: |
| |
| \list |
| \li \c ArrowPad |
| \list |
| \li \&Up - \&Haut |
| \li \&Left - \&Gauche |
| \li \&Right - \&Droite |
| \li \&Down - \&Bas |
| \endlist |
| \li \c MainWindow |
| \list |
| \li E\&xit - \&Quitter |
| \li Ctrl+Q - Ctrl+Q |
| \li \&File - \&Fichier |
| \endlist |
| \endlist |
| |
| It's quickest to press \uicontrol{Alt+D} (which clicks the \uicontrol {Done \& Next} |
| button) after typing each translation, since this marks the |
| translation as done and moves on to the next source text. |
| |
| Save the file and do the same for Dutch working with \c arrowpad_nl.ts: |
| |
| \list |
| \li \c ArrowPad |
| \list |
| \li \&Up - \&Omhoog |
| \li \&Left - \&Links |
| \li \&Right - \&Rechts |
| \li \&Down - Omlaa\&g |
| \endlist |
| \li \c MainWindow |
| \list |
| \li E\&xit - \&Afsluiten |
| \li Ctrl+Q - Ctrl+A |
| \li File - \&Bestand |
| \endlist |
| \endlist |
| |
| We have to convert the \c tt1_fr.ts and \c tt1_nl.ts translation source |
| files into QM files. We could use \e {Qt Linguist} as we've done |
| before; however using the command line tool \c lrelease ensures that |
| \e all the QM files for the application are created without us |
| having to remember to load and \uicontrol File|Release each one |
| individually from \e {Qt Linguist}. |
| |
| Type |
| |
| \snippet doc/snippets/doc_src_examples_arrowpad.qdoc 1 |
| |
| This should create both \c arrowpad_fr.qm and \c arrowpad_nl.qm. Set the \c |
| LANG environment variable to \c fr. In Unix, one of the two following |
| commands should work |
| |
| \snippet doc/snippets/doc_src_examples_arrowpad.qdoc 2 |
| |
| In Windows, either modify \c autoexec.bat or run |
| |
| \snippet doc/snippets/doc_src_examples_arrowpad.qdoc 3 |
| |
| When you run the program, you should now see the French version: |
| |
| \image linguist-arrowpad_fr.png |
| |
| Try the same with Dutch, by setting \c LANG=nl. Now the Dutch |
| version should appear: |
| |
| \image linguist-arrowpad_nl.png |
| |
| \section1 Exercises |
| |
| Mark one of the translations in \e {Qt Linguist} as not done, i.e. |
| by unchecking the "done" checkbox; run \c lupdate, then \c lrelease, |
| then the example. What effect did this change have? |
| |
| Set \c LANG=fr_CA (French Canada) and run the example program again. |
| Explain why the result is the same as with \c LANG=fr. |
| |
| Change one of the accelerators in the Dutch translation to eliminate the |
| conflict between \e \&Bestand and \e \&Boven. |
| */ |