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