Class Translation

object --+
         |
        Translation

Overview
========
This class forms the basis of the Brainwave internationalization/localization
framework. This allows your web-application to offer its content and functionality
in multiple languages. 

It uses python's gettext module in the background to switch strings within your application.

If you do not need internationalization:
========================================
Internationalization is on by default. This means that there is a little
bit of overhead in parts of the framework. If you do not need 
internationalization, you should remove the "locale" folder in 
apps/<appname>/resources. Then, when the application is loaded, the i18n
machinery will be automatically shut-off. The locale folder is not created by
the standard template creation machinery.

If you do need internationalization:
====================================
1. Embed translation strings within your application::
        def my_method(self):
                return _("Hello")       # The _ function marks the string "Hello" as a translation string
2. Create a template (.pot) file by running the L{pygettext} utility on your source code::
        $ ./pygettext.py -d <appname> -o apps/<appname>/resources/locale/<appname>.pot apps/<appname>/*.py
        (This example assumes you are currently in the root Brainwave installation folder)
3. Write locale specific (.po) files containing translations for each language you wish to support
   and save them in the respective locale/<language>/LC_MESSAGES folder::
        apps/<appname>/resources/locale/fr/LC_MESSAGES/<appname>.po             # French translation strings
        apps/<appname>/resources/locale/de/LC_MESSAGES/<appname>.po     # German translation strings
        apps/<appname>/resources/locale/es/LC_MESSAGES/<appname>.po     # Spanish translation strings
4. Compile each .po file into .mo files using L{msgfmt}::
        $ ./msgfmt.py -o apps/<appname>/resources/locale/fr/LC_MESSAGES/<appname>.mo apps/<appname>/resources/locale/fr/LC_MESSAGES/<appname>.po
        (This example assumes you are currently in the root Brainwave installation folder)

For more detailed information on how this process works, refer to the Python documentation
for the L{gettext} module.

How it works
============
Brainwave's Iris engine has a "lang_tool" middleware component which looks at each 
incoming request and tries to discover the language setting in the following manner:
        1. First, it looks at the current user's session for a "bw-language" key.
        2. Failing that, it searches for a cookie named according to the "lang.cookie_name" configuration setting (default: bw-language)
        3. If no such cookie exists, the Accept-Language HTTP header is searched. This is sent by your browser and specifies which language(s)
           you prefer in order by priority. Brainwave tries each one until it finds one with available translations.
        4. Finally, the global "lang.default" configuration option is used
        5. If this is corrupt or somehow unavailable, "en-US" is the default language.

In each of these places, the language preference must be in standard language format
as a string. e.g. US English is "en-US", French is "fr", German is "de", Spanish is "es".

Once the language has been identified, a translation instance is created which 
contains all translation strings loaded from the corresponding .mo file. This translation
object can be accessed via the iris.utils.translation member and exposes the same API as the
L{gettext} module in the Python standard library.

If you are developing on Firefox and you want to test your language setup, you can easily switch
languages via Firefox preferences > Advanced > Language > Choose...