From c886a12d103370d698d6b8f25941e247f0b1c5b3 Mon Sep 17 00:00:00 2001 From: Leena Miettinen Date: Fri, 30 Nov 2012 16:14:14 +0100 Subject: Doc: move Qt Linguist example docs from qtbase to qttools Move qdoc files, images, and snippets. Change-Id: I6ab84892dc56c23bfd056faa0713a572c814a1c2 Reviewed-by: Jerome Pasion --- .../linguist/doc/images/linguist-arrowpad_en.png | Bin 0 -> 1429 bytes .../linguist/doc/images/linguist-arrowpad_fr.png | Bin 0 -> 1671 bytes .../linguist/doc/images/linguist-arrowpad_nl.png | Bin 0 -> 1706 bytes .../linguist/doc/images/linguist-hellotr_en.png | Bin 0 -> 3367 bytes .../linguist/doc/images/linguist-hellotr_la.png | Bin 0 -> 753 bytes .../doc/images/linguist-trollprint_10_en.png | Bin 0 -> 1951 bytes .../doc/images/linguist-trollprint_10_pt_bad.png | Bin 0 -> 2073 bytes .../doc/images/linguist-trollprint_10_pt_good.png | Bin 0 -> 2120 bytes .../doc/images/linguist-trollprint_11_en.png | Bin 0 -> 2019 bytes .../doc/images/linguist-trollprint_11_pt.png | Bin 0 -> 2152 bytes .../doc/snippets/doc_src_examples_arrowpad.cpp | 43 ++++ .../doc/snippets/doc_src_examples_arrowpad.qdoc | 54 +++++ .../doc/snippets/doc_src_examples_hellotr.qdoc | 71 ++++++ .../doc/snippets/doc_src_examples_trollprint.cpp | 77 ++++++ examples/linguist/doc/src/arrowpad.qdoc | 223 ++++++++++++++++++ examples/linguist/doc/src/hellotr.qdoc | 174 ++++++++++++++ examples/linguist/doc/src/trollprint.qdoc | 261 +++++++++++++++++++++ 17 files changed, 903 insertions(+) create mode 100644 examples/linguist/doc/images/linguist-arrowpad_en.png create mode 100644 examples/linguist/doc/images/linguist-arrowpad_fr.png create mode 100644 examples/linguist/doc/images/linguist-arrowpad_nl.png create mode 100644 examples/linguist/doc/images/linguist-hellotr_en.png create mode 100644 examples/linguist/doc/images/linguist-hellotr_la.png create mode 100644 examples/linguist/doc/images/linguist-trollprint_10_en.png create mode 100644 examples/linguist/doc/images/linguist-trollprint_10_pt_bad.png create mode 100644 examples/linguist/doc/images/linguist-trollprint_10_pt_good.png create mode 100644 examples/linguist/doc/images/linguist-trollprint_11_en.png create mode 100644 examples/linguist/doc/images/linguist-trollprint_11_pt.png create mode 100644 examples/linguist/doc/snippets/doc_src_examples_arrowpad.cpp create mode 100644 examples/linguist/doc/snippets/doc_src_examples_arrowpad.qdoc create mode 100644 examples/linguist/doc/snippets/doc_src_examples_hellotr.qdoc create mode 100644 examples/linguist/doc/snippets/doc_src_examples_trollprint.cpp create mode 100644 examples/linguist/doc/src/arrowpad.qdoc create mode 100644 examples/linguist/doc/src/hellotr.qdoc create mode 100644 examples/linguist/doc/src/trollprint.qdoc (limited to 'examples/linguist') diff --git a/examples/linguist/doc/images/linguist-arrowpad_en.png b/examples/linguist/doc/images/linguist-arrowpad_en.png new file mode 100644 index 000000000..9a95eb24f Binary files /dev/null and b/examples/linguist/doc/images/linguist-arrowpad_en.png differ diff --git a/examples/linguist/doc/images/linguist-arrowpad_fr.png b/examples/linguist/doc/images/linguist-arrowpad_fr.png new file mode 100644 index 000000000..fc33f9fd7 Binary files /dev/null and b/examples/linguist/doc/images/linguist-arrowpad_fr.png differ diff --git a/examples/linguist/doc/images/linguist-arrowpad_nl.png b/examples/linguist/doc/images/linguist-arrowpad_nl.png new file mode 100644 index 000000000..f2645a81b Binary files /dev/null and b/examples/linguist/doc/images/linguist-arrowpad_nl.png differ diff --git a/examples/linguist/doc/images/linguist-hellotr_en.png b/examples/linguist/doc/images/linguist-hellotr_en.png new file mode 100644 index 000000000..6b3d8072c Binary files /dev/null and b/examples/linguist/doc/images/linguist-hellotr_en.png differ diff --git a/examples/linguist/doc/images/linguist-hellotr_la.png b/examples/linguist/doc/images/linguist-hellotr_la.png new file mode 100644 index 000000000..f1ecdb07a Binary files /dev/null and b/examples/linguist/doc/images/linguist-hellotr_la.png differ diff --git a/examples/linguist/doc/images/linguist-trollprint_10_en.png b/examples/linguist/doc/images/linguist-trollprint_10_en.png new file mode 100644 index 000000000..e460481f9 Binary files /dev/null and b/examples/linguist/doc/images/linguist-trollprint_10_en.png differ diff --git a/examples/linguist/doc/images/linguist-trollprint_10_pt_bad.png b/examples/linguist/doc/images/linguist-trollprint_10_pt_bad.png new file mode 100644 index 000000000..b96d47724 Binary files /dev/null and b/examples/linguist/doc/images/linguist-trollprint_10_pt_bad.png differ diff --git a/examples/linguist/doc/images/linguist-trollprint_10_pt_good.png b/examples/linguist/doc/images/linguist-trollprint_10_pt_good.png new file mode 100644 index 000000000..293c44a74 Binary files /dev/null and b/examples/linguist/doc/images/linguist-trollprint_10_pt_good.png differ diff --git a/examples/linguist/doc/images/linguist-trollprint_11_en.png b/examples/linguist/doc/images/linguist-trollprint_11_en.png new file mode 100644 index 000000000..f718c995c Binary files /dev/null and b/examples/linguist/doc/images/linguist-trollprint_11_en.png differ diff --git a/examples/linguist/doc/images/linguist-trollprint_11_pt.png b/examples/linguist/doc/images/linguist-trollprint_11_pt.png new file mode 100644 index 000000000..0ff8c399b Binary files /dev/null and b/examples/linguist/doc/images/linguist-trollprint_11_pt.png differ diff --git a/examples/linguist/doc/snippets/doc_src_examples_arrowpad.cpp b/examples/linguist/doc/snippets/doc_src_examples_arrowpad.cpp new file mode 100644 index 000000000..58e790d3a --- /dev/null +++ b/examples/linguist/doc/snippets/doc_src_examples_arrowpad.cpp @@ -0,0 +1,43 @@ +/**************************************************************************** +** +** 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Digia Plc and its Subsidiary(-ies) nor the names +** of its contributors may be used to endorse or promote products derived +** from this software without specific prior written permission. +** +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +qApp->translate("ArrowPad", x) +//! [0] diff --git a/examples/linguist/doc/snippets/doc_src_examples_arrowpad.qdoc b/examples/linguist/doc/snippets/doc_src_examples_arrowpad.qdoc new file mode 100644 index 000000000..4b3ea343a --- /dev/null +++ b/examples/linguist/doc/snippets/doc_src_examples_arrowpad.qdoc @@ -0,0 +1,54 @@ +/**************************************************************************** +** +** 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Digia Plc and its Subsidiary(-ies) nor the names +** of its contributors may be used to endorse or promote products derived +** from this software without specific prior written permission. +** +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [1] +lrelease arrowpad.pro +//! [1] + + +//! [2] +export LANG=fr +setenv LANG fr +//! [2] + + +//! [3] +set LANG=fr +//! [3] diff --git a/examples/linguist/doc/snippets/doc_src_examples_hellotr.qdoc b/examples/linguist/doc/snippets/doc_src_examples_hellotr.qdoc new file mode 100644 index 000000000..2e57cac8a --- /dev/null +++ b/examples/linguist/doc/snippets/doc_src_examples_hellotr.qdoc @@ -0,0 +1,71 @@ +/**************************************************************************** +** +** 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Digia Plc and its Subsidiary(-ies) nor the names +** of its contributors may be used to endorse or promote products derived +** from this software without specific prior written permission. +** +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +lupdate -verbose hellotr.pro +//! [0] + + +//! [1] + + + QPushButton + + Hello world! + + + + +//! [1] + + +//! [2] +linguist hellotr_la.ts +//! [2] + + +//! [3] + +//! [3] + + +//! [4] +Orbis, te saluto! +//! [4] diff --git a/examples/linguist/doc/snippets/doc_src_examples_trollprint.cpp b/examples/linguist/doc/snippets/doc_src_examples_trollprint.cpp new file mode 100644 index 000000000..493e245e8 --- /dev/null +++ b/examples/linguist/doc/snippets/doc_src_examples_trollprint.cpp @@ -0,0 +1,77 @@ +/**************************************************************************** +** +** 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Digia Plc and its Subsidiary(-ies) nor the names +** of its contributors may be used to endorse or promote products derived +** from this software without specific prior written permission. +** +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +twoSidedEnabledRadio = new QRadioButton(tr("Enabled", "two-sided")); +twoSidedDisabledRadio = new QRadioButton(tr("Disabled", "two-sided")); +//! [0] + + +//! [1] +colorsEnabledRadio = new QRadioButton(tr("Enabled", "colors"), colors); +colorsDisabledRadio = new QRadioButton(tr("Disabled", "colors"), colors); +//! [1] + + +//! [2] +/* + TRANSLATOR MainWindow + + In this application the whole application is a MainWindow. + Choose Help|About from the menu bar to see some text + belonging to MainWindow. + + ... +*/ +//! [2] + + +//! [3] +/* + TRANSLATOR ZClientErrorDialog + + Choose Client|Edit to reach the Client Edit dialog, then choose + Client Specification from the drop down list at the top and pick + client Bartel Leendert van der Waerden. Now check the Profile + checkbox and then click the Start Processing button. You should + now see a pop up window with the text "Error: Name too long!". + This window is a ZClientErrorDialog. +*/ +//! [3] diff --git a/examples/linguist/doc/src/arrowpad.qdoc b/examples/linguist/doc/src/arrowpad.qdoc new file mode 100644 index 000000000..4ba2e7d68 --- /dev/null +++ b/examples/linguist/doc/src/arrowpad.qdoc @@ -0,0 +1,223 @@ +/**************************************************************************** +** +** 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 arrowpad + \title Arrow Pad Example + + This example is a slightly more involved and introduces a key \e + {Qt Linguist} concept: "contexts". It also shows how to use two + or more languages. + + \image linguist-arrowpad_en.png + + We will use two translations, French and Dutch, although there is no + effective limit on the number of possible translations that can be used + with an application. The relevant lines of \c arrowpad.pro are + + \snippet arrowpad/arrowpad.pro 0 + \codeline + \snippet arrowpad/arrowpad.pro 1 + + Run \c lupdate; it should produce two identical message files + \c arrowpad_fr.ts and \c arrowpad_nl.ts. These files will contain all the source + texts marked for translation with \c tr() calls and their contexts. + + See the \l{Qt Linguist manual} for more information about + translating Qt application. + + \section1 Line by Line Walkthrough + + In \c arrowpad.h we define the \c ArrowPad subclass which is a + subclass of QWidget. In the screenshot above, the central + widget with the four buttons is an \c ArrowPad. + + \snippet arrowpad/arrowpad.h 0 + \snippet arrowpad/arrowpad.h 1 + \snippet arrowpad/arrowpad.h 2 + + When \c lupdate is run it not only extracts the source texts but it + also groups them into contexts. A context is the name of the class in + which the source text appears. Thus, in this example, "ArrowPad" is a + context: it is the context of the texts in the \c ArrowPad class. + The \c Q_OBJECT macro defines \c tr(x) in \c ArrowPad like this: + + \snippet doc/snippets/doc_src_examples_arrowpad.cpp 0 + + Knowing which class each source text appears in enables \e {Qt + Linguist} to group texts that are logically related together, e.g. + all the text in a dialog will have the context of the dialog's class + name and will be shown together. This provides useful information for + the translator since the context in which text appears may influence how + it should be translated. For some translations keyboard + accelerators may need to be changed and having all the source texts in a + particular context (class) grouped together makes it easier for the + translator to perform any accelerator changes without introducing + conflicts. + + In \c arrowpad.cpp we implement the \c ArrowPad class. + + \snippet arrowpad/arrowpad.cpp 0 + \snippet arrowpad/arrowpad.cpp 1 + \snippet arrowpad/arrowpad.cpp 2 + \snippet arrowpad/arrowpad.cpp 3 + + We call \c ArrowPad::tr() for each button's label since the labels are + user-visible text. + + \image linguist-arrowpad_en.png + + \snippet arrowpad/mainwindow.h 0 + \snippet arrowpad/mainwindow.h 1 + + In the screenshot above, the whole window is a \c MainWindow. + This is defined in the \c mainwindow.h header file. Here too, we + use \c Q_OBJECT, so that \c MainWindow will become a context in + \e {Qt Linguist}. + + \snippet arrowpad/mainwindow.cpp 0 + + In the implementation of \c MainWindow, \c mainwindow.cpp, we create + an instance of our \c ArrowPad class. + + \snippet arrowpad/mainwindow.cpp 1 + + We also call \c MainWindow::tr() twice, once for the action and + once for the shortcut. + + Note the use of \c tr() to support different keys in other + languages. "Ctrl+Q" is a good choice for Quit in English, but a + Dutch translator might want to use "Ctrl+A" (for Afsluiten) and a + German translator "Strg+E" (for Beenden). When using \c tr() for + \uicontrol Ctrl key accelerators, the two argument form should be used + with the second argument describing the function that the + accelerator performs. + + Our \c main() function is defined in \c main.cpp as usual. + + \snippet arrowpad/main.cpp 2 + \snippet arrowpad/main.cpp 3 + + We choose which translation to use according to the current locale. + QLocale::system() can be influenced by setting the \c LANG + environment variable, for example. Notice that the use of a naming + convention that incorporates the locale for \c .qm message files, + (and TS files), makes it easy to implement choosing the + translation file according to locale. + + If there is no QM message file for the locale chosen the original + source text will be used and no error raised. + + \section1 Translating to French and Dutch + + We'll begin by translating the example application into French. Start + \e {Qt Linguist} with \c arrowpad_fr.ts. You should get the seven source + texts ("\&Up", "\&Left", etc.) grouped in two contexts ("ArrowPad" + and "MainWindow"). + + Now, enter the following translations: + + \list + \li \c ArrowPad + \list + \li \&Up - \&Haut + \li \&Left - \&Gauche + \li \&Right - \&Droite + \li \&Down - \&Bas + \endlist + \li \c MainWindow + \list + \li E\&xit - \&Quitter + \li Ctrl+Q - Ctrl+Q + \li \&File - \&Fichier + \endlist + \endlist + + It's quickest to press \uicontrol{Alt+D} (which clicks the \uicontrol {Done \& Next} + button) after typing each translation, since this marks the + translation as done and moves on to the next source text. + + Save the file and do the same for Dutch working with \c arrowpad_nl.ts: + + \list + \li \c ArrowPad + \list + \li \&Up - \&Omhoog + \li \&Left - \&Links + \li \&Right - \&Rechts + \li \&Down - Omlaa\&g + \endlist + \li \c MainWindow + \list + \li E\&xit - \&Afsluiten + \li Ctrl+Q - Ctrl+A + \li File - \&Bestand + \endlist + \endlist + + We have to convert the \c tt1_fr.ts and \c tt1_nl.ts translation source + files into QM files. We could use \e {Qt Linguist} as we've done + before; however using the command line tool \c lrelease ensures that + \e all the QM files for the application are created without us + having to remember to load and \uicontrol File|Release each one + individually from \e {Qt Linguist}. + + Type + + \snippet doc/snippets/doc_src_examples_arrowpad.qdoc 1 + + This should create both \c arrowpad_fr.qm and \c arrowpad_nl.qm. Set the \c + LANG environment variable to \c fr. In Unix, one of the two following + commands should work + + \snippet doc/snippets/doc_src_examples_arrowpad.qdoc 2 + + In Windows, either modify \c autoexec.bat or run + + \snippet doc/snippets/doc_src_examples_arrowpad.qdoc 3 + + When you run the program, you should now see the French version: + + \image linguist-arrowpad_fr.png + + Try the same with Dutch, by setting \c LANG=nl. Now the Dutch + version should appear: + + \image linguist-arrowpad_nl.png + + \section1 Exercises + + Mark one of the translations in \e {Qt Linguist} as not done, i.e. + by unchecking the "done" checkbox; run \c lupdate, then \c lrelease, + then the example. What effect did this change have? + + Set \c LANG=fr_CA (French Canada) and run the example program again. + Explain why the result is the same as with \c LANG=fr. + + Change one of the accelerators in the Dutch translation to eliminate the + conflict between \e \&Bestand and \e \&Boven. +*/ diff --git a/examples/linguist/doc/src/hellotr.qdoc b/examples/linguist/doc/src/hellotr.qdoc new file mode 100644 index 000000000..9c459d979 --- /dev/null +++ b/examples/linguist/doc/src/hellotr.qdoc @@ -0,0 +1,174 @@ +/**************************************************************************** +** +** 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 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 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 +*/ diff --git a/examples/linguist/doc/src/trollprint.qdoc b/examples/linguist/doc/src/trollprint.qdoc new file mode 100644 index 000000000..92c2b3c70 --- /dev/null +++ b/examples/linguist/doc/src/trollprint.qdoc @@ -0,0 +1,261 @@ +/**************************************************************************** +** +** 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 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 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 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 trollprint/printpanel.cpp 1 + \snippet 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 trollprint/mainwindow.cpp 0 + + We must translate the window title. + + \snippet trollprint/mainwindow.cpp 1 + \snippet 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 trollprint/main.cpp 0 + + The \c main() function in \c main.cpp is the same as the one in + the \l{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/snippets/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/snippets/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/snippets/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/snippets/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 + "\TROLL PRINT\" 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 \TROLL PRINT\ - 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 "\TROLL PRINT\" as "\TROLL IMPRIMIR\". + 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 +*/ -- cgit v1.2.3