Qtopia Home - Classes - Hierachy - Annotated - Functions - Qt Embedded |

# Qtopia Internationalization

- Introduction
- Program Internationalization
  - Placing Application Files
  - Placing Plugin Files
- Desktop File Internationalization
- Documentation Internationalization
- Other Internationalization Files
- Translating Qtopia to Additional Languages
- How to Localize Qtopia

## Introduction

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.

## Program Internationalization

The process of internationalization produces 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, eg. "en", "en_GB", "ja", "ja_JP". The appname is the filename of the application executable.

### Placing Plugin Files

For plugins 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 plugin shared object minus any extensions, but including "lib" if the plugin 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.

## Desktop File Internationalization

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

These files are encoded in UTF-8.

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

## Other Internationalization Files

Other files that are language-specific are:

- /opt/Qtopia/etc/dict/words-language - list of words in language.
- /opt/Qtopia/etc/dict/words-language.dawg - above, converted to dawg format.
- /opt/Qtopia/etc/dict/common-language - list of common words in language that input methods might conflict with less common words.
- /opt/Qtopia/etc/dict/common-language.dawg - above, converted to dawg format.
- /opt/Qtopia/pics/pkim/dict-language-lc.png - image representing input in language to non-native speakers. A flag is one possibility.
- /opt/Qtopia/pics/pkim/dict-language-uc.png - above, but representing Uppercase input.

## Translating Qtopia to Additional Languages

Qtopia ships with a number of supported languages. To translate it into an additional language, you must perform the translation process described above for all the application and desktop files, and any help documentation that you wish to have available in that language. In addition to this you will need to translate the library texts found in:

/opt/Qtopia/i18n/language/libqpe.qm

Qt Linguist supports incremental translation, which helps you keep track of any additional content that is added to Qtopia and needs translation.

Qtopia uses Helvetica as default font. However, this font does not specify the characters for Chinese for instance. The default font can be changed in ~/Settings/qpe.conf. The line

FontFamily=helvetica

needs to be replaced by

FontFamily=<the new font family> e.g. unifont for Chinese.

Also, the configuration file ~/Settings/`FontMap.conf` has to be changed. It defines the font which can be selected by users within Qtopia. If this configuration file is empty, Qtopia will use Helvetica font. Therefore, a valid FontMap.conf file is required to suppress helvetica a selectable choice. `FontMap.conf` might look like this:

    [Map]
    Font0=small-uni,unifont,12
    Font1=normal-uni,unifont,13
    Font2=large-helv,helvetica,14

This file is encoded in UTF-8. The first parameter in the comma seperated list is the textual string that is presented to the user. The second parameter specifies the font family and the last parameter determines the font size.

## How to Localize Qtopia

1. Acquire `application-LanguageCode.ts` for each application.
2. Use Qt Linguist (from Qt 3) to translate the `.ts` files.

3. 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. A comment [in square brackets] should be appended to the these kinds of translations:

   (ambiguous)
   Source text
   View
   Translation
   Vue [Noun or verb?]

   (unclear / suspect)
   Source text
   %1:%2
   Translation
   %1:%2 [What is this? Note that in Fooish, the time "14:30" is written "30foo14", except on Tuesday when it is written "30bar14"]

4. Submit entire `.ts` file to Trolltech; you will receive feedback on all the comments to unfinished items and implementations will be changed as necessary/possible (which should hopefully be sufficient to complete the translation). The feedback usually takes the form of added comments to the `.ts` files so that future translators are similarly informed),