diff options
Diffstat (limited to 'docs/narr/i18n.rst')
| -rw-r--r-- | docs/narr/i18n.rst | 262 |
1 files changed, 131 insertions, 131 deletions
diff --git a/docs/narr/i18n.rst b/docs/narr/i18n.rst index 382b75b4a..9b838c7f4 100644 --- a/docs/narr/i18n.rst +++ b/docs/narr/i18n.rst @@ -44,10 +44,10 @@ The most primitive way to create a translation string is to use the :class:`pyramid.i18n.TranslationString` callable: .. code-block:: python - :linenos: + :linenos: - from pyramid.i18n import TranslationString - ts = TranslationString('Add') + from pyramid.i18n import TranslationString + ts = TranslationString('Add') This creates a Unicode-like object that is a TranslationString. @@ -66,20 +66,20 @@ object or an ASCII string. The msgid may optionally contain *replacement markers*. For instance: .. code-block:: python - :linenos: + :linenos: - from pyramid.i18n import TranslationString - ts = TranslationString('Add ${number}') + from pyramid.i18n import TranslationString + ts = TranslationString('Add ${number}') Within the string above, ``${number}`` 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 itself: .. code-block:: python - :linenos: + :linenos: - from pyramid.i18n import TranslationString - ts = TranslationString('Add ${number}', mapping={'number':1}) + from pyramid.i18n import TranslationString + ts = TranslationString('Add ${number}', mapping={'number':1}) Any number of replacement markers can be present in the msgid value, any number of times. Only markers which can be replaced by the values in the *mapping* @@ -91,11 +91,11 @@ represents a translation category to disambiguate it from other translations of the same msgid, in case they conflict. .. code-block:: python - :linenos: + :linenos: - from pyramid.i18n import TranslationString - ts = TranslationString('Add ${number}', mapping={'number':1}, - domain='form') + from pyramid.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 the right translator file on the @@ -106,7 +106,7 @@ like this one: .. code-block:: text - locale/de/LC_MESSAGES/form.mo + 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. @@ -120,10 +120,10 @@ files, so it is often useful to create translation strings with "opaque" message identifiers unrelated to their default text: .. code-block:: python - :linenos: + :linenos: - from pyramid.i18n import TranslationString - ts = TranslationString('add-number', default='Add ${number}', + from pyramid.i18n import TranslationString + ts = TranslationString('add-number', default='Add ${number}', domain='form', mapping={'number':1}) When default text is used, Default text objects may contain replacement values. @@ -141,11 +141,11 @@ the ``domain`` value of any :term:`translation string` generated by using it. For example: .. code-block:: python - :linenos: + :linenos: - from pyramid.i18n import TranslationStringFactory - _ = TranslationStringFactory('pyramid') - ts = _('add-number', default='Add ${number}', mapping={'number':1}) + from pyramid.i18n import TranslationStringFactory + _ = TranslationStringFactory('pyramid') + ts = _('add-number', default='Add ${number}', mapping={'number':1}) .. note:: We assigned the translation string factory to the name ``_``. This is a convention which will be supported by translation file generation @@ -161,11 +161,11 @@ resulting translation string will be ``pyramid``. As a result, the previous code example is completely equivalent (except for spelling) to: .. code-block:: python - :linenos: + :linenos: - from pyramid.i18n import TranslationString as _ - ts = _('add-number', default='Add ${number}', mapping={'number':1}, - domain='pyramid') + from pyramid.i18n import TranslationString as _ + ts = _('add-number', default='Add ${number}', mapping={'number':1}, + domain='pyramid') You can set up your own translation string factory much like the one provided above by using the :class:`~pyramid.i18n.TranslationStringFactory` class. For @@ -174,11 +174,11 @@ example, if you'd like to create a translation string factory which presets the something like this: .. code-block:: python - :linenos: + :linenos: - from pyramid.i18n import TranslationStringFactory - _ = TranslationStringFactory('form') - ts = _('add-number', default='Add ${number}', mapping={'number':1}) + from pyramid.i18n import TranslationStringFactory + _ = TranslationStringFactory('form') + ts = _('add-number', default='Add ${number}', mapping={'number':1}) Creating a unique domain for your application via a translation string factory is best practice. Using your own unique translation domain allows another @@ -256,10 +256,10 @@ In order for the commands related to working with ``gettext`` translation files to work properly, you will need to have :term:`Lingua` and :term:`Gettext` installed into the same environment in which :app:`Pyramid` is installed. -Installation on UNIX +Installation on Unix ++++++++++++++++++++ -Gettext is often already installed on UNIX systems. You can check if it is +Gettext is often already installed on Unix systems. You can check if it is installed by testing if the ``msgfmt`` command is available. If it is not available you can install it through the packaging system from your OS; the package name is almost always ``gettext``. For example on a Debian or Ubuntu @@ -267,7 +267,7 @@ system run this command: .. code-block:: bash - $ sudo apt-get install gettext + sudo apt-get install gettext Installing Lingua is done with the Python packaging tools. If the :term:`virtual environment` into which you've installed your :app:`Pyramid` @@ -276,7 +276,7 @@ like so: .. code-block:: bash - $ $VENV/bin/pip install lingua + $VENV/bin/pip install lingua Installation on Windows +++++++++++++++++++++++ @@ -294,7 +294,7 @@ Lingua like so: .. code-block:: doscon - c:\> %VENV%\Scripts\pip install lingua + %VENV%\Scripts\pip install lingua .. index:: @@ -311,9 +311,9 @@ application. You run a ``pot-create`` command to extract the messages: .. code-block:: bash - $ cd /file/path/to/myapplication_setup.py - $ mkdir -p myapplication/locale - $ $VENV/bin/pot-create -o myapplication/locale/myapplication.pot src + cd /file/path/to/myapplication_setup.py + mkdir -p myapplication/locale + $VENV/bin/pot-create -o myapplication/locale/myapplication.pot src The message catalog ``.pot`` template will end up in ``myapplication/locale/myapplication.pot``. @@ -334,10 +334,10 @@ template by using the ``msginit`` command from Gettext: .. code-block:: bash - $ cd /file/path/to/myapplication_setup.py - $ cd myapplication/locale - $ mkdir -p es/LC_MESSAGES - $ msginit -l es -o es/LC_MESSAGES/myapplication.po + cd /file/path/to/myapplication_setup.py + cd myapplication/locale + mkdir -p es/LC_MESSAGES + msginit -l es -o es/LC_MESSAGES/myapplication.po This will create a new message catalog ``.po`` file in ``myapplication/locale/es/LC_MESSAGES/myapplication.po``. @@ -365,9 +365,9 @@ the ``msgmerge`` command from Gettext. .. code-block:: bash - $ cd /file/path/to/myapplication_setup.py - $ cd myapplication/locale - $ msgmerge --update es/LC_MESSAGES/myapplication.po myapplication.pot + cd /file/path/to/myapplication_setup.py + cd myapplication/locale + msgmerge --update es/LC_MESSAGES/myapplication.po myapplication.pot .. index:: pair: compiling; message catalog @@ -383,9 +383,9 @@ Gettext: .. code-block:: bash - $ cd /file/path/to/myapplication_setup.py - $ msgfmt -o myapplication/locale/es/LC_MESSAGES/myapplication.mo \ - myapplication/locale/es/LC_MESSAGES/myapplication.po + cd /file/path/to/myapplication_setup.py + msgfmt -o myapplication/locale/es/LC_MESSAGES/myapplication.mo \ + myapplication/locale/es/LC_MESSAGES/myapplication.po 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 @@ -409,10 +409,10 @@ translations implied by the active :term:`locale negotiator`, or a default localizer object if no explicit locale negotiator is registered. .. code-block:: python - :linenos: + :linenos: - def aview(request): - localizer = request.localizer + def aview(request): + localizer = request.localizer .. note:: @@ -433,17 +433,17 @@ object representing the translation. Generating a translation in a view component of an application might look like so: .. code-block:: python - :linenos: + :linenos: - from pyramid.i18n import TranslationString + from pyramid.i18n import TranslationString - ts = TranslationString('Add ${number}', mapping={'number':1}, - domain='pyramid') + ts = TranslationString('Add ${number}', mapping={'number':1}, + domain='pyramid') - def aview(request): - localizer = request.localizer - translated = localizer.translate(ts) # translation string - # ... use translated ... + def aview(request): + localizer = request.localizer + translated = localizer.translate(ts) # translation string + # ... use translated ... The ``request.localizer`` attribute will be a :class:`pyramid.i18n.Localizer` object bound to the locale name represented by the request. The translation @@ -467,22 +467,22 @@ Performing a Pluralization A :term:`localizer` has a ``pluralize`` method with the following signature: .. code-block:: python - :linenos: + :linenos: - def pluralize(singular, plural, n, domain=None, mapping=None): - ... + def pluralize(singular, plural, n, domain=None, mapping=None): + # ... The simplest case is the ``singular`` and ``plural`` arguments being passed as Unicode literals. This returns the appropriate literal according to the locale pluralization rules for the number ``n``, and interpolates ``mapping``. .. code-block:: python - :linenos: + :linenos: - def aview(request): - localizer = request.localizer - translated = localizer.pluralize('Item', 'Items', 1, 'mydomain') - # ... use translated ... + def aview(request): + localizer = request.localizer + translated = localizer.pluralize('Item', 'Items', 1, 'mydomain') + # ... use translated ... However, for support of other languages, the ``singular`` argument should be a Unicode value representing a :term:`message identifier`. In this case the @@ -499,13 +499,13 @@ The argument provided as ``singular`` may be a :term:`translation string` object, but the domain and mapping information attached is ignored. .. code-block:: python - :linenos: + :linenos: - def aview(request): - localizer = request.localizer - num = 1 - translated = localizer.pluralize('item_plural', '${number} items', - num, 'mydomain', mapping={'number':num}) + def aview(request): + localizer = request.localizer + num = 1 + translated = localizer.pluralize('item_plural', '${number} items', + num, 'mydomain', mapping={'number':num}) The corresponding message catalog must have language plural definitions and plural alternatives set. @@ -537,10 +537,10 @@ You can obtain the locale name related to a request by using the :func:`pyramid.request.Request.locale_name` attribute of the request. .. code-block:: python - :linenos: + :linenos: - def aview(request): - locale_name = request.locale_name + def aview(request): + locale_name = request.locale_name The locale name of a request is dynamically computed; it will be the locale name negotiated by the currently active :term:`locale negotiator`, or the @@ -555,22 +555,22 @@ without invoking the :term:`locale negotiator`. To avoid this caching, you can use the :func:`pyramid.i18n.negotiate_locale_name` function: .. code-block:: python - :linenos: + :linenos: - from pyramid.i18n import negotiate_locale_name + from pyramid.i18n import negotiate_locale_name - def aview(request): - locale_name = negotiate_locale_name(request) + def aview(request): + locale_name = negotiate_locale_name(request) You can also obtain the locale name related to a request using the ``locale_name`` attribute of a :term:`localizer`. .. code-block:: python - :linenos: + :linenos: - def aview(request): - localizer = request.localizer - locale_name = localizer.locale_name + def aview(request): + localizer = request.localizer + locale_name = localizer.locale_name Obtaining the locale name as an attribute of a localizer is equivalent to obtaining a locale name by asking for the @@ -597,13 +597,13 @@ locale name for a request to pass to the :class:`babel.core.Locale` constructor. See :ref:`obtaining_the_locale_name`. For example: .. code-block:: python - :linenos: + :linenos: - from babel.core import Locale + from babel.core import Locale - def aview(request): - locale_name = request.locale_name - locale = Locale(locale_name) + def aview(request): + locale_name = request.locale_name + locale = Locale(locale_name) .. index:: pair: translation strings; Chameleon @@ -623,24 +623,24 @@ For example, in a Chameleon ZPT template, the translation string represented by before being rendered: .. code-block:: xml - :linenos: + :linenos: - <span tal:content="some_translation_string"/> + <span tal:content="some_translation_string"/> .. code-block:: xml - :linenos: + :linenos: - <span tal:replace="some_translation_string"/> + <span tal:replace="some_translation_string"/> .. code-block:: xml - :linenos: + :linenos: - <span>${some_translation_string}</span> + <span>${some_translation_string}</span> .. code-block:: xml - :linenos: + :linenos: - <a tal:attributes="href some_translation_string">Click here</a> + <a tal:attributes="href some_translation_string">Click here</a> .. XXX the last example above appears to not yet work as of Chameleon .. 1.2.3 @@ -701,23 +701,23 @@ setting. This value represents the :term:`default locale name` used when the :mod:`~pyramid.config.Configurator` constructor at startup time: .. code-block:: python - :linenos: + :linenos: - from pyramid.config import Configurator - config = Configurator(settings={'pyramid.default_locale_name':'de'}) + from pyramid.config import Configurator + config = Configurator(settings={'pyramid.default_locale_name':'de'}) You may alternately supply a ``pyramid.default_locale_name`` via an application's ``.ini`` file: .. code-block:: ini - :linenos: + :linenos: - [app:main] - use = egg:MyProject - pyramid.reload_templates = true - pyramid.debug_authorization = false - pyramid.debug_notfound = false - pyramid.default_locale_name = de + [app:main] + use = egg:MyProject + pyramid.reload_templates = true + pyramid.debug_authorization = false + pyramid.debug_notfound = false + pyramid.default_locale_name = de If this value is not supplied via the Configurator constructor or via a config file, it will default to ``en``. @@ -726,11 +726,11 @@ If this setting is supplied within the :app:`Pyramid` application ``.ini`` file, it will be available as a settings key: .. code-block:: python - :linenos: + :linenos: - from pyramid.threadlocal import get_current_registry - settings = get_current_registry().settings - default_locale_name = settings['pyramid.default_locale_name'] + from pyramid.threadlocal import get_current_registry + settings = get_current_registry().settings + default_locale_name = settings['pyramid.default_locale_name'] .. index:: single: detecting languages @@ -768,23 +768,23 @@ on convention by using the :mod:`pyramid.settings` mechanism. Allow a deployer to modify your application's ``.ini`` file: .. code-block:: ini - :linenos: + :linenos: - [app:main] - use = egg:MyProject - # ... - available_languages = fr de en ru + [app:main] + use = egg:MyProject + # ... + available_languages = fr de en ru Then as a part of the code of a custom :term:`locale negotiator`: .. code-block:: python - :linenos: + :linenos: - from pyramid.settings import aslist + from pyramid.settings import aslist - def my_locale_negotiator(request): - languages = aslist(request.registry.settings['available_languages']) - # ... + def my_locale_negotiator(request): + languages = aslist(request.registry.settings['available_languages']) + # ... This is only a suggestion. You can create your own "available languages" configuration scheme as necessary. @@ -836,11 +836,11 @@ You can add a translation directory imperatively by using the startup. For example: .. code-block:: python - :linenos: + :linenos: - from pyramid.config import Configurator - config.add_translation_dirs('my.application:locale/', - 'another.application:locale/') + from pyramid.config import Configurator + config.add_translation_dirs('my.application:locale/', + 'another.application:locale/') A message catalog in a translation directory added via :meth:`~pyramid.config.Configurator.add_translation_dirs` will be merged into @@ -955,10 +955,10 @@ configuration by passing an object which can act as the negotiator (or a instance during application startup. For example: .. code-block:: python - :linenos: + :linenos: - from pyramid.config import Configurator - config = Configurator(locale_negotiator=my_locale_negotiator) + from pyramid.config import Configurator + config = Configurator(locale_negotiator=my_locale_negotiator) Alternatively, use the :meth:`pyramid.config.Configurator.set_locale_negotiator` method. @@ -966,8 +966,8 @@ Alternatively, use the For example: .. code-block:: python - :linenos: + :linenos: - from pyramid.config import Configurator - config = Configurator() - config.set_locale_negotiator(my_locale_negotiator) + from pyramid.config import Configurator + config = Configurator() + config.set_locale_negotiator(my_locale_negotiator) |