+++ /dev/null
-/****************************************************************************
-**
-** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies).
-** Contact: http://www.qt-project.org/legal
-**
-** 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 Digia. For licensing terms and
-** conditions see http://qt.digia.com/licensing. For further information
-** use the contact form at http://qt.digia.com/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: http://www.gnu.org/copyleft/fdl.html.
-** $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 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.cpp 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.cpp 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 \uicontrol {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.cpp 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 \uicontrol {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.cpp 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
- \li Uncomment the two lines that create a QLabel with the text
- "\<b\>TROLL PRINT\</b\>" in \c printpanel.cpp.
- \li Word-tidying: Replace "2-sided" by "Two-sided" in \c printpanel.cpp.
- \li Replace "1.0" with "1.1" everywhere it occurs in \c mainwindow.cpp.
- \li 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
- \li \c MainWindow
- \list
- \li Troll Print 1.0 - marked "(obs.)", obsolete
- \li About Troll Print 1.0 - marked "(obs.)", obsolete
- \li Troll Print 1.0. Copyright 1999 Software, Inc. -
- marked obsolete
- \li Troll Print 1.1 - automatically translated as
- "Troll Imprimir 1.1"
- \li About Troll Print 1.1 - automatically translated as
- "Troll Imprimir 1.1"
- \li Troll Print 1.1. Copyright 1999-2000 Software,
- Inc. - automatically translated as "Troll Imprimir 1.1.
- Copyright 1999-2000 Software, Inc."
- \endlist
- \li \c PrintPanel
- \list
- \li 2-sided - marked "(obs.)", obsolete
- \li \<b\>TROLL PRINT\</b\> - unmarked, i.e. untranslated
- \li 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 \uicontrol {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 \uicontrol{Ajuda|Sobre} (\uicontrol{Help|About}) to see the about box.
-
- If you choose \uicontrol {Ajuda|Sobre Qt} (\uicontrol {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
-*/
projects / profile / ivi / qtbase.git / commitdiff
