Qtopia Home - Classes - Hierachy - Annotated - Functions - Licenses - Reference

Qtopia Internationalization

Introduction

Qtopia can be translated into several languages. By default Qtopia ships only with English. Additional languages can be acquired from Trolltech. For further information please contact sales@trolltech.com.

Internationalizing Qtopia software is much the same as internationalizing any Qt-based software. You should be familiar with the Qt internationalization documentation, the tr() macros, Qt Linguist from Qt 3.3 or later, and the internationalization process in general before you proceed with this document.

Note that since Qt 2 does not incorporate right-to-left writing support Qtopia (which is based on Qt 2) cannot be translated into any of the languages, such as Arabic and Hebrew, that require this feature.

Language Packages

Language-specific packages are available on request by contacting: sales@trolltech.com.

After becoming a Qtopia customer, Trolltech will create an FTP directory for each customer account.The user can log in to the FTP directory using any browser and download the language package(s).

Once the relevant language package is downloaded the steps are as follows:

  1. cd into the Qtopia directory installation directory - $QPEDIR.
  2. Extract the package using the following command:
       tar -xzf mypackage 
    

  3. Configure Qtopia as described in Building Qtopia.

Note: No special configuration options are required as the Qtopia build detects the new language files automatically.

If you are using an SDK and you don't have the convinience of the qtopia build system at hand you have to run lrelease manually for each ts file and put the resulting qm file into $QPEDIR/i18n/<yourlang>.

Translating Qtopia

Adding a translation for Qtopia is easy. There are a few steps you will need to take in order to successfully translate Qtopia into your chosen language.

  1. Install Qt 3.x, which includes linguist, lupdate and lrelease.
  2. Run lupdate and lrelease, and start using Trolltech's linguist
  3. Add language description
  4. Translate the strings using the Linguist tool
  5. Install translation files

To translate Qtopia into an additional language you must perform the translation process described above for all the application, desktop and config files, and any help documentation that you wish to have available in that language.

Install Qt 3

You can either install Qt 3 for X11 from your linux distribution, or download the Qt 3 source, and compile it yourself. Once installed, you should have linguist, lupdate and lrelease tools available for you to use.

Getting Started Translating

The first step is to tell Qtopia where Qt3 is installed. This is done by setting the environment variable DQTDIR to the location of your Qt3 directory. Not having set this variable will prevent that configure generates the necessary installation rules.

Qtopia ships without any translation files. If you want to generate translation files for your chosen language you have to reconfigure Qtopia:

$QPEDIR/configure -languages "ja fr zh_CN" <other configure options>

This will tell the build system that it has to build translation files for Japanese, French and Simplified Chinese.

The second step is to run the command make lupdate in the Qtopia ($QPEDIR) directory. This makes sure all the files necessary for translation exist and are up to date.

The make lupdate process generates translation files for each language specified via Qtopia's configure option languages. The general naming convention for these files is appname-<your-lang>.ts (e.g. sysinfo-zh_CN.ts).

As the last step the script $QPEDIR/bin/nct_lupdate is executed in order to generate translation files for those strings that cannot be found in source code. This includes most config and desktop files in the $QPEDIR directory. Each of these config/desktop files must have a Translation group similar to the following one which can be found in $QPEDIR/apps/Applications/clock.desktop:

[Translation]
File=QtopiaApplications
Context=Clock

This causes the generation of the file QtopiaApplications.ts in $QPEDIR/i18n/your-lang. Please read the build system page for more information about non-code translatable files.

Language description

Running the command make lupdate will create the directory $QPEDIR/i18n/new-lang and server specific translation files (e.g. QtopiaApplications.ts) which contains the translated names for Qtopia applications. In addition to these automatically generated files every language needs a .directory file. For example, the German .directory in $QPEDIR/i18n/de looks like this:

[Translation]
File=QtopiaI18N
Context=German
[Desktop Entry]
Name[]=German

This file has to be added manually before make lupdate has been executed or you will need to run make lupdate again. It contains the name of the language itself as it is presented to the user.

Translating Qtopia using Linguist

Linguist Manual

The next step is to run the linguist tool. Linguist makes it easy to work with translations. It supports incremental translation, which helps you keep track of any additional content that is added to Qtopia and needs translating.

Any strings that are ambiguous or otherwise unclear or suspect in some way should be translated to whatever degree it is possible, and then left in the unfinished state.

Installing translation files

The last step is to run the command make install in the Qtopia ($QPEDIR) directory. As part of this process lrelease is used to create Qt message files (.qm files).

Fonts

Qtopia uses Helvetica as the default font, however, this font does not specify the characters for languages such as Chinese.

The configuration file $QPEDIR/etc/default/FontMap.conf has to be translated so that the correct font family and size is used for each language. It defines the font which can be selected by users within Qtopia. If this configuration file is empty, Qtopia will use Helvetica font as the default font. Therefore, a valid FontMap.conf and QtopiaDefaults.ts file is required to suppress Helvetica as a selectable choice. The original FontMap.conf looks like this:

[Translation]
File=QtopiaDefaults
Context=FontMap
[Map]
Font0[]=small,helvetica,10
Font1[]=normal,helvetica,12
Font2[]=large,helvetica,14

Such a configuration will be suitable for most Western languages. The Map group defines three font settings that will be used by Qtopia, each of which have three parameters as follows:

  1. textual string that is presented to the user when a new setting is chosen
  2. font family specification
  3. font size.

This configuration file is marked for translation. When executing make lupdate the build system will create: $QPEDIR/i18n/your-lang/QtopiaDefaults.ts. Due to its special meaning, the string "small,helvetica,12" cannot be translated as a normal string, for example, a French translation may look like this:

<name>FontMap</name>
<message encoding="UTF-8">
        <source>Small,helvetica,10</source>
        <translation>Petit,unifont,11</translation>
</message>

As a result, Petit will be presented to the user and selecting this option will load the fontset unifont with a font size of 11. The chosen font has to support all characters of the given language.

Program Internationalization

When make install is executed the build system generates Qt message files (.qm files).

Placing Application Files

Application files must be placed as follows:

/opt/Qtopia/i18n/language/appname.qm

The language is an ISO 639 language code optionally followed by an underscore and an ISO 3166 territory. For example, "en", "en_GB", "ja", "ja_JP". The appname is the filename of the application executable.

Note that you should not need to manually place files into /opt/Qtopia as "make install" supports installing .qm files.

Placing Plug-in Files

For plug-ins that are shared libraries the files must be placed in the following directory:

/opt/Qtopia/i18n/language/pluginname.qm

The pluginname is the filename of the plug-in shared object minus any extensions, but including "lib" if the plug-in incorporates that prefix.

Locale suffixes are supported. For example, if your application uses British English it can have a /opt/Qtopia/i18n/en_US/appname.qm file specifying changes for American English. Translations with locale suffixes take precedence over translations without such suffixes.

Note that you should not need to manually place files into /opt/Qtopia as "make install" supports installing .qm files.

Desktop & Configuration File Internationalization

Desktop/Config files (eg. /opt/Qtopia/apps/Application/appname.desktop) can also be translated. For example, the texteditor.desktop file begins with:

[Translation]
File=QtopiaApplications
Context=Notes
[Desktop Entry]
Comment[]=A Text Editing Program
Exec=textedit
Icon=TextEditor
Type=Application
MimeType=text/*
Name[]=Notes

This causes the file /opt/Qtopia/i18n/language/QtopiaApplications.qm to be loaded (if it isn't already) and the strings marked with "[]" to be translated in the "Text Editor" context. Please read the build system page for more information about non-code translatable files.

These files are encoded in UTF-8.

Image Translation

User interfaces can contain language specific images which may require translations (e.g. a text editor may use an image with a capital letter B indicating a bold font type). Since Qtopia 2.2 the resource system supports the translation of pcitures. Using the above example an application could load an internationalized "bold" image via:

Resource::loadImage("app1/bold");

The resource system tries to find the picture for language e.g. en_GB using the following order:

A picture that requires a translation must be put into one of the i18n subfolders. American English (en_US) is used as a fall back mechanism in case there is no translation for the current language. Some pictures in e.g. Qtopia's pkim package use this mechanism.

Developers who wish to provide translations for their pictures have to ensure that they provide a translation for American English. Due to the lookup order of pictures the name must not exist in the application's picture directory nor in the global picture directory.

Documentation Internationalization

Online documentation for applications is written in the HTML subset supported by the Qt richtext widget. Such documentation files must be placed as follows:

English documentation:

/opt/Qtopia/help/html/appname-suffixes.html

Non-English documentation:

/opt/Qtopia/help/language/html/appname-suffixes.html

The -suffixes is optional. It always starts with "-" to avoid namespace conflicts.

These files are encoded in UTF-8.

For online help file information refer to: Help File Contents.

Other Internationalization Files

Other files that are language-specific are:

Translating Your Own Applications

Qtopia's build system makes it very easy to translate your own applications. The example application in $QPEDIR/examples/application summarizes what has to be done in order to generate .ts files. Further details on how to build and install additional Qtopia applications can be found in the build system help.


Copyright © 2005 Trolltech Trademarks
Qtopia version 2.2.0