diff options
Diffstat (limited to 'doc/src/examples/hellotr.qdoc')
| -rw-r--r-- | doc/src/examples/hellotr.qdoc | 188 |
1 files changed, 188 insertions, 0 deletions
diff --git a/doc/src/examples/hellotr.qdoc b/doc/src/examples/hellotr.qdoc new file mode 100644 index 0000000000..72efd11732 --- /dev/null +++ b/doc/src/examples/hellotr.qdoc @@ -0,0 +1,188 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (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 either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** 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.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at qt-sales@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example linguist/hellotr + \title Hello tr() Example + + This example is a small Hello World program with a Latin translation. The + screenshot below 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 examples/linguist/hellotr/main.cpp 0 + + This line includes the definition of the QTranslator class. + Objects of this class provide translations for user-visible text. + + \snippet examples/linguist/hellotr/main.cpp 5 + + Creates a QTranslator object without a parent. + + \snippet examples/linguist/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 examples/linguist/hellotr/main.cpp 7 + + Adds the translations from \c hellotr_la.qm to the pool of translations used + by the program. + + \snippet examples/linguist/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 examples/linguist/hellotr/hellotr.pro 0 + \snippet examples/linguist/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 \c .ts files with + the source text that is extracted from the source code. + Translators read and update the \c .ts files using \e {Qt + Linguist} adding and editing their translations. + + The \c .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 \c .ts files into the \c .qm Qt message file format. The + \c .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 \c .ts + files are updated whenever the source changes. + + Try running \c lupdate right now, like this: + + \snippet doc/src/snippets/code/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/src/snippets/code/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 + \c .ts file. + + To start \e {Qt Linguist}, type + + \snippet doc/src/snippets/code/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 \gui Translation pane (the middle right of the + window). Don't forget the exclamation mark! + + Click the \gui Done checkbox and choose \gui File|Save from the + menu bar. The \c .ts file will no longer contain + + \snippet doc/src/snippets/code/doc_src_examples_hellotr.qdoc 3 + + but instead will have + + \snippet doc/src/snippets/code/doc_src_examples_hellotr.qdoc 4 + + \section1 Running the Application in Latin + + To see the application running in Latin, we have to generate a \c .qm + file from the \c .ts file. Generating a \c .qm file can be achieved + either from within \e {Qt Linguist} (for a single \c .ts file), or + by using the command line program \c lrelease which will produce one \c + .qm file for each of the \c .ts files listed in the project file. + Generate \c hellotr_la.qm from \c hellotr_la.ts by choosing + \gui File|Release from \e {Qt Linguist}'s menu bar and pressing + \gui 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 +*/ |