Home · All Classes · Grouped Classes · Annotated · Functions

Internationalization

Introduction

Qtopia can be translated into several languages. By default Qtopia ships only with English. Additional language-specific packages are available for purchase. For further information please contact qt-sales@nokia.com.

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

Note: Qtopia ships without any translation files, later steps will show how to generate the translation files.

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. Add language description file
  2. Create initial version of translation files
  3. Translating strings using Linguist
  4. Install translation files
  5. Updating translation files

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

Language Directory and Language Description File

Create the directory $QPEDIR/i18n/<new-lang> for the new language, for example run:

    mkdir $QPEDIR/i18n/zh_CN

if you want to create translation files for Simplified Chinese

Every language needs a .directory file that serves as a description for the language itself. For example, the Simplified Chinese .directory in $QPEDIR/i18n/zh_CN may look like this:

    [Translation]
    File=QtopiaI18N
    Context=Simplified Chinese
    [Desktop Entry]
    Name[]=Simplified Chinese

A .directory file contains the untranslated (English) name of the language itself as it is presented to the user. To create a .directory run:

    cp $QPEDIR/i18n/en_US/.directory $QPEDIR/i18n/zh_CN/
    # edit the .directory file setting the correct value for  Context and Name[]
    vim $QPEDIR/i18n/zh_CN/.directory

Create Initial Version of Translation Files

After creating the .directory file above you need to run configure so that it is aware of the new langage. After that you can create the .ts files for all available languages by running:

    make lupdate

This will result in the following steps for all available languages.

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>. If this file already exists it will be updated without the loss of any existing content. The Desktop & Configuration File Internationalization section further down in this document explains how this information is used to translate settings file content.

For more information on build system related translation information please refer to the following guides:

Translating strings using Linguist

The next step is to run the linguist tool. Linguist makes it easy to work with translations. It supports incremental translation, which helps you to keep track of any additional content that is added to Qtopia and needs to be translated. Any strings that are ambiguous or otherwise unclear or suspect in some way, should be translated to whatever degree is possible and then left in the unfinished state.

For further information refer to : Linguist Manual

Install 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).

Updating Translation Files

Any time a User Visible string has changed run make lupdate to cause the recreation of the translation files. It is then a matter of editing the changed .ts files with linguist so that the correct text is shown for the new strings. The last step is the installation of the edited translation files by running make install.

Fonts

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

The configuration file $QPEDIR/etc/default/Trolltech/qpe.conf has to be translated so that the correct font family and size is used for each language. If this configuration file is not translated, Qtopia will use DejaVu as the default font. Therefore, valid qpe.conf and QtopiaDefaults.ts files are required to suppress DejaVu as the preferred choice. The qpe.conf looks like this:

    [Translation]
    File=QtopiaDefaults
    Context=QPE

    [Font]
    FontFamily[]=dejavu_sans_condensed
    FontSize[]=6.4

Such a configuration will be suitable for most Western languages. The Font group defines the font family and font size (in points) that will be used by Qtopia.

This configuration file is marked for translation. When executing make lupdate the build system will create: $QPEDIR/i18n/<your-lang>/QtopiaDefaults.ts. For example, a Korean translation may look like this:

    <name>QPE</name>
    <message>
        <source>dejavu_sans_condensed</source>
        <translation>unifont</translation>
    </message>
    <message>
        <source>6.4</source>
        <translation>13</translation>
    </message>

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 will 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"). 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.

The <appname> is the filename of the application executable.

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. New plug-ins should always be loaded via QPluginManager in order to ensure that the necessary translation files are loaded.

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. The "bin/nct_lupdate" script can be used to maintain .ts files from .desktop files.

All desktop files have to be encoded in UTF-8.

Image Translation

For certain applications it may be a requirement to translate images. A word processor application may have a tool button that markes text as bold. The button itself may have the capital letter B as image. This would not be suitable for e.g. a German user interface where the B would have to be replaced by an image displaying the letter F ('Bold' translates to the German 'Fett').

The resource system supports the following two types of translatable images:

The string i18n serves as an indicator to activate a lookup mechanism that is aware of the current user interface language. The pixmap above will be looked up in one of the following directories:

As comparison a call to QPixmap(":image/bold") will search in different directories:

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. Therefore developers who want to provide translations for their pictures have to ensure that they provide a translation/picture for American English.

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/<lang>/html/<appname>-suffixes.html

These files are encoded in UTF-8.

Word Lists

/opt/Qtopia/etc/dict/<lang>/ contains word lists specific to the language. These files end with .dawg and are generated at install time from files without the .dawg suffix in the source. See the QDawg documentation for details.

The word lists are:

Special Localizations

Contacts

Qtopia defines name ordering conventions used by Contacts in the formatting section of $QPEDIR/etc/default/Trolltech/Contacts.conf, where a number of options are listed (by default 2 are provided), and the default selection between those options. See QContact::setLabelFormat() for a description of the format.


Copyright © 2008 Nokia Trademarks
Qtopia 4.3.3