Internationalization Guide

Overview

This guide will explain how to create internationalization support (ie: dictionaries files) and to use it to translate an application.

This will be done in two steps:

Using qilinguist, a qibuild tool, to create and generate a dictionary file.
Setting up the C++ application to find and translate strings.

How to use qilinguist

Configuration of translation files

First of all you need to create a ``po`` directory into your root application folder and POTFILES.in in it.

helloapp
  |_ po
      |_ POTFILES.in
  |_ src
      |_ main.cpp
      |_ hello.cpp
  |_ headers
      |_ hello.h

Into the POTFILES.in you MUST add the relative path of all files you want to translate. For example, if you only have translation in hello.cpp, the POTFILES.in looks like:

$ cat po/POTFILES.in
src/hello.cpp

Add qilinguist configurations

You need to add a ``translate`` node into the qiproject.xml file. This configuration is used by ``qilinguist`` to generate translation files and installation rules.

The qiproject.xml will look like:

<project name="helloApp">
  <translate name="helloApp" domain="hello" linguas="fr_FR en_US" tr="gettext" />
/project>

Tag definitions:

``name``: The name of the application or library.
``domain``: The name of the generated dictionary.
``linguas``: A list of all locales supported formatted as xx_XX (country and language code)
``tr``: Define if you use gettext or QT internationalization (value can be: "gettext" or "qt").

Dictionaries will be install into:

<sdk_path>/share/locale/<name>/<linguas>/LC_MESSAGES/<domain>.mo

How to use qilinguist

Everything is ready to generate and edit dictionaries.

There are two commands to use:

qilinguist update: finds the translatable strings in the specified source, header and generates or updates .po (or .ts) translation files.
Warning:
: The jp_JP.po isn't correct. You need to replace
```
    "Content-Type: text/plain; charset=ASCII\n" 
```
by
```
    "Content-Type: text/plain; charset=UTF-8\n" 
```
qilinguist release: produces MO files out of PO ones or QM files out of TS ones. The format of those files is a binary format that is used by the localized application.

First of all you need to generate or update translatable files by using ``qilinguist update``. This will create files (into ``po`` folder) you can edit using Linguist from the Qt SDK or poedit for instance.

Once you have translated those files, you need to compile them by using ``qilinguist release``.

How to internationalize C++ applications

Update CMakeLists.txt

You must add the qi_create_trad(projectname "po") into the CMakeLists.txt root file.

cmake_minimum_required(VERSION 2.8)
project(yourProjectName)
qi_create_trad(yourProjectName "po")

Set and configure qi::Translator

You need to get a default qi::Translator, then you MUST set the default domain and current locale.

Steps:

Get default Translator (qi::defaultTranslator(const std::string &name)) with ``name`` the name of the application or library.
Set default domain (qi::Translator::setDefaultDomain(const std::string &domain)) with ``domain`` the name of the generated dictionary.
Set current locale (qi::Translator::setCurrentLocale(const std::string &locale)) with ``locale`` the name of the default loacle formatted as xx_XX (country and language code)

Warning:: : The ``name`` and ``domain`` must be the same as those define into the qiproject.xml; : The ``locale`` must be a locale supported and define into the qiproject.xml, otherwise it will fallback to the default value.

You can add some domains by using qi::Translator::addDomain(const std::string &domain). This will allow qi::Translator to look it multiple dictionary.

You can change the locale you want to use by calling qi::Translator::setCurrentLocale(const std::string &locale). This function allows you to set and switch language at runtime.

How to translate sentences

You have two choices to translate your sentences:

All sentences will be parsed when calling qilinguist update, then generate translation files (ie: po/ts files). Then, at runtime qi::Translator::translate will look for translation regarding initialization done in the last paragraphe.

Example

/*
 * Copyright (c) 2013 Aldebaran Robotics. All rights reserved.
 * Use of this source code is governed by a BSD-style license that can be
 * found in the COPYING file.
 */

#include <iostream>

#include <qi/application.hpp>
#include <qi/os.hpp>
#include <qi/translator.hpp>


int main(int argc, char *argv[])
{
  qi::Application app(argc, argv);
  app.setName("qitranslate");

  qi::Translator &tl = qi::defaultTranslator(app.name());
  tl.setCurrentLocale("en_US");
  tl.setDefaultDomain("translate");

  std::cout << qi::tr("Hi, my name is NAO.") << std::endl;
  std::cout << qi::tr("Where is Brian?") << std::endl;
  std::cout << qi::tr("Brian is in the kitchen.") << std::endl;

  tl.setCurrentLocale("fr_FR");
  std::cout << qi::tr("Hi, my name is NAO.") << std::endl;
  std::cout << qi::tr("Where is Brian?") << std::endl;
  std::cout << qi::tr("Brian is in the kitchen.") << std::endl;

  std::cout << qi::tr("Brian is in the kitchen.", "", "en_US") << std::endl;
  std::cout << qi::tr("Brian is in the kitchen.", "", "fr_FR") << std::endl;
}