| /**************************************************************************** |
| ** |
| ** 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 hellotr |
| \ingroup examples-linguist |
| \title Hello tr() Example |
| |
| \brief Translating a small Hello World program to Latin. |
| |
| The screenshot shows the English version. |
| |
| \image linguist-hellotr_en.png |
| |
| See the \l{Qt Linguist Manual} for more information about |
| translating Qt application. |
| |
| \section1 Line by Line Walkthrough |
| |
| |
| \snippet hellotr/main.cpp 0 |
| |
| This line includes the definition of the QTranslator class. |
| Objects of this class provide translations for user-visible text. |
| |
| \snippet hellotr/main.cpp 5 |
| |
| Creates a QTranslator object without a parent. |
| |
| \snippet hellotr/main.cpp 6 |
| |
| Tries to load a file called \c hellotr_la.qm (the \c .qm file extension is |
| implicit) that contains Latin translations for the source texts used in |
| the program. No error will occur if the file is not found. |
| |
| \snippet hellotr/main.cpp 7 |
| |
| Adds the translations from \c hellotr_la.qm to the pool of translations used |
| by the program. |
| |
| \snippet hellotr/main.cpp 8 |
| |
| Creates a push button that displays "Hello world!". If \c hellotr_la.qm |
| was found and contains a translation for "Hello world!", the |
| translation appears; if not, the source text appears. |
| |
| All classes that inherit QObject have a \c tr() function. Inside |
| a member function of a QObject class, we simply write \c tr("Hello |
| world!") instead of \c QPushButton::tr("Hello world!") or \c |
| QObject::tr("Hello world!"). |
| |
| \section1 Running the Application in English |
| |
| Since we haven't made the translation file \c hellotr_la.qm, the source text |
| is shown when we run the application: |
| |
| \image linguist-hellotr_en.png |
| |
| \section1 Creating a Latin Message File |
| |
| The first step is to create a project file, \c hellotr.pro, that lists |
| all the source files for the project. The project file can be a qmake |
| project file, or even an ordinary makefile. Any file that contains |
| |
| \snippet hellotr/hellotr.pro 0 |
| \snippet hellotr/hellotr.pro 1 |
| |
| will work. \c TRANSLATIONS specifies the message files we want to |
| maintain. In this example, we just maintain one set of translations, |
| namely Latin. |
| |
| Note that the file extension is \c .ts, not \c .qm. The \c .ts |
| translation source format is designed for use during the |
| application's development. Programmers or release managers run |
| the \c lupdate program to generate and update TS files with |
| the source text that is extracted from the source code. |
| Translators read and update the TS files using \e {Qt |
| Linguist} adding and editing their translations. |
| |
| The TS format is human-readable XML that can be emailed directly |
| and is easy to put under version control. If you edit this file |
| manually, be aware that the default encoding for XML is UTF-8, not |
| Latin1 (ISO 8859-1). One way to type in a Latin1 character such as |
| '\oslash' (Norwegian o with slash) is to use an XML entity: |
| "\ø". This will work for any Unicode 4.0 character. |
| |
| Once the translations are complete the \c lrelease program is used to |
| convert the TS files into the QM Qt message file format. The |
| QM format is a compact binary format designed to deliver very |
| fast lookup performance. Both \c lupdate and \c lrelease read all the |
| project's source and header files (as specified in the HEADERS and |
| SOURCES lines of the project file) and extract the strings that |
| appear in \c tr() function calls. |
| |
| \c lupdate is used to create and update the message files (\c hellotr_la.ts |
| in this case) to keep them in sync with the source code. It is safe to |
| run \c lupdate at any time, as \c lupdate does not remove any |
| information. For example, you can put it in the makefile, so the TS |
| files are updated whenever the source changes. |
| |
| Try running \c lupdate right now, like this: |
| |
| \snippet doc/snippets/doc_src_examples_hellotr.qdoc 0 |
| |
| (The \c -verbose option instructs \c lupdate to display messages that |
| explain what it is doing.) You should now have a file \c hellotr_la.ts in |
| the current directory, containing this: |
| |
| \snippet doc/snippets/doc_src_examples_hellotr.qdoc 1 |
| |
| You don't need to understand the file format since it is read and |
| updated using tools (\c lupdate, \e {Qt Linguist}, \c lrelease). |
| |
| \section1 Translating to Latin with Qt Linguist |
| |
| We will use \e {Qt Linguist} to provide the translation, although |
| you can use any XML or plain text editor to enter a translation into a |
| TS file. |
| |
| To start \e {Qt Linguist}, type |
| |
| \snippet doc/snippets/doc_src_examples_hellotr.qdoc 2 |
| |
| You should now see the text "QPushButton" in the top left pane. |
| Double-click it, then click on "Hello world!" and enter "Orbis, te |
| saluto!" in the \uicontrol Translation pane (the middle right of the |
| window). Don't forget the exclamation mark! |
| |
| Click the \uicontrol Done checkbox and choose \uicontrol File|Save from the |
| menu bar. The TS file will no longer contain |
| |
| \snippet doc/snippets/doc_src_examples_hellotr.qdoc 3 |
| |
| but instead will have |
| |
| \snippet doc/snippets/doc_src_examples_hellotr.qdoc 4 |
| |
| \section1 Running the Application in Latin |
| |
| To see the application running in Latin, we have to generate a QM |
| file from the TS file. Generating a QM file can be achieved |
| either from within \e {Qt Linguist} (for a single TS file), or |
| by using the command line program \c lrelease which will produce one |
| QM file for each of the TS files listed in the project file. |
| Generate \c hellotr_la.qm from \c hellotr_la.ts by choosing |
| \uicontrol File|Release from \e {Qt Linguist}'s menu bar and pressing |
| \uicontrol Save in the file save dialog that pops up. Now run the \c hellotr |
| program again. This time the button will be labelled "Orbis, te |
| saluto!". |
| |
| \image linguist-hellotr_la.png |
| */ |