You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
594 lines
22 KiB
594 lines
22 KiB
/****************************************************************************
|
|
**
|
|
** Explanation of moc and the meta object system
|
|
**
|
|
** Copyright (C) 1992-2008 Trolltech ASA. All rights reserved.
|
|
**
|
|
** This file is part of the Qt GUI Toolkit.
|
|
**
|
|
** This file may be used under the terms of the GNU General
|
|
** Public License versions 2.0 or 3.0 as published by the Free
|
|
** Software Foundation and appearing in the files LICENSE.GPL2
|
|
** and LICENSE.GPL3 included in the packaging of this file.
|
|
** Alternatively you may (at your option) use any later version
|
|
** of the GNU General Public License if such license has been
|
|
** publicly approved by Trolltech ASA (or its successors, if any)
|
|
** and the KDE Free Qt Foundation.
|
|
**
|
|
** Please review the following information to ensure GNU General
|
|
** Public Licensing requirements will be met:
|
|
** http://trolltech.com/products/qt/licenses/licensing/opensource/.
|
|
** If you are unsure which license is appropriate for your use, please
|
|
** review the following information:
|
|
** http://trolltech.com/products/qt/licenses/licensing/licensingoverview
|
|
** or contact the sales department at sales@trolltech.com.
|
|
**
|
|
** This file may be used under the terms of the Q Public License as
|
|
** defined by Trolltech ASA and appearing in the file LICENSE.QPL
|
|
** included in the packaging of this file. Licensees holding valid Qt
|
|
** Commercial licenses may use this file in accordance with the Qt
|
|
** Commercial License Agreement provided with the Software.
|
|
**
|
|
** This file is provided "AS IS" with NO WARRANTY OF ANY KIND,
|
|
** INCLUDING THE WARRANTIES OF DESIGN, MERCHANTABILITY AND FITNESS FOR
|
|
** A PARTICULAR PURPOSE. Trolltech reserves all rights not granted
|
|
** herein.
|
|
**
|
|
**********************************************************************/
|
|
|
|
/*! \defgroup i18n
|
|
|
|
\title Internationalization with Qt
|
|
|
|
\keyword internationalization
|
|
\keyword i18n
|
|
|
|
The internationalization of an application is the process of making
|
|
the application usable by people in countries other than one's own.
|
|
|
|
\tableofcontents
|
|
|
|
In some cases internationalization is simple, for example, making a US
|
|
application accessible to Australian or British users may require
|
|
little more than a few spelling corrections. But to make a US
|
|
application usable by Japanese users, or a Korean application usable
|
|
by German users, will require that the software operate not only in
|
|
different languages, but use different input techniques, character
|
|
encodings and presentation conventions.
|
|
|
|
Qt tries to make internationalization as painless as possible for
|
|
developers. All input widgets and text drawing methods in Qt offer
|
|
built-in support for all supported languages. The built-in font engine
|
|
is capable of correctly and attractively rendering text that contains
|
|
characters from a variety of different writing systems at the same
|
|
time.
|
|
|
|
Qt supports most languages in use today, in particular:
|
|
\list
|
|
\i All East Asian languages (Chinese, Japanese and Korean)
|
|
\i All Western languages (using Latin script)
|
|
\i Arabic
|
|
\i Cyrillic languages (Russian)
|
|
\i Greek
|
|
\i Hebrew
|
|
\i Thai and Lao
|
|
\i All scripts in Unicode 3.2 that do not require special processing
|
|
\endlist
|
|
|
|
On Windows NT/2000/XP and Unix/X11 with Xft (client side font support)
|
|
the following languages are also supported:
|
|
\list
|
|
\i Bengali
|
|
\i Devanagari
|
|
\i Dhivehi (Thaana)
|
|
\i Gujarati
|
|
\i Gurmukhi
|
|
\i Kannada
|
|
\i Khmer
|
|
\i Malayalam (X11 only)
|
|
\i Myanmar (X11 only)
|
|
\i Syriac
|
|
\i Tamil
|
|
\i Telugu
|
|
\i Tibetan (X11 only)
|
|
\endlist
|
|
|
|
Many of these writing systems exhibit special features:
|
|
|
|
\list
|
|
|
|
\i <b>Special line breaking behavior.</b> Some of the Asian languages are
|
|
written without spaces between words. Line breaking can occur either
|
|
after every character (with exceptions) as in Chinese, Japanese and
|
|
Korean, or after logical word boundaries as in Thai.
|
|
|
|
\i <b>Bidirectional writing.</b> Arabic and Hebrew are written from right to
|
|
left, except for numbers and embedded English text which is written
|
|
left to right. The exact behavior is defined in the \link
|
|
http://www.unicode.org/unicode/reports/tr9/ Unicode Technical Report
|
|
#9 \endlink.
|
|
|
|
\i <b>Non spacing or diacritical marks</b> (accents or umlauts in European
|
|
languages). Some languages such as Vietnamese make extensive use of
|
|
these marks and some characters can have more than one mark at the
|
|
same time to clarify pronunciation.
|
|
|
|
\i <b>Ligatures.</b> In special contexts, some pairs of characters get
|
|
replaced by a combined glyph forming a ligature. Common examples are
|
|
the fl and fi ligatures used in typesetting US and European books.
|
|
|
|
\endlist
|
|
|
|
Qt tries to take care of all the special features listed above. You
|
|
usually don't have to worry about these features so long as you use
|
|
Qt's input widgets (e.g. QLineEdit, QTextEdit, and derived classes)
|
|
and Qt's display widgets (e.g. QLabel).
|
|
|
|
Support for these writing systems is transparent to the programmer
|
|
and completely encapsulated in Qt's text engine. This means that you
|
|
don't need to have any knowledge about the writing system used in a
|
|
particular language, except for the following small points:
|
|
\list
|
|
|
|
\i QPainter::drawText( int x, int y, const QString &str ) will always
|
|
draw the string with it's left edge at the position specified with
|
|
the x, y parameters. This will usually give you left aligned strings.
|
|
Arabic and Hebrew application strings are usually right
|
|
aligned, so for these languages use the version of drawText() that
|
|
takes a QRect since this will align in accordance with the language.
|
|
|
|
\i When you write your own text input controls, use \l
|
|
QFontMetrics::charWidth() to determine the width of a character in a
|
|
string. In some languages (e.g. Arabic or languages from the Indian
|
|
subcontinent), the width and shape of a glyph changes depending on the
|
|
surrounding characters. Writing input controls usually requires a
|
|
certain knowledge of the scripts it is going to be used in. Usually
|
|
the easiest way is to subclass QLineEdit or QTextEdit.
|
|
|
|
\endlist
|
|
|
|
The following sections give some information on the status
|
|
of the internationalization (i18n) support in Qt.
|
|
|
|
See also the \link linguist-manual.book Qt Linguist\endlink manual.
|
|
|
|
\section1 Step by Step
|
|
|
|
Writing multi-platform international software with Qt is a gentle,
|
|
incremental process. Your software can become internationalized in
|
|
the following stages:
|
|
|
|
\section2 Use QString for all User-visible Text
|
|
|
|
Since QString uses the Unicode encoding internally, every
|
|
language in the world can be processed transparently using
|
|
familiar text processing operations. Also, since all Qt
|
|
functions that present text to the user take a QString as a
|
|
parameter, there is no char* to QString conversion overhead.
|
|
|
|
Strings that are in "programmer space" (such as QObject names
|
|
and file format texts) need not use QString; the traditional
|
|
char* or the QCString class will suffice.
|
|
|
|
You're unlikely to notice that you are using Unicode;
|
|
QString, and QChar are just like easier versions of the crude
|
|
const char* and char from traditional C.
|
|
|
|
\section2 Use tr() for all Literal Text
|
|
|
|
Wherever your program uses \c{"quoted text"} for text that will
|
|
be presented to the user, ensure that it is processed by the \l
|
|
QApplication::translate() function. Essentially all that is necessary
|
|
to achieve this is to use \l QObject::tr(). For example, assuming the
|
|
\c LoginWidget is a subclass of QWidget:
|
|
|
|
\code
|
|
LoginWidget::LoginWidget()
|
|
{
|
|
QLabel *label = new QLabel( tr("Password:"), this );
|
|
...
|
|
}
|
|
\endcode
|
|
|
|
This accounts for 99% of the user-visible strings you're likely to
|
|
write.
|
|
|
|
If the quoted text is not in a member function of a
|
|
QObject subclass, use either the tr() function of an
|
|
appropriate class, or the QApplication::translate() function
|
|
directly:
|
|
|
|
\code
|
|
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 );
|
|
}
|
|
\endcode
|
|
|
|
If you need to have translatable text completely
|
|
outside a function, there are two macros to help: QT_TR_NOOP()
|
|
and QT_TRANSLATE_NOOP(). They merely mark the text for
|
|
extraction by the \e lupdate utility described below.
|
|
The macros expand to just the text (without the context).
|
|
|
|
Example of QT_TR_NOOP():
|
|
\code
|
|
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] );
|
|
}
|
|
\endcode
|
|
|
|
Example of QT_TRANSLATE_NOOP():
|
|
\code
|
|
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] );
|
|
}
|
|
\endcode
|
|
|
|
If you disable the const char* to QString automatic conversion
|
|
by compiling your software with the macro QT_NO_CAST_ASCII
|
|
defined, you'll be very likely to catch any strings you are
|
|
missing. See QString::fromLatin1() for more information.
|
|
Disabling the conversion can make programming a bit cumbersome.
|
|
|
|
If your source language uses characters outside Latin-1, you
|
|
might find QObject::trUtf8() more convenient than
|
|
QObject::tr(), as tr() depends on the
|
|
QApplication::defaultCodec(), which makes it more fragile than
|
|
QObject::trUtf8().
|
|
|
|
\section2 Use QKeySequence() for Accelerator Values
|
|
|
|
Accelerator values such as Ctrl+Q or Alt+F need to be
|
|
translated too. If you hardcode \c CTRL+Key_Q for "Quit" in
|
|
your application, translators won't be able to override
|
|
it. The correct idiom is
|
|
|
|
\code
|
|
QPopupMenu *file = new QPopupMenu( this );
|
|
file->insertItem( tr("&Quit"), this, SLOT(quit()),
|
|
QKeySequence(tr("Ctrl+Q", "File|Quit")) );
|
|
\endcode
|
|
|
|
\section2 Use QString::arg() for Dynamic Text
|
|
|
|
The QString::arg() functions offer a simple means for substituting
|
|
arguments:
|
|
\code
|
|
void FileCopier::showProgress( int done, int total,
|
|
const QString& current_file )
|
|
{
|
|
label.setText( tr("%1 of %2 files copied.\nCopying: %3")
|
|
.arg(done)
|
|
.arg(total)
|
|
.arg(current_file) );
|
|
}
|
|
\endcode
|
|
|
|
In some languages the order of arguments may need to change, and this
|
|
can easily be achieved by changing the order of the % arguments. For
|
|
example:
|
|
\code
|
|
QString s1 = "%1 of %2 files copied. Copying: %3";
|
|
QString s2 = "Kopierer nu %3. Av totalt %2 filer er %1 kopiert.";
|
|
|
|
qDebug( s1.arg(5).arg(10).arg("somefile.txt").ascii() );
|
|
qDebug( s2.arg(5).arg(10).arg("somefile.txt").ascii() );
|
|
\endcode
|
|
|
|
produces the correct output in English and Norwegian:
|
|
\code
|
|
5 of 10 files copied. Copying: somefile.txt
|
|
Kopierer nu somefile.txt. Av totalt 10 filer er 5 kopiert.
|
|
\endcode
|
|
|
|
\section2 Produce Translations
|
|
|
|
Once you are using tr() throughout an application, you can start
|
|
producing translations of the user-visible text in your program.
|
|
|
|
\link linguist-manual.book Qt Linguist\endlink's manual provides
|
|
further information about Qt's translation tools, \e{Qt Linguist}, \e
|
|
lupdate and \e lrelease.
|
|
|
|
Translation of a Qt application is a three-step process:
|
|
|
|
\list 1
|
|
|
|
\i Run \e lupdate to extract translatable text from the C++ source
|
|
code of the Qt application, resulting in a message file for
|
|
translators (a \c .ts file). The utility recognizes the tr() construct
|
|
and the QT_*_NOOP macros described above and produces \c .ts files
|
|
(usually one per language).
|
|
|
|
\i Provide translations for the source texts in the \c .ts file, using
|
|
\e{Qt Linguist}. Since \c .ts files are in XML format, you can also
|
|
edit them by hand.
|
|
|
|
\i Run \e lrelease to obtain a light-weight message file (a \c .qm
|
|
file) from the \c .ts file, suitable only for end use. Think of the \c
|
|
.ts files as "source files", and \c .qm files as "object files". The
|
|
translator edits the \c .ts files, but the users of your application
|
|
only need the \c .qm files. Both kinds of files are platform and
|
|
locale independent.
|
|
|
|
\endlist
|
|
|
|
Typically, you will repeat these steps for every release of your
|
|
application. The \e lupdate utility does its best to reuse the
|
|
translations from previous releases.
|
|
|
|
Before you run \e lupdate, you should prepare a project file. Here's
|
|
an example project file (\c .pro file):
|
|
|
|
\code
|
|
HEADERS = funnydialog.h \
|
|
wackywidget.h
|
|
SOURCES = funnydialog.cpp \
|
|
main.cpp \
|
|
wackywidget.cpp
|
|
FORMS = fancybox.ui
|
|
TRANSLATIONS = superapp_dk.ts \
|
|
superapp_fi.ts \
|
|
superapp_no.ts \
|
|
superapp_se.ts
|
|
\endcode
|
|
|
|
When you run \e lupdate or \e lrelease, you must give the name of the
|
|
project file as a command-line argument.
|
|
|
|
In this example, four exotic languages are supported: Danish, Finnish,
|
|
Norwegian and Swedish. If you use \link qmake-manual.book
|
|
qmake\endlink, you usually don't need an extra project
|
|
file for \e lupdate; your \c qmake project file will work fine once
|
|
you add the \c TRANSLATIONS entry.
|
|
|
|
In your application, you must \l QTranslator::load() the translation
|
|
files appropriate for the user's language, and install them using \l
|
|
QApplication::installTranslator().
|
|
|
|
If you have been using the old Qt tools (\c findtr, \c msg2qm and \c
|
|
mergetr), you can use \e qm2ts to convert your old \c .qm files.
|
|
|
|
\e linguist, \e lupdate and \e lrelease are installed in the \c bin
|
|
subdirectory of the base directory Qt is installed into. Click Help|Manual
|
|
in \e{Qt Linguist} to access the user's manual; it contains a tutorial
|
|
to get you started.
|
|
|
|
While these utilities offer a convenient way to create \c .qm files,
|
|
any system that writes \c .qm files is sufficient. You could make an
|
|
application that adds translations to a QTranslator with
|
|
QTranslator::insert() and then writes a \c .qm file with
|
|
QTranslator::save(). This way the translations can come from any
|
|
source you choose.
|
|
|
|
\target qt-itself
|
|
Qt itself contains over 400 strings that will also need to be
|
|
translated into the languages that you are targeting. You will find
|
|
translation files for French and German in \c $QTDIR/translations as
|
|
well as a template for translating to other languages. (This directory
|
|
also contains some additional unsupported translations which may be
|
|
useful.)
|
|
|
|
Typically, your application's main() function will look like this:
|
|
\code
|
|
int main( int argc, char **argv )
|
|
{
|
|
QApplication app( argc, argv );
|
|
|
|
// translation file for Qt
|
|
QTranslator qt( 0 );
|
|
qt.load( QString( "qt_" ) + QTextCodec::locale(), "." );
|
|
app.installTranslator( &qt );
|
|
|
|
// translation file for application strings
|
|
QTranslator myapp( 0 );
|
|
myapp.load( QString( "myapp_" ) + QTextCodec::locale(), "." );
|
|
app.installTranslator( &myapp );
|
|
|
|
...
|
|
|
|
return app.exec();
|
|
}
|
|
\endcode
|
|
|
|
\section2 Support for Encodings
|
|
|
|
The QTextCodec class and the facilities in QTextStream make it easy to
|
|
support many input and output encodings for your users' data. When an
|
|
application starts, the locale of the machine will determine the 8-bit
|
|
encoding used when dealing with 8-bit data: such as for font
|
|
selection, text display, 8-bit text I/O and character input.
|
|
|
|
The application may occasionally require encodings other than the
|
|
default local 8-bit encoding. For example, an application in a
|
|
Cyrillic KOI8-R locale (the de-facto standard locale in Russia) might
|
|
need to output Cyrillic in the ISO 8859-5 encoding. Code for this
|
|
would be:
|
|
|
|
\code
|
|
QString string = ...; // some Unicode text
|
|
|
|
QTextCodec* codec = QTextCodec::codecForName( "ISO 8859-5" );
|
|
QCString encoded_string = codec->fromUnicode( string );
|
|
|
|
...; // use encoded_string in 8-bit operations
|
|
\endcode
|
|
|
|
For converting Unicode to local 8-bit encodings, a shortcut is
|
|
available: the \link QString::local8Bit() local8Bit\endlink() method
|
|
of QString returns such 8-bit data. Another useful shortcut is the
|
|
\link QString::utf8() utf8\endlink() method, which returns text in the
|
|
8-bit UTF-8 encoding: this perfectly preserves Unicode information
|
|
while looking like plain US-ASCII if the text is wholly US-ASCII.
|
|
|
|
For converting the other way, there are the QString::fromUtf8() and
|
|
QString::fromLocal8Bit() convenience functions, or the general code,
|
|
demonstrated by this conversion from ISO 8859-5 Cyrillic to Unicode
|
|
conversion:
|
|
|
|
\code
|
|
QCString encoded_string = ...; // Some ISO 8859-5 encoded text.
|
|
|
|
QTextCodec* codec = QTextCodec::codecForName("ISO 8859-5");
|
|
QString string = codec->toUnicode(encoded_string);
|
|
|
|
...; // Use string in all of Qt's QString operations.
|
|
\endcode
|
|
|
|
Ideally Unicode I/O should be used as this maximizes the portability
|
|
of documents between users around the world, but in reality it is
|
|
useful to support all the appropriate encodings that your users will
|
|
need to process existing documents. In general, Unicode (UTF-16 or
|
|
UTF-8) is best for information transferred between arbitrary people,
|
|
while within a language or national group, a local standard is often
|
|
more appropriate. The most important encoding to support is the one
|
|
returned by QTextCodec::codecForLocale(), as this is the one the user
|
|
is most likely to need for communicating with other people and
|
|
applications (this is the codec used by local8Bit()).
|
|
|
|
Qt supports most of the more frequently used encodings natively. For a
|
|
complete list of supported encodings see the \l QTextCodec
|
|
documentation.
|
|
|
|
In some cases and for less frequently used encodings it may be
|
|
necessary to write your own QTextCodec subclass. Depending on the
|
|
urgency, it may be useful to contact Trolltech technical support or
|
|
ask on the \c qt-interest mailing list to see if someone else is
|
|
already working on supporting the encoding. A useful interim measure
|
|
can be to use the QTextCodec::loadCharmapFile() function to build a
|
|
data-driven codec, although this approach has a memory and speed
|
|
penalty, especially with dynamically loaded libraries. For details of
|
|
writing your own QTextCodec, see the main QTextCodec class
|
|
documentation.
|
|
|
|
\keyword localization
|
|
|
|
\section2 Localize
|
|
|
|
Localization is the process of adapting to local conventions, for
|
|
example presenting dates and times using the locally preferred
|
|
formats. Such localizations can be accomplished using appropriate tr()
|
|
strings.
|
|
|
|
\code
|
|
void Clock::setTime(const QTime& t)
|
|
{
|
|
if ( tr("AMPM") == "AMPM" ) {
|
|
// 12-hour clock
|
|
} else {
|
|
// 24-hour clock
|
|
}
|
|
}
|
|
\endcode
|
|
|
|
In the example, for the US we would leave the translation of "AMPM" as
|
|
it is and thereby use the 12-hour clock branch; but in Europe we would
|
|
translate it as something else (anything else, e.g. "EU") and this
|
|
will make the code use the 24-hour clock branch.
|
|
|
|
Localizing images is not recommended. Choose clear icons that are
|
|
appropriate for all localities, rather than relying on local puns or
|
|
stretched metaphors.
|
|
|
|
\section1 Dynamic Translation
|
|
|
|
Some applications, such as Qt Linguist, must be able to support changes
|
|
to the user's language settings while they are still running. To make
|
|
widgets aware of changes to the system language, implement a public
|
|
slot called \c languageChange() in each widget that needs to be notified.
|
|
In this slot, you should update the text displayed by widgets using the
|
|
\l{QObject::tr()}{tr()} function in the usual way; for example:
|
|
|
|
\code
|
|
void MyWidget::languageChange()
|
|
{
|
|
titleLabel->setText(tr("Document Title"));
|
|
...
|
|
okPushButton->setText(tr("&OK"));
|
|
}
|
|
\endcode
|
|
|
|
The default event handler for QWidget subclasses responds to the
|
|
\link QEvent::Type LanguageChange\endlink event, and will call this slot
|
|
when necessary; other application components can also connect signals
|
|
to this slot to force widgets to update themselves.
|
|
|
|
\section1 System Support
|
|
|
|
Some of the operating systems and windowing systems that Qt runs on
|
|
only have limited support for Unicode. The level of support available
|
|
in the underlying system has some influence on the support that Qt can
|
|
provide on those platforms, although in general Qt applications need
|
|
not be too concerned with platform-specific limitations.
|
|
|
|
\section2 Unix/X11
|
|
|
|
\list
|
|
\i Locale-oriented fonts and input methods. Qt hides these and
|
|
provides Unicode input and output.
|
|
\i Filesystem conventions such as
|
|
\link http://www.ietf.org/rfc/rfc2279.txt UTF-8 \endlink
|
|
are under development
|
|
in some Unix variants. All Qt file functions allow Unicode,
|
|
but convert filenames to the local 8-bit encoding, as
|
|
this is the Unix convention
|
|
(see QFile::setEncodingFunction()
|
|
to explore alternative encodings).
|
|
\i File I/O defaults to the local 8-bit encoding,
|
|
with Unicode options in QTextStream.
|
|
\endlist
|
|
|
|
\section2 Windows
|
|
|
|
\list
|
|
\i Qt provides full Unicode support, including input methods, fonts,
|
|
clipboard, drag-and-drop and file names.
|
|
\i File I/O defaults to Latin-1, with Unicode options in QTextStream.
|
|
Note that some Windows programs do not understand big-endian
|
|
Unicode text files even though that is the order prescribed by
|
|
the Unicode Standard in the absence of higher-level protocols.
|
|
\i Unlike programs written with MFC or plain winlib, Qt programs
|
|
are portable between Windows 95/98 and Windows NT.
|
|
\e {You do not need different binaries to support Unicode.}
|
|
\endlist
|
|
|
|
\section1 Note about Locales on X11
|
|
|
|
Many Unix distributions contain only partial support for some locales.
|
|
For example, if you have a \c /usr/share/locale/ja_JP.EUC directory,
|
|
this does not necessarily mean you can display Japanese text; you also
|
|
need JIS encoded fonts (or Unicode fonts), and the \c
|
|
/usr/share/locale/ja_JP.EUC directory needs to be complete. For best
|
|
results, use complete locales from your system vendor.
|
|
|
|
\section1 Relevant Qt Classes
|
|
|
|
These classes are relevant to internationalizing Qt applications.
|
|
*/
|