--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/src/examples/hellotr.qdoc Thu Apr 08 14:19:33 2010 +0300
@@ -0,0 +1,188 @@
+/****************************************************************************
+**
+** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies).
+** All rights reserved.
+** Contact: Nokia Corporation (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 Technology Preview License Agreement accompanying
+** this package.
+**
+** 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.1, included in the file LGPL_EXCEPTION.txt in this package.
+**
+** If you have questions regarding the use of this file, please contact
+** Nokia at qt-info@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 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/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
+ 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 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 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
+ \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
+*/