Documentation versions

Internationalisation

Internationalisation in Reahl is based on locales. A “locale” defines what natural language to use for user messages, and what other customs are applicable for users choosing that locale (such as how dates and numbers are formatted).

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.

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):

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):

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.

The code below shows how a HMenu is created that allows the user to choose between supported locales. Also shown is how strings that will be shown to a user are marked for translation by the customary method of enclosing them in _(...). To make a callable _ available, a Translator instance needs to be instantiated (typically at the top of each file). Note that the Translator instance is created for the reahl-doc component – the component in which the example resides.

from __future__ import print_function, unicode_literals, absolute_import, division
from reahl.web.fw import UserInterface, Url, UserInterface
from reahl.web.ui import HMenu
from reahl.web.ui import P
from reahl.web.ui import TwoColumnPage
from reahl.component.i18n import Translator

_ = Translator('reahl-doc')


class TranslatedUI(UserInterface):
    def assemble(self):
        self.define_view('/some_page', title=_('Translated example'), page=HomePage.factory())


class HomePage(TwoColumnPage):
    def __init__(self, view):
        super(HomePage, self).__init__(view, style='basic')

        self.header.add_child(HMenu.from_languages(view))

        current_url = Url.get_current_url()
        message = _('This is a translated string. The current URL is "%s".') % current_url.path
        self.main.add_child(P(view, text=message))

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.

A translation is 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.

All other internationalisation in Reahl is done using the facilities directly provided by Babel.

Previous topic

Security considerations

Next topic

Off-the-shelf functionality

Documentation versions