cmlenz@74: .. -*- mode: rst; encoding: utf-8 -*-
cmlenz@74: 
cmlenz@74: =============================
cmlenz@74: Support Classes and Functions
cmlenz@74: =============================
cmlenz@74: 
cmlenz@74: .. contents:: Contents
cmlenz@74:    :depth: 2
cmlenz@74: .. sectnum::
cmlenz@74: 
cmlenz@74: 
cmlenz@74: The ``babel.support`` modules contains a number of classes and functions that
cmlenz@74: can help with integrating Babel, and internationalization in general, into your
cmlenz@74: application or framework. The code in this module is not used by Babel itself,
cmlenz@74: but instead is provided to address common requirements of applications that
cmlenz@74: should handle internationalization. 
cmlenz@74: 
cmlenz@74: 
cmlenz@74: ---------------
cmlenz@74: Lazy Evaluation
cmlenz@74: ---------------
cmlenz@74: 
cmlenz@74: One such requirement is lazy evaluation of translations. Many web-based
cmlenz@74: applications define some localizable message at the module level, or in general
cmlenz@74: at some level where the locale of the remote user is not yet known. For such
cmlenz@74: cases, web frameworks generally provide a "lazy" variant of the ``gettext``
cmlenz@74: functions, which basically translates the message not when the ``gettext``
cmlenz@74: function is invoked, but when the string is accessed in some manner.
cmlenz@74: 
cmlenz@74: 
cmlenz@74: ---------------------------
cmlenz@74: Extended Translations Class
cmlenz@74: ---------------------------
cmlenz@74: 
cmlenz@74: Many web-based applications are composed of a variety of different components
cmlenz@74: (possibly using some kind of plugin system), and some of those components may
cmlenz@74: provide their own message catalogs that need to be integrated into the larger
cmlenz@74: system.
cmlenz@74: 
cmlenz@74: To support this usage pattern, Babel provides a ``Translations`` class that is
cmlenz@74: derived from the ``GNUTranslations`` class in the ``gettext`` module. This
cmlenz@74: class adds a ``merge()`` method that takes another ``Translations`` instance,
cmlenz@74: and merges the content of the latter into the main catalog:
cmlenz@74: 
cmlenz@74: .. code-block:: python
cmlenz@74: 
cmlenz@74:     translations = Translations.load('main')
cmlenz@74:     translations.merge(Translations.load('plugin1'))