From d796c9dd933ab96ec83b9a634feedd5d32e1ba3f Mon Sep 17 00:00:00 2001 From: Timothy Pearson Date: Tue, 8 Nov 2011 12:31:36 -0600 Subject: Test conversion to TQt3 from Qt3 8c6fc1f8e35fd264dd01c582ca5e7549b32ab731 --- doc/html/i18n.html | 570 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 570 insertions(+) create mode 100644 doc/html/i18n.html (limited to 'doc/html/i18n.html') diff --git a/doc/html/i18n.html b/doc/html/i18n.html new file mode 100644 index 000000000..51772b7f0 --- /dev/null +++ b/doc/html/i18n.html @@ -0,0 +1,570 @@ + + + + + +Internationalization with TQt + + + + + + + +
+ +Home + | +All Classes + | +Main Classes + | +Annotated + | +Grouped Classes + | +Functions +

Internationalization with TQt

+ + +

+

The internationalization of an application is the process of making +the application usable by people in countries other than one's own. +

+

+ + +

In some cases internationalization is simple, for example, making a US +application accessible to Australian or British users may retquire +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 retquire that the software operate not only in +different languages, but use different input techniques, character +encodings and presentation conventions. +

TQt tries to make internationalization as painless as possible for +developers. All input widgets and text drawing methods in TQt 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. +

TQt supports most languages in use today, in particular: +

+

On Windows NT/2000/XP and Unix/X11 with Xft (client side font support) +the following languages are also supported: +

+

Many of these writing systems exhibit special features: +

+

TQt 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 +TQt's input widgets (e.g. TQLineEdit, TQTextEdit, and derived classes) +and TQt's display widgets (e.g. TQLabel). +

Support for these writing systems is transparent to the programmer +and completely encapsulated in TQt'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: +

+

The following sections give some information on the status +of the internationalization (i18n) support in TQt. +

See also the TQt Linguist manual. +

Step by Step +

+

Writing multi-platform international software with TQt is a gentle, +incremental process. Your software can become internationalized in +the following stages: +

Use TQString for all User-visible Text +

+

Since TQString uses the Unicode encoding internally, every +language in the world can be processed transparently using +familiar text processing operations. Also, since all TQt +functions that present text to the user take a TQString as a +parameter, there is no char* to TQString conversion overhead. +

Strings that are in "programmer space" (such as TQObject names +and file format texts) need not use TQString; the traditional +char* or the TQCString class will suffice. +

You're unlikely to notice that you are using Unicode; +TQString, and TQChar are just like easier versions of the crude +const char* and char from traditional C. +

Use tr() for all Literal Text +

+

Wherever your program uses "quoted text" for text that will +be presented to the user, ensure that it is processed by the TQApplication::translate() function. Essentially all that is necessary +to achieve this is to use TQObject::tr(). For example, assuming the +LoginWidget is a subclass of TQWidget: +

+    LoginWidget::LoginWidget()
+    {
+        TQLabel *label = new TQLabel( tr("Password:"), this );
+        ...
+    }
+
+ +

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 +TQObject subclass, use either the tr() function of an +appropriate class, or the TQApplication::translate() function +directly: +

+    void some_global_function( LoginWidget *logwid )
+    {
+        TQLabel *label = new TQLabel(
+                LoginWidget::tr("Password:"), logwid );
+    }
+
+    void same_global_function( LoginWidget *logwid )
+    {
+        TQLabel *label = new TQLabel(
+                qApp->translate("LoginWidget", "Password:"),
+                logwid );
+    }
+
+ +

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 lupdate utility described below. +The macros expand to just the text (without the context). +

Example of QT_TR_NOOP(): +

+    TQString FriendlyConversation::greeting( int greet_type )
+    {
+        static const char* greeting_strings[] = {
+            QT_TR_NOOP( "Hello" ),
+            QT_TR_NOOP( "Goodbye" )
+        };
+        return tr( greeting_strings[greet_type] );
+    }
+
+ +

Example of QT_TRANSLATE_NOOP(): +

+    static const char* greeting_strings[] = {
+        QT_TRANSLATE_NOOP( "FriendlyConversation", "Hello" ),
+        QT_TRANSLATE_NOOP( "FriendlyConversation", "Goodbye" )
+    };
+
+    TQString FriendlyConversation::greeting( int greet_type )
+    {
+        return tr( greeting_strings[greet_type] );
+    }
+
+    TQString global_greeting( int greet_type )
+    {
+        return qApp->translate( "FriendlyConversation",
+                                greeting_strings[greet_type] );
+    }
+
+ +

If you disable the const char* to TQString 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 TQString::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 TQObject::trUtf8() more convenient than +TQObject::tr(), as tr() depends on the +TQApplication::defaultCodec(), which makes it more fragile than +TQObject::trUtf8(). +

Use TQKeySequence() for Accelerator Values +

+

Accelerator values such as Ctrl+Q or Alt+F need to be +translated too. If you hardcode CTRL+Key_Q for "Quit" in +your application, translators won't be able to override +it. The correct idiom is +

+    TQPopupMenu *file = new TQPopupMenu( this );
+    file->insertItem( tr("&Quit"), this, SLOT(tquit()),
+                      TQKeySequence(tr("Ctrl+Q", "File|Quit")) );
+
+ +

Use TQString::arg() for Dynamic Text +

+

The TQString::arg() functions offer a simple means for substituting +arguments: +

+    void FileCopier::showProgress( int done, int total,
+                                   const TQString& current_file )
+    {
+        label.setText( tr("%1 of %2 files copied.\nCopying: %3")
+                        .arg(done)
+                        .arg(total)
+                        .arg(current_file) );
+    }
+
+ +

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: +

+    TQString s1 = "%1 of %2 files copied. Copying: %3";
+    TQString 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() );
+
+ +

produces the correct output in English and Norwegian: +

+5 of 10 files copied. Copying: somefile.txt
+Kopierer nu somefile.txt. Av totalt 10 filer er 5 kopiert.
+
+ +

Produce Translations +

+

Once you are using tr() throughout an application, you can start +producing translations of the user-visible text in your program. +

TQt Linguist's manual provides +further information about TQt's translation tools, TQt Linguist, lupdate and lrelease. +

Translation of a TQt application is a three-step process: +

    +

  1. Run lupdate to extract translatable text from the C++ source +code of the TQt application, resulting in a message file for +translators (a .ts file). The utility recognizes the tr() construct +and the QT_*_NOOP macros described above and produces .ts files +(usually one per language). +

  2. Provide translations for the source texts in the .ts file, using +TQt Linguist. Since .ts files are in XML format, you can also +edit them by hand. +

  3. Run lrelease to obtain a light-weight message file (a .qm +file) from the .ts file, suitable only for end use. Think of the .ts files as "source files", and .qm files as "object files". The +translator edits the .ts files, but the users of your application +only need the .qm files. Both kinds of files are platform and +locale independent. +

+

Typically, you will repeat these steps for every release of your +application. The lupdate utility does its best to reuse the +translations from previous releases. +

Before you run lupdate, you should prepare a project file. Here's +an example project file (.pro file): +

+    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
+
+ +

When you run lupdate or 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 qmake, you usually don't need an extra project +file for lupdate; your qmake project file will work fine once +you add the TRANSLATIONS entry. +

In your application, you must TQTranslator::load() the translation +files appropriate for the user's language, and install them using TQApplication::installTranslator(). +

If you have been using the old TQt tools (findtr, msg2qm and mergetr), you can use qm2ts to convert your old .qm files. +

linguist, lupdate and lrelease are installed in the bin +subdirectory of the base directory TQt is installed into. Click Help|Manual +in TQt Linguist to access the user's manual; it contains a tutorial +to get you started. +

While these utilities offer a convenient way to create .qm files, +any system that writes .qm files is sufficient. You could make an +application that adds translations to a TQTranslator with +TQTranslator::insert() and then writes a .qm file with +TQTranslator::save(). This way the translations can come from any +source you choose. +

+TQt 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 $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: +

+    int main( int argc, char **argv )
+    {
+        TQApplication app( argc, argv );
+
+        // translation file for TQt
+        TQTranslator qt( 0 );
+        qt.load( TQString( "qt_" ) + TQTextCodec::locale(), "." );
+        app.installTranslator( &qt );
+
+        // translation file for application strings
+        TQTranslator myapp( 0 );
+        myapp.load( TQString( "myapp_" ) + TQTextCodec::locale(), "." );
+        app.installTranslator( &myapp );
+
+        ...
+
+        return app.exec();
+    }
+
+ +

Support for Encodings +

+

The TQTextCodec class and the facilities in TQTextStream 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 retquire 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: +

+    TQString string = ...; // some Unicode text
+
+    TQTextCodec* codec = TQTextCodec::codecForName( "ISO 8859-5" );
+    TQCString encoded_string = codec->fromUnicode( string );
+
+    ...; // use encoded_string in 8-bit operations
+
+ +

For converting Unicode to local 8-bit encodings, a shortcut is +available: the local8Bit() method +of TQString returns such 8-bit data. Another useful shortcut is the +utf8() 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 TQString::fromUtf8() and +TQString::fromLocal8Bit() convenience functions, or the general code, +demonstrated by this conversion from ISO 8859-5 Cyrillic to Unicode +conversion: +

+    TQCString encoded_string = ...; // Some ISO 8859-5 encoded text.
+
+    TQTextCodec* codec = TQTextCodec::codecForName("ISO 8859-5");
+    TQString string = codec->toUnicode(encoded_string);
+
+    ...; // Use string in all of TQt's TQString operations.
+
+ +

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 TQTextCodec::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()). +

TQt supports most of the more frequently used encodings natively. For a +complete list of supported encodings see the TQTextCodec +documentation. +

In some cases and for less frequently used encodings it may be +necessary to write your own TQTextCodec subclass. Depending on the +urgency, it may be useful to contact Trolltech technical support or +ask on the 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 TQTextCodec::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 TQTextCodec, see the main TQTextCodec class +documentation. +

+

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. +

+    void Clock::setTime(const TQTime& t)
+    {
+        if ( tr("AMPM") == "AMPM" ) {
+            // 12-hour clock
+        } else {
+            // 24-hour clock
+        }
+    }
+
+ +

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. +

Dynamic Translation +

+

Some applications, such as TQt 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 languageChange() in each widget that needs to be notified. +In this slot, you should update the text displayed by widgets using the +TQObject::tr(){tr()} function in the usual way; for example: +

+void MyWidget::languageChange()
+{
+    titleLabel->setText(tr("Document Title"));
+    ...
+    okPushButton->setText(tr("&OK"));
+}
+
+ +

The default event handler for TQWidget subclasses responds to the +LanguageChange event, and will call this slot +when necessary; other application components can also connect signals +to this slot to force widgets to update themselves. +

System Support +

+

Some of the operating systems and windowing systems that TQt runs on +only have limited support for Unicode. The level of support available +in the underlying system has some influence on the support that TQt can +provide on those platforms, although in general TQt applications need +not be too concerned with platform-specific limitations. +

Unix/X11 +

+

+

Windows +

+

+

Note about Locales on X11 +

+

Many Unix distributions contain only partial support for some locales. +For example, if you have a /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 /usr/share/locale/ja_JP.EUC directory needs to be complete. For best +results, use complete locales from your system vendor. +

Relevant TQt Classes +

+

These classes are relevant to internationalizing TQt applications. + +

+
TQBig5CodecConversion to and from the Big5 encoding +
TQEucJpCodecConversion to and from EUC-JP character sets +
TQEucKrCodecConversion to and from EUC-KR character sets +
TQGb18030CodecConversion to and from the Chinese GB18030/GBK/GB2312 encoding +
TQGb2312CodecConversion to and from the Chinese GB2312 encoding +
TQGbkCodecConversion to and from the Chinese GBK encoding +
TQHebrewCodecConversion to and from visually ordered Hebrew +
TQJisCodecConversion to and from JIS character sets +
TQSjisCodecConversion to and from Shift-JIS +
TQTextCodecConversion between text encodings +
TQTextDecoderState-based decoder +
TQTextEncoderState-based encoder +
TQTranslatorInternationalization support for text output +
TQTranslatorMessageTranslator message and its properties +
TQTsciiCodecConversion to and from the Tamil TSCII encoding +
+ +

+ +
Copyright © 2007 +TrolltechTrademarks +
TQt 3.3.8
+
+ -- cgit v1.2.1