QML/Internationalisation

Latest revision as of 16:29, 1 June 2012

Overview

This tutorial explains how to internationalise a QML application.

It does not cover topics like integrating with translation sites (e.g. transifex), how to version control translation files, or automation of the Qt translation tools. In other words, it doesn't provide a build workflow for translations, such as you might want in a real development environment.

If you are translating a Qt application (not a QML UI), you can incorporate many of the translation steps into the .pro project file: see http://doc.qt.nokia.com/4.7/linguist-manager.html. This automates some of the build steps covered below.

However, for translation of QML interfaces, I was unable to make QML files part of this type of project automation. There is no mention of how to do this in the page about QML i18n (http://doc.qt.nokia.com/4.7/qdeclarativei18n.html) either. So I've explained the manual process instead.

Pre-requisites

Qt Creator (MeeGo 1.1 SDK version) installed. See these instructions.

System Setup

No special system setup is required.

How to

Follow these steps to internationalise a QML application:

1. Use a custom Qt app to load your QML, rather than the default qmlviewer: this makes it easier to internationalise the project. I used the transparent window application as a starting point.
   If you run a QML application under the default qmlviewer, you'll have to pass a -translation flag to it, telling it which language file to use for string translations.
2. Add qsTr("some string") properties to elements in the QML user interface definition. The recommendation is that you only use ASCII characters in the strings which occur in the source QML files. For example:

   import Qt 4.7
   
   Rectangle {
     width: 320
     height: 240
   
     Text {
       text: qsTr("__hello__")
       anchors.horizontalCenter: parent.horizontalCenter
       anchors.verticalCenter: parent.verticalCenter
     }
   }
   

   The __string__ syntax makes it easier for me to notice whether translations are working when the application runs (anything with underlines around hasn't been translated). In a real application you might want to put the translation strings in as English strings, so at least if any strings aren't translated, or if the system's locale is not supported, the user will see English.

3. You need one translation for each language you want to use. It's probably a good idea to include translations for the application's native language to stop yourself being lazy and accidentally leaving English (or whatever your native language is) strings in there.
   To generate these, you need to use the lupdate program first. This creates the .ts files which are used as a basis for creating translations. Run this inside the project directory from the command line:

   /opt/meego/meego-sdk-qt/bin/meego-sdk-wrapper lupdate *.qml \
   -ts qml-translations.en.ts qml-translations.fr.ts qml-translations.de.ts
   

   The scan is recursive by default. It creates the .ts files you specified, with "unfinished" entries for each translatable string in your app's QML files. If you want more languages to be supported, add more .ts file names to the command line.
   The language codes are constructed from:

   • A two letter ISO 639-1 language code, e.g. en (English), fr (French), de (German).
   • An (optional) underscore + two letter ISO 3166-1_alpha 2 country code (representing the regional variant of the language), e.g. _GB, _US, _CA (Canada).

   So you can potentially provide:

   • One file for each language code (qml-translations.en.ts for generic English).
   • One file for each language code/region pair (qml-translations.en_US.ts for American English, qml-translations.en_GB.ts for UK English).

   In cases where you have both generic translations and region-specific ones, someone from a region you haven't covered (e.g. en_AU, Australian English) will get the generic translations (the en ones).

4. Now you need to flesh out the .ts files using Qt Linguist to edit them:
   

   /opt/meego/meego-sdk-qt/bin/meego-sdk-wrapper linguist *.ts

   See http://doc.qt.nokia.com/4.7/linguist-translators.html for more about using Qt Linguist.

5. Check that there are no unfinished translations in the .ts files. This will prevent you releasing your application with missing translations. Here's an example command will show the names of any .ts files which have one or more unfinished translations:
   

   grep -c "translation type=\"unfinished\"" *.ts | grep -v -E ":0$"
   

6. Create the release binaries (.qm files) containing the translations:
   

   /opt/meego/meego-sdk-qt/bin/meego-sdk-wrapper lrelease *.ts
   

7. Next we use the .qm files we just created as Qt resources, along with some special directory path syntax, to load them into the translator. (I couldn't get them to load as non-resource files unless I used an absolute file path.)
   1. Add a new Qt Resource file (.qrc) to the project (right-click on the project in Qt Creator, select Add New...).
   2. Add the .qm files to the .qrc file as resources. When the application is built, resources are compiled into the binary so they can be accessed by the application in a platform-agnostic fashion.
   3. Edit the main.cpp file so it loads the appropriate translation resource (.qm) into the application, based on the locale:
      

      #include <QTranslator>
      #include <QLocale>
      #include <QtGui/QApplication>
      #include "mainwindow.h"
      
      int main(int argc, char *argv[])
      {
        QApplication app(argc, argv);
      
        QString locale = QLocale::system().name();
      
        QTranslator translator;
      
        /* the ":/" is a special directory Qt uses to
         * distinguish resources;
         * NB this will look for a filename matching locale + ".qm";
         * if that's not found, it will truncate the locale to
         * the first two characters (e.g. "en_GB" to "en") and look
         * for that + ".qm"; if not found, it will look for a
         * qml-translations.qm file; if not found, no translation is done
         */
        if (translator.load("qml-translations." + locale, ":/"))
          app.installTranslator(&translator);
      
        MainWindow w;
        w.show();
      
        return app.exec();
      }
      

      Note that we could enhance this code to default to English (set locale to en) if a user's language isn't supported.
      

      See http://doc.qt.nokia.com/4.7/linguist-programmers.html, which explains more about integrating translations into a Qt app.

   4. Run the binary from the qml-translations-build-desktop directory (where the code is compiled by default) or the equivalent location if you're using a MADDE toolchain:
      

      /opt/meego/meego-sdk-qt/bin/meego-sdk-qtapp ./qml-translations
      

      NB this uses the meego-sdk-qtapp wrapper script, described below.
      

      If your language is set to en_GB or en_US, you should see the English version; if set to fr_FR or de_AT, you'll see it in French or German respectively. If you are using another language, you'll see untranslated strings.
      

      You can try it in a different language with:

      LANG=fr_FR.utf8 /opt/meego/meego-sdk-qt/bin/meego-sdk-wrapper ./qml-translations
      LANG=de_AT.utf8 /opt/meego/meego-sdk-qt/bin/meego-sdk-wrapper ./qml-translations
      

   MeeGo SDK wrapper script

   For reference: I created a wrapper for other MeeGo SDK Qt binaries (lupdate and lrelease) and my own executables, to ensure that the MeeGo SDK Qt libraries occur first on the path.

   Hopefully this will eventually be redundant, if/when the SDK supplies its own wrapper.

   Put the following code in a file called meego-sdk-qtapp, in the same directory as the MeeGo SDK binaries (/opt/meego/meego-sdk-qt/bin):

   #!/bin/sh
   
   export QTDIR="`meego-sdk-qmake -query QT_INSTALL_PREFIX`"
   export QT_PLUGIN_PATH="`meego-sdk-qmake -query QT_INSTALL_PLUGINS`"
   export QT_LIBS_PATH="`meego-sdk-qmake -query QT_INSTALL_LIBS`"
   
   # Let the wrapped binary know that it has been run through the wrapper.
   export WRAPPER="`readlink -f "$0"`"
   HERE="`dirname "$WRAPPER"`"
   
   case ":$PATH:" in
     *:$HERE:*)
       # $PATH already contains $HERE, leave it where it is.
       ;;
     *)
       # Prepend $HERE to $PATH.
       export PATH="$HERE:$PATH"
       ;;
   esac
   
   # Always use our versions of Qt libs.
   if [ -n "$LD_LIBRARY_PATH" ]; then
     LD_LIBRARY_PATH="$QT_LIBS_PATH:$HERE:$HERE/lib:$LD_LIBRARY_PATH"
   else
     LD_LIBRARY_PATH="$QT_LIBS_PATH:$HERE:$HERE/lib"
   fi
   export LD_LIBRARY_PATH
   
   APP=$1
   shift
   
   if [ -f $HERE/$APP ] ; then
     $HERE/$APP "$@"
   else
     $APP "$@"
   fi
   

   Make sure it's executable (chmod +x).

   Then use it to run the MeeGo SDK applications like this:

   /opt/meego/meego-sdk-qt/bin/meego-sdk-qtapp lupdate <other arguments here>
   

   Or your own applications (like the qml-translator application created above) with:

   /opt/meego/meego-sdk-qt/bin/meego-sdk-qtapp ./qml-translator