From 51981a128c7ed05e51938a3f358c0970dcc33a6f Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Wed, 21 Apr 2010 10:35:07 +0000 Subject: Moved i18n work to a branch and revert to pre-i18n-feature state via svn merge -r9054:9030 svn+ssh://repoze@svn.repoze.org/svn/repoze.bfg/trunk --- docs/api.rst | 1 - docs/api/i18n.rst | 23 ----- docs/glossary.rst | 24 ----- docs/index.rst | 1 - docs/latexindex.rst | 1 - docs/narr/i18n.rst | 265 ---------------------------------------------------- docs/narr/views.rst | 5 - 7 files changed, 320 deletions(-) delete mode 100644 docs/api/i18n.rst delete mode 100644 docs/narr/i18n.rst (limited to 'docs') diff --git a/docs/api.rst b/docs/api.rst index a97c79fa9..2bd5fca01 100644 --- a/docs/api.rst +++ b/docs/api.rst @@ -15,7 +15,6 @@ documentation is organized alphabetically by module name. api/configuration api/events api/exceptions - api/i18n api/interfaces api/location api/paster diff --git a/docs/api/i18n.rst b/docs/api/i18n.rst deleted file mode 100644 index a67350b64..000000000 --- a/docs/api/i18n.rst +++ /dev/null @@ -1,23 +0,0 @@ -.. _i18n_module: - -:mod:`repoze.bfg.i18n` ----------------------- - -.. automodule:: repoze.bfg.i18n - - .. autoclass:: TranslationString - - .. autoclass:: TranslationStringFactory - - .. autoinstance:: bfg_tstr - - .. autofunction:: get_translator(request) - - .. autofunction:: interpolate - - .. autoclass:: InterpolationOnlyTranslator - -See :ref:`i18n_chapter` for more information about using -:mod:`repoze.bfg` internationalization services within an application. - - diff --git a/docs/glossary.rst b/docs/glossary.rst index 537af06b9..14bd4fc44 100644 --- a/docs/glossary.rst +++ b/docs/glossary.rst @@ -667,27 +667,3 @@ Glossary at import time, the action usually taken by the decorator is deferred until a separate "scan" phase. :mod:`repoze.bfg` relies on Venusian to provide a basis for its :term:`scan` feature. - - Translation String - An instance of the :class:`repoze.bfg.i18n.TranslationString`, - which is a class that behaves like a Unicode string, but has - several extra attributes such as ``domain``, ``msgid``, and - ``mapping`` for use during translation. Translation strings are - usually created by hand within software, but are sometimes - created on the behalf of the system for automatic template - translation. For more information, see :ref:`i18n_chapter`. - - Translator - A callable which receives a :term:`translation string` and - returns a translated Unicode object for the purposes of - internationalization. A translator may be suppled to a - :mod:`repoze.bfg` application at startup time indirectly via the - ``translator_factory`` function, which is a :term:`translator - factory`. - - Translator Factory - A callable which receives a :term:`request` and returns a - :term:`translator` for the purposes of internationalization. A - translator factory may be suppled to a :mod:`repoze.bfg` - application at startup time via the ``translator_factory`` - function. diff --git a/docs/index.rst b/docs/index.rst index c1b185352..ee32cf691 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -53,7 +53,6 @@ Narrative documentation in chapter form explaining how to use narr/templates narr/models narr/security - narr/i18n narr/vhosting narr/events narr/environment diff --git a/docs/latexindex.rst b/docs/latexindex.rst index 5850ee06c..45438e939 100644 --- a/docs/latexindex.rst +++ b/docs/latexindex.rst @@ -42,7 +42,6 @@ Narrative Documentation narr/templates narr/models narr/security - narr/i18n narr/vhosting narr/events narr/environment diff --git a/docs/narr/i18n.rst b/docs/narr/i18n.rst deleted file mode 100644 index 45bbab342..000000000 --- a/docs/narr/i18n.rst +++ /dev/null @@ -1,265 +0,0 @@ -.. index:: - single: i18n - single: internationalization - -.. _i18n_chapter: - -Using Internationalization -========================== - -:mod:`repoze.bfg` offers an internationalization (i18n) subsystem that -can be used to translate the text of buttons, the text of error -messages and other software-defined values into the native language of -aq user of your :mod:`repoze-bfg` driven website. - -Activating Translation ----------------------- - -By default, a :mod:`repoze.bfg` application performs no translation -without explicitly configuring a :term:`translator factory`. To make -any translation at all happen, you must pass a translator factory -object to your application's -:mod:`repoze.bfg.configuration.Configurator` by supplying it with a -``translator_factory`` argument. For example: - -.. code-block:: python - :linenos: - - from repoze.bfg.configuration import Configurator - from repoze.bfg.i18n import InterpolationOnlyTranslator - config = Configurator(translator_factory=InterpolationOnlyTranslator) - -.. note:: At the time of this writing, only one (very weak) translator - factory named :class:`repoze.bfg.i18n.InterpolationOnlyTranslator` - ships as part of the :mod:`repoze.bfg` software. This class only - does basic interpolation of mapping values; it does not actually do - any language translation. - -Creating a Translation String ------------------------------ - -While you write your software, you can insert specialized markup into -your Python code that makes it possible for the system to translate -text values into the languages used by your application's users. This -markup generates a :term:`translation string`. A translation string -is an object that behave mostly like a normal Unicode object, except -that it also carries around extra information related to its job as -part of :mod:`repoze.bfg` the translation machinery. - -Using The ``TranslationString`` Class -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -One way to create a translation string is to use the -:class:`repoze.bfg.i18n.TranslationString` callable: - -.. code-block:: python - :linenos: - - from repoze.bfg.i18n import TranslationString - ts = TranslationString('Add') - -This creates a Unicode-like object that is a TranslationString. - -The first argument to :class:`repoze.bfg.i18n.TranslationString` is -the ``text``; it is required. The ``text`` value acts as a default -value for the translation string if a translation to the user's -language cannot be found at translation time. The ``text`` argument -must be a Unicode object or an ASCII string. The text may optionally -contain *replacement markers*. For instance: - -.. code-block:: python - :linenos: - - from repoze.bfg.i18n import TranslationString - ts = TranslationString('Add ${number}') - -Within the string above, ``${stuff}`` is a replacement marker. It -will be replaced by whatever is in the *mapping* for a translation -string. The mapping may be supplied at the same time as the -replacement marker: - -.. code-block:: python - :linenos: - - from repoze.bfg.i18n import TranslationString - ts = TranslationString('Add ${number}', mapping={'number':1}) - -Any number of replacement markers can be present in th text value, any -number of times. Only markers which can be replaced by the values in -the *mapping* will be replaced at translation time. The others will -not be interpolated and will be output literally. - -A translation string should also usually carry a *domain*. The domain -represents a translation category to disambiguate it from other -translations of the same msgid, in case they conflict. - -.. code-block:: python - :linenos: - - from repoze.bfg.i18n import TranslationString - ts = TranslationString('Add ${number}', mapping={'number':1}, - domain='form') - -The above translation string named a domain of "form". A -:term:`translator` function will often use the domain to locate a file -on the filesystem which contains translations for a given context. In -this case, if it were trying to translate to our msgid to German, it -might try to find a translation from a :term:`gettext` file like this -one:: - - locale/de/LC_MESSAGES/form.mo - -In other words, it would want to take translations from the "form.mo" -translation file in the German language. - -Domain translation support is dependent upon the :term:`translator -factory` in use. Not all translator factories use domain information -that is associated with a translation string. However, it is always -safe to associate a given translation string with a domain; the -information is ignored by translators that don't support it. - -Finally, the TranslationString constructor accepts a ``msgid`` -argument. If a ``msgid`` argument is supplied, it is used as the -*message identifier* for the translation string. When ``msgid`` is -``None``, the ``text`` value passed to a TranslationString is used as -an implicit message identifier. Message identifiers are matched with -translations in translation files, so it is often useful to create -translation strings with "opaque" message identifiers unrelated to -their default text: - -.. code-block:: python - :linenos: - - from repoze.bfg.i18n import TranslationString - ts = TranslationString('Add ${number}', msgid='add-number', - domain='form', mapping={'number':1}) - -Using the ``bfg_tstr`` Translation String Factory -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Another way to generate a translation string is to use the -:attr:`repoze.bfg.i18n.bfg_tstr` object. This object is a -*translation string factory*. Basically a translation string factory -presets the ``domain`` value of any :term:`translation string` -generated by using it. For example: - -.. code-block:: python - :linenos: - - from repoze.bfg.i18n import bfg_tstr as _ - ts = _('Add ${number}', msgid='add-number', mapping={'number':1}) - -.. note:: We imported ``bfg_tstr`` as the name ``_``. This is a - convention which will be supported by translation file generation - tools. - -The result of calling ``bfg_tstr`` is a -:class:`repoze.bfg.i18n.TranslationString` instance. Even though a -``domain`` value was not passed to bfg_tstr (as would have been -necessary if the :class:`repoze.bfg.i18n.TranslationString` -constructor were used instead of a translation string factory), the -``domain`` attribute of the resulting translation string will be -``bfg``. As a result, the previous code example is completely -equivalent (except for spelling) to: - -.. code-block:: python - :linenos: - - from repoze.bfg.i18n import TranslationString as _ - ts = _('Add ${number}', msgid='add-number', mapping={'number':1}, - domain='form') - -Using the ``TranslationStringFactory`` Class -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -You can set up your own translation string factory much like the one -provided as :mod:`repoze.bfg.i18n.bfg_tstr` by using the -:class:`repoze.bfg.i18n.TranslationStringFactory` class. For example, -if you'd like to create a translation string factory which presets the -``domain`` value of generated translation strings to ``form``, you'd -do something like this: - -.. code-block:: python - :linenos: - - from repoze.bfg.i18n import TranslationStringFactory - _ = TranslationStringFactory('form') - ts = _('Add ${number}', msgid='add-number', mapping={'number':1}) - -.. note:: We created this factory with the name ``_``. This is a - convention which will be supported by translation file generation - tools. - -Performing a Translation by Hand --------------------------------- - -If you need to perform translation "by hand" in an application, use -the :func:`repoze.bfg.i18n.get_translator` function to obtain a -:term:`translator` . :func:`repoze.bfg.i18n.get_translator` will -return either the current translator defined by the -``translator_factory`` passed to the Configurator at startup or a -default translator if no explicit translator factory has been -registered. - -Remember that a translator is a callable which accepts either a -:term:`translation string` and which returns a Unicode object -representing the translation. So, generating a translation in a view -component of your application might look like so: - -.. code-block:: python - :linenos: - - from repoze.bfg.i18n import get_translator - - from repoze.bfg.i18n import bfg_tstr as _ - ts = _('Add ${number}', mapping={'number':1}) - - def aview(request): - translator = get_translator(request) - translated = translator(ts) - -A translator may be called any number of times after being retrieved -from the ``get_translator`` function. - -Defining A Translator Factory ------------------------------ - -A translator factory is an object which accepts a :term:`request` and -which returns a :term:`translator` callable. - -The :term:`translator` callable returned by a translator factory must -accept a single positional argument which represents a -:term:`translation string` and should return a fully localized and -expanded translation of the translation string. - -A simplistic implementation of both a translator factory and a -translator (via its constructor and ``__call__`` methods respecively) -named :class:`repoze.bfg.i18n.InterpolationOnlyTranslator` is defined. -Here it is: - -.. code-block:: python - :linenos: - - from repoze.bfg.i18n import interpolate - - class InterpolationOnlyTranslator(object): - def __init__(self, request): - self.request = request - - def __call__(self, message): - mapping = getattr(message, 'mapping', None) - return interpolate(message, mapping) - -The exact operation of a translator is left to the implementor of a -particular translator factory. You can define and use your own -translator factory by passing it as the ``translator_factory`` -argument to the :class:`repoze.bfg.configuration.Configurator` -constructor. - -.. code-block:: python - :linenos: - - from repoze.bfg.configuration import Configurator - from repoze.bfg.i18n import InterpolationOnlyTranslator - config = Configurator(translator_factory=InterpolationOnlyTranslator, ...) - diff --git a/docs/narr/views.rst b/docs/narr/views.rst index eebaa63de..a24e4b7b5 100644 --- a/docs/narr/views.rst +++ b/docs/narr/views.rst @@ -840,11 +840,6 @@ In all cases, the message provided to the exception constructor is made available to the view which :mod:`repoze.bfg` invokes as ``request.exception.args[0]``. -.. index:: - single: exception views - -.. _exception_views: - Exception Views ~~~~~~~~~~~~~~~~ -- cgit v1.2.3