.. Copyright 2013, 2014, 2015 Reahl Software Services (Pty) Ltd. All rights reserved.
 
Internationalisation
====================

.. sidebar:: Behind the scenes

   The Internationalisation infrastructure of Reahl is built using
   `Babel <http://babel.pocoo.org//>`_.

To make it possible to switch languages depending on who is viewing a
page, you have to instantiate a Translator at the top of a module and
assign it to the variable named `_`. Each translatable string is then
marked using a call to the Translator.

Existing tools are used to collect these strings all over your code so
that humans can translate them.

All other internationalisation in Reahl is done using the facilities
directly provided by `Babel <http://babel.pocoo.org//>`_.

The example presented here contains a simple View containing a user
message that needs to be translated. At the top of the page, a Menu is
displayed listing all locales supported by the system.

.. note::

   In order to be able to illustrate how URLs influence the locale used,
   the example does not have a home page. If you run the example locally,
   you will have to open the View by using its URL:
   http://localhost:8000/some_page.  

When viewed via http://localhost:8000/some_page the example program
shows the string in British English (the default):

   .. figure:: ../_build/screenshots/i18n1.png
      :alt: A screenshot with the message in English and a menu where the locale can be switched.


When the user clicks on "Afrikaans" in the Menu, the same page is
displayed in Afrikaans. Notice how the URL of the View has changed: it
now starts with "af" (the locale string for Afrikaans):

   .. figure:: ../_build/screenshots/i18n2.png
      :alt: A screenshot with the message in Afrikaans and a menu where the locale can be switched.


Embedding an identifier for the chosen locale in the URL of a View
means that a different URL will exist for each supported locale for a
View. This makes it possible for search engines to crawl and index all
localised versions of a View.

Here is the code of the example, with some explanation:

.. literalinclude:: ../../reahl/doc/examples/features/i18nexample/i18nexample.py


Note that the Translator instance is created for the `reahl-doc`
component -- the component in which the example resides, and that
contains its translated messages.

Translated messages are also shipped inside a component -- any given
component may provide the translation of any number of other
components, for any number of locales. This makes it possible for
anyone to add support for a chosen locale to any component, even if
the target component was developed by someone else without any
knowledge of the locale you want to add support for.

Translations of the user messages for a particular component have to
be prepared by humans (just like source code is) and compiled for use
in production. The `reahl` commandline tool includes commands that
help authors extract all the messages that are marked for translation
from the source code of a component, maintain these and finally
compile them for use.

