Skip to content
GitLab
Commit edb4f6fa authored by Leena Miettinen's avatar Leena Miettinen Committed by The Qt Project
Browse files

Doc: remove details about i18n from Qt Linguist Manual 


Add links to topics that describe i18n in detail for
C++ and QML.

Change-Id: I47b95b040dd9efe4eb8951dedbf94ab8988316e5
Reviewed-by: default avatarOswald Buddenhagen <oswald.buddenhagen@digia.com>
parent 027b8f89
No related merge requests found
Hide whitespace changes
Inline Side-by-side
Showing
with 47 additions and 308 deletions
src/linguist/linguist/doc/snippets/doc_src_linguist-manual.cpp
+ 0
− 114
View file @ edb4f6fa
...@@ -41,117 +41,3 @@ ...@@ -41,117 +41,3 @@
//! [3] //! [3]
label->setText(tr("F\374r \310lise")); label->setText(tr("F\374r \310lise"));
//! [3] //! [3]
void wrapInFunction()
{
//! [6]
button = new QPushButton("&Quit", this);
//! [6]
//! [7]
button = new QPushButton(tr("&Quit"), this);
//! [7]
//! [8]
QPushButton::tr("&Quit")
//! [8]
//! [9]
QObject::tr("&Quit")
//! [9]
//! [10]
rbc = new QRadioButton(tr("Enabled", "Color frame"), this);
//! [10]
//! [11]
rbh = new QRadioButton(tr("Enabled", "Hue frame"), this);
//! [11]
}
//! [12]
/*
TRANSLATOR FindDialog
Choose Edit|Find from the menu bar or press Ctrl+F to pop up the
Find dialog.
...
*/
//! [12]
//! [13]
/*
TRANSLATOR MyNamespace::MyClass
Necessary for lupdate.
...
*/
//! [13]
//! [14]
void some_global_function(LoginWidget *logwid)
{
QLabel *label = new QLabel(
LoginWidget::tr("Password:"), logwid);
}
void same_global_function(LoginWidget *logwid)
{
QLabel *label = new QLabel(
qApp->translate("LoginWidget", "Password:"),
logwid);
}
//! [14]
//! [15]
QString FriendlyConversation::greeting(int greet_type)
{
static const char* greeting_strings[] = {
QT_TR_NOOP("Hello"),
QT_TR_NOOP("Goodbye")
};
return tr(greeting_strings[greet_type]);
}
//! [15]
//! [16]
static const char* greeting_strings[] = {
QT_TRANSLATE_NOOP("FriendlyConversation", "Hello"),
QT_TRANSLATE_NOOP("FriendlyConversation", "Goodbye")
};
QString FriendlyConversation::greeting(int greet_type)
{
return tr(greeting_strings[greet_type]);
}
QString global_greeting(int greet_type)
{
return qApp->translate("FriendlyConversation",
greeting_strings[greet_type]);
}
//! [16]
void wrapInFunction()
{
//! [17]
QString tr(const char *text, const char *comment, int n);
//! [17]
//! [18]
tr("%n item(s) replaced", "", count);
//! [18]
}
src/linguist/linguist/doc/src/linguist-manual.qdoc
+ 47
− 194
View file @ edb4f6fa
...@@ -867,229 +867,82 @@ ...@@ -867,229 +867,82 @@
with Qt, but requires a certain amount of developer intervention and with Qt, but requires a certain amount of developer intervention and
will of course incur some runtime performance cost. will of course incur some runtime performance cost.
\section1 Making the Application Translation-Aware \section1 Internationalizing Applications
Developers should make their application look for and load the Design your application so that it can be adapted to various languages and
appropriate translation file and mark user-visible text and Ctrl regions without engineering changes. Qt tries to make internationalization
keyboard accelerators as targets for translation. as painless as possible for you. All input controls and text drawing methods
in Qt offer built-in support for all supported languages. But you still need
Each piece of text that requires translating requires context to help to keep the following things in mind when writing source code for your
the translator identify where in the program the text occurs. In the application:
case of multiple identical texts that require different translations,
the translator also requires some information to disambiguate the
source texts. Marking text for translation will automatically cause
the class name to be used as basic context information. In some cases
the developer may be required to add additional information to help
the translator.
You can develop applications that use both C++ and QML sources in the same
application and even have user interface strings in both sources. The tools
create a single combined translation file and the strings are accessible
from C++ and QML. The following sections describe how to make C++ sources
translatable. For more information about making QML sources translatable, see
\l{Internationalization and Localization with Qt Quick}.
\section2 Loading Translations
\snippet hellotr/main.cpp 1
\snippet hellotr/main.cpp 3
This is how a simple \c main() function of a Qt application begins.
\snippet hellotr/main.cpp 1
\snippet hellotr/main.cpp 4
For a translation-aware application a translator object is created, a
translation is loaded and the translator object installed into the
application.
\snippet arrowpad/main.cpp 0
\snippet arrowpad/main.cpp 1
In production applications a more flexible approach, for example,
loading translations according to locale, might be more appropriate. If
the TS files are all named according to a convention such as
\e appname_locale, for example \c tt2_fr, \c tt2_de, and so on, then the
code above will load the current locale's translation at runtime.
If there is no translation file for the current locale the application
will fall back to using the original source text.
Note that if you need to programmatically add translations at
runtime, you can reimplement QTranslator::translate().
\section2 Making the Application Translate User-Visible Strings
User-visible strings are marked as translation targets by wrapping them
in a \c tr() call, for example:
\snippet doc_src_linguist-manual.cpp 6
would become
\snippet doc_src_linguist-manual.cpp 7
All QObject subclasses that use the \c Q_OBJECT macro implement
the \c tr() function.
Although the \c tr() call is normally made directly since it is
usually called as a member function of a QObject subclass, in
other cases an explicit class name can be supplied, for example:
\snippet doc_src_linguist-manual.cpp 8
or
\snippet doc_src_linguist-manual.cpp 9
\section2 Distinguishing Between Identical Translatable Strings
The lupdate tool automatically
provides a \e context for every source text. This context is the class
name of the class that contains the \c tr() call. This is sufficient in
the vast majority of cases. Sometimes however, the translator will need
further information to uniquely identify a source text; for example,
a dialog that contained two separate frames, each of which contained an
"Enabled" option would need each identified because in some languages the
translation would differ between the two. This is easily achieved using the
two argument form of the \c tr() call.
For example:
\snippet doc_src_linguist-manual.cpp 10
and
\snippet doc_src_linguist-manual.cpp 11
Ctrl key accelerators are also translatable:
\snippet trollprint/mainwindow.cpp 2
It is strongly recommended that the two argument form of \c tr() is used
for Ctrl key accelerators. The second argument is the only clue the
translator has as to the function performed by the accelerator.
\section2 Helping the Translator with Navigation Information
In large complex applications it may be difficult for the translator to
see where a particular source text comes from. This problem can be
solved by adding a comment using the keyword \e TRANSLATOR which
describes the navigation steps to reach the text in question.
For example:
\snippet doc_src_linguist-manual.cpp 12
These comments are particularly useful for widget classes.
\section2 Handling Plural Forms
Qt includes a \c tr() overload that will make it very easy to
write "plural-aware" internationalized applications. This overload
has the following signature:
\snippet doc_src_linguist-manual.cpp 17
Depending on the value of \c n, the \c tr() function will return a different
translation, with the correct grammatical number for the target language.
Also, any occurrence of \c %n is replaced with \c{n}'s value. For example:
\snippet doc_src_linguist-manual.cpp 18
If a French translation is loaded, this will expand to "0 item
remplac\unicode{233}", "1 item remplac\unicode{233}", "2 items
remplac\unicode{233}s", and so on, depending on \c{n}'s value.
And if no translation is loaded, the original string is used, with \c %n
replaced with count's value (for example, "6 item(s) replaced").
To handle plural forms in the native language, you need to load a
translation file for this language, too.
The lupdate tool has the
\c -pluralonly command line option, which allows the creation of
TS files containing only entries with plural forms.
See the \l{Qt Quarterly} Article
\l{http://doc.qt.digia.com/qq/qq19-plurals.html}{Plural Forms in Translations}
for further details on this issue.
\section2 Coping With C++ Namespaces
C++ namespaces and the \c {using namespace} statement can confuse \list
lupdate. It will interpret
\c MyClass::tr() as meaning just that, not as
\c MyNamespace::MyClass::tr(), even if \c MyClass is
defined in the \c MyNamespace namespace. Runtime translation of
these strings will fail because of that.
You can work around this limitation by putting a \e TRANSLATOR \li Make your application look for and load the appropriate translation
comment at the beginning of the source files that use \c file.
MyClass::tr():
\snippet doc_src_linguist-manual.cpp 13 \li Mark user-visible text and Ctrl keyboard accelerators as targets for
translation.
After the comment, all references to \c MyClass::tr() will be \li Provide context for text to be translated.
understood as meaning \c MyNamespace::MyClass::tr().
\section2 Translating Text That is Outside of a QObject Subclass \li Disambiguate identical texts.
\section3 Using QCoreApplication::translate() \li Use numbered arguments (%n) as placeholders for parameters that are
replaced with text or numbers at run-time.
If the quoted text is not in a member function of a QObject subclass, \li Internationalize numbers, dates, times, and currencies.
use either the tr() function of an appropriate class, or the
QCoreApplication::translate() function directly:
\snippet doc_src_linguist-manual.cpp 14 \li Mark data text strings outside functions translatable.
\section3 Using QT_TR_NOOP() and QT_TRANSLATE_NOOP() \endlist
If you need to have translatable text completely outside a function, You can develop applications that use both C++ and QML sources in the same
there are two macros to help: QT_TR_NOOP() and QT_TRANSLATE_NOOP(). application and even have user interface strings in both sources. The tools
These macros merely mark the text for extraction by create a single combined translation file and the strings are accessible
lupdate. from C++ and QML.
The macros expand to just the text (without the context).
Example of QT_TR_NOOP(): The classes that support internationalizing of Qt applications are described
\snippet doc_src_linguist-manual.cpp 15 in \l{Internationalization with Qt}. The process of making source code
translatable is described in \l{Writing Source Code for Translation} and in
\l{Internationalization and Localization with Qt Quick}.
Example of QT_TRANSLATE_NOOP(): Each piece of text that requires translating requires context to help
\snippet doc_src_linguist-manual.cpp 16 the translator identify where in the program the text appears. In the
case of multiple identical texts that require different translations,
the translator also requires some information to disambiguate the
source texts. Marking text for translation will automatically cause
the class name to be used as basic context information. In some cases
the developer may be required to add additional information to help
the translator.
\section1 Tutorials \section1 Tutorials
Three tutorials are presented: The following tutorials illustrate how to prepare Qt applications for
translation:
\list 1 \list
\li \l{hellotr}{Hello tr()} demonstrates the creation of \li \l{hellotr}{Hello tr()} is a C++ application that demonstrates the
a \l QTranslator object. It also shows the simplest use of creation of a \l QTranslator object. It also shows the simplest use of
the \c tr() function to mark user-visible source text for the \c tr() function to mark user-visible source text for
translation. translation.
\li \l{arrowpad}{Arrow Pad} explains how to make the application load the \li \l{arrowpad}{Arrow Pad} is a C++ application that demonstrates how to
make the application load the
translation file applicable to the current locale. It also shows the translation file applicable to the current locale. It also shows the
use of the two-argument form of \c tr() which provides additional use of the two-argument form of \c tr() which provides additional
information to the translator. information to the translator.
\li \l{trollprint}{Troll Print} explains how \li \l{trollprint}{Troll Print} is a C++ application that demonstrates how
identical source texts can be distinguished even when they occur in identical source texts can be distinguished even when they occur in
the same context. This tutorial also discusses how the translation the same context. This tutorial also discusses how the translation
tools help minimize the translator's work when an application is tools help minimize the translator's work when an application is
upgraded. upgraded.
\endlist
These tutorials cover all that you need to know to prepare your Qt
applications for translation.
At the beginning of a project add the translation source files to be \li \l{QML Examples - Internationalization}{Internationalization} is a
used to the project file and add calls to Qt Quick application that demonstrates how to internationalize Qt Quick
lupdate and lrelease to the Makefile. applications.
\endlist
During the project all the developer must do is wrap any user-visible
text in \c tr() calls. They should also use the two argument form for
Ctrl key accelerators, or when asked by the translator for the cases
where the same text translates into two different forms in the same
context. The developer should also include \c TRANSLATION comments to
help the translator navigate the application.
*/ */
/*! /*!
......
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment