From fec0f0614c69dc7382fba367f8269479e2682058 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Mon, 25 Oct 2010 18:47:29 -0400 Subject: convert narrative docs to Pyramid --- docs/narr/i18n.rst | 180 ++++++++++++++++++++++++++--------------------------- 1 file changed, 89 insertions(+), 91 deletions(-) (limited to 'docs/narr/i18n.rst') diff --git a/docs/narr/i18n.rst b/docs/narr/i18n.rst index cab327bb8..aaa1962e8 100644 --- a/docs/narr/i18n.rst +++ b/docs/narr/i18n.rst @@ -15,14 +15,11 @@ one language or cultural context. :term:`Localization` (l10n) is the process of displaying the user interface of an internationalized application in a *particular* language or cultural context. -:mod:`repoze.bfg` offers internationalization and localization +:mod:`pyramid` offers internationalization and localization subsystems that can be used to translate the text of buttons, error messages and other software- and template-defined values into the native language of a user of your application. -.. note: The APIs and functionality described in this chapter are new - as of :mod:`repoze.bfg` version 1.3. - .. index:: single: translation string pair: domain; translation @@ -38,18 +35,18 @@ text values into the languages used by your application's users. This markup creates a :term:`translation string`. A translation string is an object that behaves mostly like a normal Unicode object, except that it also carries around extra information related to its job as part of -the :mod:`repoze.bfg` translation machinery. +the :mod:`pyramid` translation machinery. Using The ``TranslationString`` Class ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The most primitive way to create a translation string is to use the -:class:`repoze.bfg.i18n.TranslationString` callable: +:class:`pyramid.i18n.TranslationString` callable: .. code-block:: python :linenos: - from repoze.bfg.i18n import TranslationString + from pyramid.i18n import TranslationString ts = TranslationString('Add') This creates a Unicode-like object that is a TranslationString. @@ -62,7 +59,7 @@ This creates a Unicode-like object that is a TranslationString. :term:`Django` i18n, using a TranslationString is a lot like using "lazy" versions of related gettext APIs. -The first argument to :class:`repoze.bfg.i18n.TranslationString` is +The first argument to :class:`pyramid.i18n.TranslationString` is the ``msgid``; it is required. It represents the key into the translation mappings provided by a particular localization. The ``msgid`` argument must be a Unicode object or an ASCII string. The @@ -71,7 +68,7 @@ msgid may optionally contain *replacement markers*. For instance: .. code-block:: python :linenos: - from repoze.bfg.i18n import TranslationString + from pyramid.i18n import TranslationString ts = TranslationString('Add ${number}') Within the string above, ``${number}`` is a replacement marker. It @@ -82,7 +79,7 @@ replacement marker itself: .. code-block:: python :linenos: - from repoze.bfg.i18n import TranslationString + from pyramid.i18n import TranslationString ts = TranslationString('Add ${number}', mapping={'number':1}) Any number of replacement markers can be present in the msgid value, @@ -97,7 +94,7 @@ translations of the same msgid, in case they conflict. .. code-block:: python :linenos: - from repoze.bfg.i18n import TranslationString + from pyramid.i18n import TranslationString ts = TranslationString('Add ${number}', mapping={'number':1}, domain='form') @@ -126,7 +123,7 @@ identifiers unrelated to their default text: .. code-block:: python :linenos: - from repoze.bfg.i18n import TranslationString + from pyramid.i18n import TranslationString ts = TranslationString('add-number', default='Add ${number}', domain='form', mapping={'number':1}) @@ -140,7 +137,7 @@ Using the ``TranslationStringFactory`` Class ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Another way to generate a translation string is to use the -:attr:`repoze.bfg.i18n.TranslationStringFactory` object. This object +:attr:`pyramid.i18n.TranslationStringFactory` 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: @@ -148,8 +145,8 @@ generated by using it. For example: .. code-block:: python :linenos: - from repoze.bfg.i18n import TranslationStringFactory - _ = TranslationStringFactory('bfg') + from pyramid.i18n import TranslationStringFactory + _ = TranslationStringFactory('pyramid') ts = _('Add ${number}', msgid='add-number', mapping={'number':1}) .. note:: We assigned the translation string factory to the name @@ -157,26 +154,26 @@ generated by using it. For example: file generation tools. After assigning ``_`` to the result of a -:func:`repoze.bfg.i18n.TranslationStringFactory`, the subsequent -result of calling ``_`` will be a -:class:`repoze.bfg.i18n.TranslationString` instance. Even though a -``domain`` value was not passed to ``_`` (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: +:func:`pyramid.i18n.TranslationStringFactory`, the subsequent result +of calling ``_`` will be a :class:`pyramid.i18n.TranslationString` +instance. Even though a ``domain`` value was not passed to ``_`` (as +would have been necessary if the +:class:`pyramid.i18n.TranslationString` constructor were used instead +of a translation string factory), the ``domain`` attribute of the +resulting translation string will be ``pyramid``. 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 _ + from pyramid.i18n import TranslationString as _ ts = _('Add ${number}', msgid='add-number', mapping={'number':1}, - domain='bfg') + domain='pyramid') You can set up your own translation string factory much like the one provided above by using the -:class:`repoze.bfg.i18n.TranslationStringFactory` class. For example, +:class:`pyramid.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: @@ -184,7 +181,7 @@ do something like this: .. code-block:: python :linenos: - from repoze.bfg.i18n import TranslationStringFactory + from pyramid.i18n import TranslationStringFactory _ = TranslationStringFactory('form') ts = _('Add ${number}', msgid='add-number', mapping={'number':1}) @@ -193,7 +190,7 @@ factory is best practice. Using your own unique translation domain allows another person to reuse your application without needing to merge your translation files with his own. Instead, he can just include your package's :term:`translation directory` via the -:meth:`repoze.bfg.configuration.Configurator.add_translation_dirs` +:meth:`pyramid.configuration.Configurator.add_translation_dirs` method. .. note:: @@ -210,7 +207,7 @@ method. Working With ``gettext`` Translation Files ------------------------------------------ -The basis of :mod:`repoze.bfg` translation services is +The basis of :mod:`pyramid` translation services is GNU :term:`gettext`. Once your application source code files and templates are marked up with translation markers, you can work on translations by creating various kinds of gettext files. @@ -218,7 +215,7 @@ by creating various kinds of gettext files. .. note:: The steps a developer must take to work with :term:`gettext` - :term:`message catalog` files within a :mod:`repoze.bfg` + :term:`message catalog` files within a :mod:`pyramid` application are very similar to the steps a :term:`Pylons` developer must take to do the same. See the `Pylons internationalization documentation @@ -249,7 +246,7 @@ GNU gettext uses three types of files in the translation framework, makes the localized program run faster. The tool for working with :term:`gettext` translation files related to -a :mod:`repoze.bfg` application is :term:`Babel`. +a :mod:`pyramid` application is :term:`Babel`. .. index:: single: Babel @@ -262,13 +259,13 @@ Installing Babel In order for the commands related to working with ``gettext`` translation files to work properly, you will need to have :term:`Babel` installed into the same environment in which -:mod:`repoze.bfg` is installed. +:mod:`pyramid` is installed. Installation on UNIX ++++++++++++++++++++ If the :term:`virtualenv` into which you've installed your -:mod:`repoze.bfg` application lives in ``/my/virtualenv``, you can +:mod:`pyramid` application lives in ``/my/virtualenv``, you can install Babel like so: .. code-block:: bash @@ -280,7 +277,7 @@ Installation on Windows +++++++++++++++++++++++ If the :term:`virtualenv` into which you've installed your -:mod:`repoze.bfg` application lives in ``C:\my\virtualenv``, you can +:mod:`pyramid` application lives in ``C:\my\virtualenv``, you can install Babel like so: .. code-block:: bash @@ -336,7 +333,7 @@ Extracting Messages from Code and Templates Once :term:`Babel` is installed and your application's ``setup.py`` file has the correct message extractor references, you may extract a message catalog template from the code and :term:`Chameleon` templates -which reside in your :mod:`repoze.bfg` application. You run a +which reside in your :mod:`pyramid` application. You run a ``setup.py`` command to extract the messages: .. code-block:: bash @@ -356,11 +353,11 @@ The name ``myapplication`` above in the filename ``myapplication.pot`` denotes the :term:`translation domain` of the translations that must be performed to localize your application. By default, the translation domain is the :term:`project` name of your -:mod:`repoze.bfg` application. +:mod:`pyramid` application. To change the translation domain of the extracted messages in your project, edit the ``setup.cfg`` file of your application, The default -``setup.cfg`` file of a Paster-generated :mod:`repoze.bfg` application +``setup.cfg`` file of a Paster-generated :mod:`pyramid` application has stanzas in it that look something like the following: .. code-block:: ini @@ -439,7 +436,7 @@ Once the file is there, it can be worked on by a human translator. One tool which may help with this is `Poedit `_. -Note that :mod:`repoze.bfg` itself ignores the existence of all +Note that :mod:`pyramid` itself ignores the existence of all ``.po`` files. For a running application to have translations available, a ``.mo`` file must exist. See :ref:`compiling_message_catalog`. @@ -480,7 +477,7 @@ translations, compile ``.po`` files to ``.mo`` files:: This will create a ``.mo`` file for each ``.po`` file in your application. As long as the :term:`translation directory` in which the ``.mo`` file ends up in is configured into your application, these -translations will be available to :mod:`repoze.bfg`. +translations will be available to :mod:`pyramid`. .. index:: single: localizer @@ -491,8 +488,8 @@ Using a Localizer A :term:`localizer` is an object that allows you to perform translation or pluralization "by hand" in an application. You may use -the :func:`repoze.bfg.i18n.get_localizer` function to obtain a -:term:`localizer`. :func:`repoze.bfg.i18n.get_localizer`. This +the :func:`pyramid.i18n.get_localizer` function to obtain a +:term:`localizer`. :func:`pyramid.i18n.get_localizer`. This function will return either the localizer object implied by the active :term:`locale negotiator` or a default localizer object if no explicit locale negotiator is registered. @@ -500,7 +497,7 @@ locale negotiator is registered. .. code-block:: python :linenos: - from repoze.bfg.i18n import get_localizer + from pyramid.i18n import get_localizer def aview(request): locale = get_localizer(request) @@ -521,20 +518,21 @@ translation in a view component of an application might look like so: .. code-block:: python :linenos: - from repoze.bfg.i18n import get_localizer - from repoze.bfg.i18n import TranslationString + from pyramid.i18n import get_localizer + from pyramid.i18n import TranslationString - ts = TranslationString('Add ${number}', mapping={'number':1}, domain='bfg') + ts = TranslationString('Add ${number}', mapping={'number':1}, + domain='pyramid') def aview(request): localizer = get_localizer(request) translated = localizer.translate(ts) # translation string # ... use translated ... -The :func:`repoze.bfg.i18n.get_localizer` function will return a -:class:`repoze.bfg.i18n.Localizer` object bound to the locale name +The :func:`pyramid.i18n.get_localizer` function will return a +:class:`pyramid.i18n.Localizer` object bound to the locale name represented by the request. The translation returned from its -:meth:`repoze.bfg.i18n.Localizer.translate` method will depend on the +:meth:`pyramid.i18n.Localizer.translate` method will depend on the ``domain`` attribute of the provided translation string as well as the locale of the localizer. @@ -575,7 +573,7 @@ information attached to those objects is ignored. .. code-block:: python :linenos: - from repoze.bfg.i18n import get_localizer + from pyramid.i18n import get_localizer def aview(request): localizer = get_localizer(request) @@ -593,12 +591,12 @@ Obtaining the Locale Name for a Request --------------------------------------- You can obtain the locale name related to a request by using the -:func:`repoze.bfg.i18n.get_locale_name` function. +:func:`pyramid.i18n.get_locale_name` function. .. code-block:: python :linenos: - from repoze.bfg.i18n import get_locale_name + from pyramid.i18n import get_locale_name def aview(request): locale_name = get_locale_name(request) @@ -609,17 +607,17 @@ locale negotiator returns ``None``. You can change the default locale name by changing the ``default_locale_name`` setting; see :ref:`default_locale_name_setting`. -Once :func:`repoze.bfg.i18n.get_locale_name` is first run, the locale +Once :func:`pyramid.i18n.get_locale_name` is first run, the locale name is stored on the request object. Subsequent calls to -:func:`repoze.bfg.i18n.get_locale_name` will return the stored locale +:func:`pyramid.i18n.get_locale_name` will return the stored locale name without invoking the :term:`locale negotiator`. To avoid this -caching, you can use the :func:`repoze.bfg.i18n.negotiate_locale_name` +caching, you can use the :func:`pyramid.i18n.negotiate_locale_name` function: .. code-block:: python :linenos: - from repoze.bfg.i18n import negotiate_locale_name + from pyramid.i18n import negotiate_locale_name def aview(request): locale_name = negotiate_locale_name(request) @@ -630,7 +628,7 @@ You can also obtain the locale name related to a request using the .. code-block:: python :linenos: - from repoze.bfg.i18n import get_localizer + from pyramid.i18n import get_localizer def aview(request): localizer = get_localizer(request) @@ -638,7 +636,7 @@ You can also obtain the locale name related to a request using the Obtaining the locale name as an attribute of a localizer is equivalent to obtaining a locale name by calling the -:func:`repoze.bfg.i18n.get_locale_name` function. +:func:`pyramid.i18n.get_locale_name` function. .. index:: single: date and currency formatting (i18n) @@ -647,7 +645,7 @@ to obtaining a locale name by calling the Performing Date Formatting and Currency Formatting -------------------------------------------------- -:mod:`repoze.bfg` does not itself perform date and currency formatting +:mod:`pyramid` does not itself perform date and currency formatting for different locales. However, :term:`Babel` can help you do this via the :class:`babel.core.Locale` class. The `Babel documentation for this class @@ -657,7 +655,7 @@ related locale operations. See :ref:`installing_babel` for information about how to install Babel. The :class:`babel.core.Locale` class requires a :term:`locale name` as -an argument to its constructor. You can use :mod:`repoze.bfg` APIs to +an argument to its constructor. You can use :mod:`pyramid` APIs to obtain the locale name for a request to pass to the :class:`babel.core.Locale` constructor; see :ref:`obtaining_the_locale_name`. For example: @@ -666,7 +664,7 @@ obtain the locale name for a request to pass to the :linenos: from babel.core import Locale - from repoze.bfg.i18n import get_locale_name + from pyramid.i18n import get_locale_name def aview(request): locale_name = get_locale_name(request) @@ -714,20 +712,20 @@ through translation before being rendered: .. 1.2.3 The features represented by attributes of the ``i18n`` namespace of -Chameleon will also consult the :mod:`repoze.bfg` translations. +Chameleon will also consult the :mod:`pyramid` translations. See `http://chameleon.repoze.org/docs/latest/i18n.html#the-i18n-namespace `_. .. note:: - Unlike when Chameleon is used outside of :mod:`repoze.bfg`, when it - is used *within* :mod:`repoze.bfg`, it does not support use of the + Unlike when Chameleon is used outside of :mod:`pyramid`, when it + is used *within* :mod:`pyramid`, it does not support use of the ``zope.i18n`` translation framework. Applications which use - :mod:`repoze.bfg` should use the features documented in this + :mod:`pyramid` should use the features documented in this chapter rather than ``zope.i18n``. -Third party :mod:`repoze.bfg` template renderers might not provide +Third party :mod:`pyramid` template renderers might not provide this support out of the box and may need special code to do an equivalent. For those, you can always use the more manual translation facility described in :ref:`performing_a_translation`. @@ -741,16 +739,16 @@ facility described in :ref:`performing_a_translation`. Localization-Related Deployment Settings ---------------------------------------- -A :mod:`repoze.bfg` application will have a ``default_locale_name`` +A :mod:`pyramid` application will have a ``default_locale_name`` setting. This value represents the :term:`default locale name` used when the :term:`locale negotiator` returns ``None``. Pass it to the -:mod:`repoze.bfg.configuration.Configurator` constructor at startup +:mod:`pyramid.configuration.Configurator` constructor at startup time: .. code-block:: python :linenos: - from repoze.bfg.configuration import Configurator + from pyramid.configuration import Configurator config = Configurator(settings={'default_locale_name':'de'}) You may alternately supply a ``default_locale_name`` via an @@ -769,13 +767,13 @@ application's Paster ``.ini`` file: If this value is not supplied via the Configurator constructor or via a Paste config file, it will default to ``en``. -If this setting is supplied within the :mod:`repoze.bfg` application +If this setting is supplied within the :mod:`pyramid` application ``.ini`` file, it will be available as a settings key: .. code-block:: python :linenos: - from repoze.bfg.setttings import get_settings + from pyramid.setttings import get_settings settings = get_settings() default_locale_name = settings['default_locale_name'] @@ -786,7 +784,7 @@ Other systems provide an API that returns the set of "available languages" as indicated by the union of all languages in all translation directories on disk at the time of the call to the API. -It is by design that :mod:`repoze.bfg` doesn't supply such an API. +It is by design that :mod:`pyramid` doesn't supply such an API. Instead, the application itself is responsible for knowing the "available languages". The rationale is this: any particular application deployment must always know which languages it should be translatable @@ -808,7 +806,7 @@ allowed to be translated to instead of relying on the framework to divine this information from translation directory file info. You can set up a system to allow a deployer to select available -languages based on convention by using the :mod:`repoze.bfg.settings` +languages based on convention by using the :mod:`pyramid.settings` mechanism: Allow a deployer to modify your application's PasteDeploy .ini file: @@ -824,7 +822,7 @@ Then as a part of the code of a custom :term:`locale negotiator`: .. code-block:: py - from repoze.bfg.settings import get_settings + from pyramid.settings import get_settings languages = get_settings()['available_languages'].split() This is only a suggestion. You can create your own "available @@ -840,7 +838,7 @@ languages" configuration scheme as necessary. Activating Translation ---------------------- -By default, a :mod:`repoze.bfg` application performs no translation. +By default, a :mod:`pyramid` application performs no translation. To turn translation on, you must: - add at least one :term:`translation directory` to your application. @@ -851,7 +849,7 @@ Adding a Translation Directory ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ :term:`gettext` is the underlying machinery behind the -:mod:`repoze.bfg` translation machinery. A translation directory is a +:mod:`pyramid` translation machinery. A translation directory is a directory organized to be useful to :term:`gettext`. A translation directory usually includes a listing of language directories, each of which itself includes an ``LC_MESSAGES`` directory. Each @@ -862,7 +860,7 @@ to provide translations to your application. Adding a :term:`translation directory` registers all of its constituent :term:`message catalog` files (all of the ``.mo`` files found within all ``LC_MESSAGES`` directories within each locale -directory in the translation directory) within your :mod:`repoze.bfg` +directory in the translation directory) within your :mod:`pyramid` application to be available to use for translation services. You may add a translation directory to your application's @@ -871,7 +869,7 @@ configuration using either imperative configuration or ZCML. .. topic:: Using Imperative Configuration You can add a translation directory imperatively by using the - :meth:`repoze.bfg.configuration.Configurator.add_translation_dirs` + :meth:`pyramid.configuration.Configurator.add_translation_dirs` during application startup. For example: @@ -879,7 +877,7 @@ configuration using either imperative configuration or ZCML. .. code-block:: python :linenos: - from repoze.bfg.configuration import Configurator + from pyramid.configuration import Configurator config.begin() config.add_translation_dirs('my.application:locale/', 'another.application:locale/') @@ -887,7 +885,7 @@ configuration using either imperative configuration or ZCML. config.end() A message catalog in a translation directory added via - :meth:`repoze.bfg.configuration.Configurator.add_translation_dirs` + :meth:`pyramid.configuration.Configurator.add_translation_dirs` will be merged into translations from a message catalog added earlier if both translation directories contain translations for the same locale and :term:`translation domain`. @@ -913,7 +911,7 @@ Setting the Locale When the *default locale negotiator* (see :ref:`default_locale_negotiator`) is in use, you can inform -:mod:`repoze.bfg` of the current locale name by doing any of these +:mod:`pyramid` of the current locale name by doing any of these things before any translations need to be performed: - Set the ``_LOCALE_`` attribute of the request to a valid locale name @@ -947,10 +945,10 @@ A :term:`locale negotiator` informs the operation of a :term:`localizer` by telling it what :term:`locale name` is related to a particular request. A locale negotiator is a bit of code which accepts a request and which returns a :term:`locale name`. It is -consulted when :meth:`repoze.bfg.i18n.Localizer.translate` or -:meth:`repoze.bfg.i18n.Localizer.pluralize` is invoked. It is also -consulted when :func:`repoze.bfg.i18n.get_locale_name` or -:func:`repoze.bfg.i18n.negotiate_locale_name` is invoked. +consulted when :meth:`pyramid.i18n.Localizer.translate` or +:meth:`pyramid.i18n.Localizer.pluralize` is invoked. It is also +consulted when :func:`pyramid.i18n.get_locale_name` or +:func:`pyramid.i18n.negotiate_locale_name` is invoked. .. _default_locale_negotiator: @@ -961,7 +959,7 @@ Most applications can make use of the default locale negotiator, which requires no additional coding or configuration. The default locale negotiator implementation named -:class:`repoze.bfg.i18n.default_locale_negotiator` uses the following +:class:`pyramid.i18n.default_locale_negotiator` uses the following set of steps to dermine the locale name. - First, the negotiator looks for the ``_LOCALE_`` attribute of the @@ -1005,7 +1003,7 @@ Here's an implementation of a simple locale negotiator: return locale_name If a locale negotiator returns ``None``, it signifies to -:mod:`repoze.bfg` that the default application locale name should be +:mod:`pyramid` that the default application locale name should be used. You may add your newly created locale negotiator to your application's @@ -1015,7 +1013,7 @@ configuration using either imperative configuration or ZCML. Pass an object which can act as the negotiator (or a :term:`dotted Python name` referring to the object) as the ``locale_negotiator`` - argument of the :class:`repoze.bfg.configuration.Configurator` + argument of the :class:`pyramid.configuration.Configurator` instance during application startup. For example: @@ -1023,11 +1021,11 @@ configuration using either imperative configuration or ZCML. .. code-block:: python :linenos: - from repoze.bfg.configuration import Configurator + from pyramid.configuration import Configurator config = Configurator(locale_negotiator=my_locale_negotiator) Alternately, use the - :meth:`repoze.bfg.configuration.Configurator.set_locale_negotiator` + :meth:`pyramid.configuration.Configurator.set_locale_negotiator` method. For example: @@ -1035,7 +1033,7 @@ configuration using either imperative configuration or ZCML. .. code-block:: python :linenos: - from repoze.bfg.configuration import Configurator + from pyramid.configuration import Configurator config = Configurator() config.begin() config.set_locale_negotiator(my_locale_negotiator) -- cgit v1.2.3