summaryrefslogtreecommitdiffstats
path: root/doc/src/examples/trollprint.qdoc
diff options
context:
space:
mode:
Diffstat (limited to 'doc/src/examples/trollprint.qdoc')
-rw-r--r--doc/src/examples/trollprint.qdoc275
1 files changed, 275 insertions, 0 deletions
diff --git a/doc/src/examples/trollprint.qdoc b/doc/src/examples/trollprint.qdoc
new file mode 100644
index 0000000..38251ee
--- /dev/null
+++ b/doc/src/examples/trollprint.qdoc
@@ -0,0 +1,275 @@
+/****************************************************************************
+**
+** 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/trollprint
+ \title Troll Print Example
+
+ 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 examples/linguist/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 examples/linguist/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 examples/linguist/trollprint/printpanel.cpp 1
+ \snippet examples/linguist/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 examples/linguist/trollprint/mainwindow.cpp 0
+
+ We must translate the window title.
+
+ \snippet examples/linguist/trollprint/mainwindow.cpp 1
+ \snippet examples/linguist/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 examples/linguist/trollprint/main.cpp 0
+
+ The \c main() function in \c main.cpp is the same as the one in
+ the \l{linguist/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 the 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/src/snippets/code/doc_src_examples_trollprint.qdoc 0
+
+ and add the second argument "colors" in the appropriate \c tr() calls
+ for the second pair of radio buttons:
+
+ \snippet doc/src/snippets/code/doc_src_examples_trollprint.qdoc 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 \gui {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/src/snippets/code/doc_src_examples_trollprint.qdoc 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 \gui {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/src/snippets/code/doc_src_examples_trollprint.qdoc 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
+ \o Uncomment the two lines that create a QLabel with the text
+ "\<b\>TROLL PRINT\</b\>" in \c printpanel.cpp.
+ \o Word-tidying: Replace "2-sided" by "Two-sided" in \c printpanel.cpp.
+ \o Replace "1.0" with "1.1" everywhere it occurs in \c mainwindow.cpp.
+ \o 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
+ \o \c MainWindow
+ \list
+ \o Troll Print 1.0 - marked "(obs.)", obsolete
+ \o About Troll Print 1.0 - marked "(obs.)", obsolete
+ \o Troll Print 1.0. Copyright 1999 Software, Inc. -
+ marked obsolete
+ \o Troll Print 1.1 - automatically translated as
+ "Troll Imprimir 1.1"
+ \o About Troll Print 1.1 - automatically translated as
+ "Troll Imprimir 1.1"
+ \o Troll Print 1.1. Copyright 1999-2000 Software,
+ Inc. - automatically translated as "Troll Imprimir 1.1.
+ Copyright 1999-2000 Software, Inc."
+ \endlist
+ \o \c PrintPanel
+ \list
+ \o 2-sided - marked "(obs.)", obsolete
+ \o \<b\>TROLL PRINT\</b\> - unmarked, i.e. untranslated
+ \o 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 \gui {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 \gui{Ajuda|Sobre} (\gui{Help|About}) to see the about box.
+
+ If you choose \gui {Ajuda|Sobre Qt} (\gui {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
+*/