From 6ce1e0cf1a141767ee0aca70786c15dd993347c5 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Wed, 20 Jul 2011 06:10:38 -0400 Subject: add more index markers --- docs/narr/i18n.rst | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+) (limited to 'docs/narr/i18n.rst') diff --git a/docs/narr/i18n.rst b/docs/narr/i18n.rst index c21a19b5b..924fb047a 100644 --- a/docs/narr/i18n.rst +++ b/docs/narr/i18n.rst @@ -353,6 +353,9 @@ The message catalog ``.pot`` template will end up in: ``myapplication/locale/myapplication.pot``. +.. index:: + single: translation domains + Translation Domains +++++++++++++++++++ @@ -494,6 +497,8 @@ translations will be available to :app:`Pyramid`. .. index:: single: localizer single: get_localizer + single: translation + single: pluralization Using a Localizer ----------------- @@ -744,6 +749,9 @@ 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`. +.. index:: + single: Mako i18n + Mako Pyramid I18N Support ------------------------- @@ -798,6 +806,9 @@ If this setting is supplied within the :app:`Pyramid` application settings = get_current_registry().settings default_locale_name = settings['default_locale_name'] +.. index:: + single: detecting langauges + "Detecting" Available Languages ------------------------------- @@ -857,6 +868,9 @@ languages" configuration scheme as necessary. pair: locale; negotiator single: translation directory +.. index:: + pair: activating; translation + .. _activating_translation: Activating Translation @@ -869,6 +883,9 @@ To turn translation on, you must: - ensure that your application sets the :term:`locale name` correctly. +.. index:: + pair: translation directory; adding + .. _adding_a_translation_directory: Adding a Translation Directory @@ -906,6 +923,9 @@ 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`. +.. index:: + pair: setting; locale + Setting the Locale ~~~~~~~~~~~~~~~~~~ @@ -936,6 +956,9 @@ things before any translations need to be performed: function into that application as required. See :ref:`custom_locale_negotiator`. +.. index:: + single: locale negotiator + .. _locale_negotiators: Locale Negotiators -- cgit v1.2.3 From 875ded31e7fdd0c85d1c91458248581b9dd729d7 Mon Sep 17 00:00:00 2001 From: Michael Merickel Date: Sat, 30 Jul 2011 01:50:24 -0600 Subject: Updated all of the docs to reflect the new pyramid.* settings prefix. --- docs/narr/i18n.rst | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) (limited to 'docs/narr/i18n.rst') diff --git a/docs/narr/i18n.rst b/docs/narr/i18n.rst index 924fb047a..ba5490b31 100644 --- a/docs/narr/i18n.rst +++ b/docs/narr/i18n.rst @@ -623,7 +623,7 @@ You can obtain the locale name related to a request by using the This returns the locale name negotiated by the currently active :term:`locale negotiator` or the :term:`default locale name` if the locale negotiator returns ``None``. You can change the default locale -name by changing the ``default_locale_name`` setting; see +name by changing the ``pyramid.default_locale_name`` setting; see :ref:`default_locale_name_setting`. Once :func:`~pyramid.i18n.get_locale_name` is first run, the locale @@ -768,7 +768,7 @@ Internationalization" which explains how to add idiomatic I18N support to Localization-Related Deployment Settings ---------------------------------------- -A :app:`Pyramid` application will have a ``default_locale_name`` +A :app:`Pyramid` application will have a ``pyramid.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:`~pyramid.config.Configurator` constructor at startup @@ -778,9 +778,9 @@ time: :linenos: from pyramid.config import Configurator - config = Configurator(settings={'default_locale_name':'de'}) + config = Configurator(settings={'pyramid.default_locale_name':'de'}) -You may alternately supply a ``default_locale_name`` via an +You may alternately supply a ``pyramid.default_locale_name`` via an application's Paster ``.ini`` file: .. code-block:: ini @@ -788,10 +788,10 @@ application's Paster ``.ini`` file: [app:main] use = egg:MyProject#app - reload_templates = true - debug_authorization = false - debug_notfound = false - default_locale_name = de + 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 Paste config file, it will default to ``en``. @@ -804,7 +804,7 @@ If this setting is supplied within the :app:`Pyramid` application from pyramid.threadlocal import get_current_registry settings = get_current_registry().settings - default_locale_name = settings['default_locale_name'] + default_locale_name = settings['pyramid.default_locale_name'] .. index:: single: detecting langauges -- cgit v1.2.3 From 3d338ea5737b7c113b17120b40684e2694cf3fa9 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Mon, 22 Aug 2011 02:16:55 -0400 Subject: - Use [app:main] instead of a pipeline in all scaffolds and tutorials and narrative docs. - Break out awkward description of PasteDeploy entry points from project chapter into its own Paste chapter. --- docs/narr/i18n.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs/narr/i18n.rst') diff --git a/docs/narr/i18n.rst b/docs/narr/i18n.rst index ba5490b31..aef9b59ab 100644 --- a/docs/narr/i18n.rst +++ b/docs/narr/i18n.rst @@ -787,7 +787,7 @@ application's Paster ``.ini`` file: :linenos: [app:main] - use = egg:MyProject#app + use = egg:MyProject pyramid.reload_templates = true pyramid.debug_authorization = false pyramid.debug_notfound = false @@ -847,7 +847,7 @@ Allow a deployer to modify your application's PasteDeploy .ini file: :linenos: [app:main] - use = egg:MyProject#app + use = egg:MyProject # ... available_languages = fr de en ru -- cgit v1.2.3 From 012b9762cd0b114b6afbf2d6356554b51706804a Mon Sep 17 00:00:00 2001 From: michr Date: Fri, 23 Sep 2011 18:48:28 -0700 Subject: fixed up all the warning dealing ..note and ..warn added a hide toc for glossary to prevent warnings --- docs/narr/i18n.rst | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) (limited to 'docs/narr/i18n.rst') diff --git a/docs/narr/i18n.rst b/docs/narr/i18n.rst index aef9b59ab..bac86e982 100644 --- a/docs/narr/i18n.rst +++ b/docs/narr/i18n.rst @@ -518,7 +518,9 @@ negotiator is registered. def aview(request): locale = get_localizer(request) -.. note:: If you need to create a localizer for a locale use the +.. note:: + + If you need to create a localizer for a locale use the :func:`pyramid.i18n.make_localizer` function. .. index:: @@ -555,7 +557,9 @@ represented by the request. The translation returned from its ``domain`` attribute of the provided translation string as well as the locale of the localizer. -.. note:: If you're using :term:`Chameleon` templates, you don't need +.. note:: + + If you're using :term:`Chameleon` templates, you don't need to pre-translate translation strings this way. See :ref:`chameleon_translation_strings`. -- cgit v1.2.3 From f8869cb0664506204b22aa791003a6d5f8ded58c Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Thu, 6 Oct 2011 03:22:35 -0400 Subject: remove stray references to Paste --- docs/narr/i18n.rst | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) (limited to 'docs/narr/i18n.rst') diff --git a/docs/narr/i18n.rst b/docs/narr/i18n.rst index bac86e982..c2ecba9bb 100644 --- a/docs/narr/i18n.rst +++ b/docs/narr/i18n.rst @@ -365,10 +365,10 @@ be performed to localize your application. By default, the translation domain is the :term:`project` name of your :app:`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 :app:`Pyramid` application -has stanzas in it that look something like the following: +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 ``pcreate`` -generated :app:`Pyramid` application has stanzas in it +that look something like the following: .. code-block:: ini :linenos: @@ -785,7 +785,7 @@ time: config = Configurator(settings={'pyramid.default_locale_name':'de'}) You may alternately supply a ``pyramid.default_locale_name`` via an -application's Paster ``.ini`` file: +application's ``.ini`` file: .. code-block:: ini :linenos: @@ -797,8 +797,8 @@ application's Paster ``.ini`` file: pyramid.debug_notfound = false pyramid.default_locale_name = de -If this value is not supplied via the Configurator constructor or via -a Paste config file, it will default to ``en``. +If this value is not supplied via the Configurator constructor or via a +config file, it will default to ``en``. If this setting is supplied within the :app:`Pyramid` application ``.ini`` file, it will be available as a settings key: @@ -845,7 +845,7 @@ You can set up a system to allow a deployer to select available languages based on convention by using the :mod:`pyramid.settings` mechanism: -Allow a deployer to modify your application's PasteDeploy .ini file: +Allow a deployer to modify your application's ``.ini`` file: .. code-block:: ini :linenos: -- cgit v1.2.3 From c1265329e28bc513a2304fd451e727d9bc95f7ba Mon Sep 17 00:00:00 2001 From: Michael Merickel Date: Fri, 14 Oct 2011 14:39:15 -0500 Subject: fixed translationstring docs, default is not the first argument --- docs/narr/i18n.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'docs/narr/i18n.rst') diff --git a/docs/narr/i18n.rst b/docs/narr/i18n.rst index c2ecba9bb..631654d32 100644 --- a/docs/narr/i18n.rst +++ b/docs/narr/i18n.rst @@ -149,7 +149,7 @@ generated by using it. For example: from pyramid.i18n import TranslationStringFactory _ = TranslationStringFactory('pyramid') - ts = _('Add ${number}', msgid='add-number', mapping={'number':1}) + 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 @@ -170,7 +170,7 @@ to: :linenos: from pyramid.i18n import TranslationString as _ - ts = _('Add ${number}', msgid='add-number', mapping={'number':1}, + ts = _('add-number', default='Add ${number}', mapping={'number':1}, domain='pyramid') You can set up your own translation string factory much like the one @@ -185,7 +185,7 @@ do something like this: from pyramid.i18n import TranslationStringFactory _ = TranslationStringFactory('form') - ts = _('Add ${number}', msgid='add-number', mapping={'number':1}) + 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 -- cgit v1.2.3 From e980bac6aa7715c11b8a618c7486fe9331251103 Mon Sep 17 00:00:00 2001 From: Michael Merickel Date: Mon, 24 Oct 2011 09:42:02 -0500 Subject: garden --- docs/narr/i18n.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/narr/i18n.rst') diff --git a/docs/narr/i18n.rst b/docs/narr/i18n.rst index 631654d32..c5e6a9062 100644 --- a/docs/narr/i18n.rst +++ b/docs/narr/i18n.rst @@ -249,7 +249,7 @@ GNU gettext uses three types of files in the translation framework, The tools for working with :term:`gettext` translation files related to a :app:`Pyramid` application is :term:`Babel` and :term:`Lingua`. Lingua is a -Balel extension that provides support for scraping i18n references out of +Babel extension that provides support for scraping i18n references out of Python and Chameleon files. .. index:: -- cgit v1.2.3 From dca45cea4e3d968b89dc62234f3d8d8392614da6 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Fri, 9 Dec 2011 04:36:39 -0500 Subject: fix bare python mentions --- docs/narr/i18n.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) (limited to 'docs/narr/i18n.rst') diff --git a/docs/narr/i18n.rst b/docs/narr/i18n.rst index c5e6a9062..e261f9a11 100644 --- a/docs/narr/i18n.rst +++ b/docs/narr/i18n.rst @@ -347,7 +347,7 @@ extract the messages: $ cd /place/where/myapplication/setup.py/lives $ mkdir -p myapplication/locale - $ python setup.py extract_messages + $ $myvenv/bin/python setup.py extract_messages The message catalog ``.pot`` template will end up in: @@ -439,7 +439,7 @@ init_catalog`` command: .. code-block:: text $ cd /place/where/myapplication/setup.py/lives - $ python setup.py init_catalog -l es + $ $myvenv/bin/python setup.py init_catalog -l es By default, the message catalog ``.po`` file will end up in: @@ -471,7 +471,7 @@ Then use the ``setup.py update_catalog`` command. .. code-block:: text $ cd /place/where/myapplication/setup.py/lives - $ python setup.py update_catalog + $ $myvenv/bin/python setup.py update_catalog .. index:: pair: compiling; message catalog @@ -487,7 +487,7 @@ translations, compile ``.po`` files to ``.mo`` files: .. code-block:: text $ cd /place/where/myapplication/setup.py/lives - $ python setup.py compile_catalog + $ $myvenv/bin/python setup.py compile_catalog This will create a ``.mo`` file for each ``.po`` file in your application. As long as the :term:`translation directory` in which -- cgit v1.2.3 From 043ccddb909327106264d10ed5d413760a51770d Mon Sep 17 00:00:00 2001 From: Tshepang Lekhonkhobe Date: Wed, 2 Jan 2013 02:22:52 +0200 Subject: eliminate other repeated words --- docs/narr/i18n.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/narr/i18n.rst') diff --git a/docs/narr/i18n.rst b/docs/narr/i18n.rst index e261f9a11..511464322 100644 --- a/docs/narr/i18n.rst +++ b/docs/narr/i18n.rst @@ -301,7 +301,7 @@ You need to add a few boilerplate lines to your application's ``setup.py`` file in order to properly generate :term:`gettext` files from your application. -.. note:: See :ref:`project_narr` to learn about about the +.. note:: See :ref:`project_narr` to learn about the composition of an application's ``setup.py`` file. In particular, add the ``Babel`` and ``lingua`` distributions to the -- cgit v1.2.3 From 75ebabe886bbbe14c873e60597f16531c151a867 Mon Sep 17 00:00:00 2001 From: Tshepang Lekhonkhobe Date: Tue, 19 Feb 2013 23:26:45 +0200 Subject: fix broken link --- docs/narr/i18n.rst | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) (limited to 'docs/narr/i18n.rst') diff --git a/docs/narr/i18n.rst b/docs/narr/i18n.rst index 511464322..24cd3ff54 100644 --- a/docs/narr/i18n.rst +++ b/docs/narr/i18n.rst @@ -736,9 +736,7 @@ through translation before being rendered: The features represented by attributes of the ``i18n`` namespace of Chameleon will also consult the :app:`Pyramid` translations. -See -`http://chameleon.repoze.org/docs/latest/i18n.html#the-i18n-namespace -`_. +See http://chameleon.readthedocs.org/en/latest/reference.html#id50. .. note:: -- cgit v1.2.3 From f73f0e332658fac2583f51247dcd49bd36d63ce4 Mon Sep 17 00:00:00 2001 From: Tshepang Lekhonkhobe Date: Wed, 13 Mar 2013 23:05:17 +0200 Subject: consistency: use $VENV whenever virtualenv binaries are used --- docs/narr/i18n.rst | 13 ++++++------- 1 file changed, 6 insertions(+), 7 deletions(-) (limited to 'docs/narr/i18n.rst') diff --git a/docs/narr/i18n.rst b/docs/narr/i18n.rst index 24cd3ff54..74765f8e2 100644 --- a/docs/narr/i18n.rst +++ b/docs/narr/i18n.rst @@ -276,7 +276,7 @@ like so: .. code-block:: text $ cd /my/virtualenv - $ bin/easy_install Babel lingua + $ $VENV/bin/easy_install Babel lingua Installation on Windows +++++++++++++++++++++++ @@ -287,8 +287,7 @@ like so: .. code-block:: text - C> cd \my\virtualenv - C> Scripts\easy_install Babel lingua + C> %VENV%\Scripts\easy_install Babel lingua .. index:: single: Babel; message extractors @@ -347,7 +346,7 @@ extract the messages: $ cd /place/where/myapplication/setup.py/lives $ mkdir -p myapplication/locale - $ $myvenv/bin/python setup.py extract_messages + $ $VENV/bin/python setup.py extract_messages The message catalog ``.pot`` template will end up in: @@ -439,7 +438,7 @@ init_catalog`` command: .. code-block:: text $ cd /place/where/myapplication/setup.py/lives - $ $myvenv/bin/python setup.py init_catalog -l es + $ $VENV/bin/python setup.py init_catalog -l es By default, the message catalog ``.po`` file will end up in: @@ -471,7 +470,7 @@ Then use the ``setup.py update_catalog`` command. .. code-block:: text $ cd /place/where/myapplication/setup.py/lives - $ $myvenv/bin/python setup.py update_catalog + $ $VENV/bin/python setup.py update_catalog .. index:: pair: compiling; message catalog @@ -487,7 +486,7 @@ translations, compile ``.po`` files to ``.mo`` files: .. code-block:: text $ cd /place/where/myapplication/setup.py/lives - $ $myvenv/bin/python setup.py compile_catalog + $ $VENV/bin/python setup.py compile_catalog This will create a ``.mo`` file for each ``.po`` file in your application. As long as the :term:`translation directory` in which -- cgit v1.2.3 From 00f9fe4dc2425d58d4c30253c53695bdf2a21e99 Mon Sep 17 00:00:00 2001 From: tisdall Date: Thu, 8 Aug 2013 14:44:23 -0400 Subject: "langauges" to "languages" --- docs/narr/i18n.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/narr/i18n.rst') diff --git a/docs/narr/i18n.rst b/docs/narr/i18n.rst index 74765f8e2..bb336784f 100644 --- a/docs/narr/i18n.rst +++ b/docs/narr/i18n.rst @@ -808,7 +808,7 @@ If this setting is supplied within the :app:`Pyramid` application default_locale_name = settings['pyramid.default_locale_name'] .. index:: - single: detecting langauges + single: detecting languages "Detecting" Available Languages ------------------------------- -- cgit v1.2.3 From bfd928b5424c49343c6680715013d61bf4991cfa Mon Sep 17 00:00:00 2001 From: tisdall Date: Fri, 9 Aug 2013 14:42:49 -0400 Subject: "dermine" to "determine" --- docs/narr/i18n.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/narr/i18n.rst') diff --git a/docs/narr/i18n.rst b/docs/narr/i18n.rst index bb336784f..2964686d3 100644 --- a/docs/narr/i18n.rst +++ b/docs/narr/i18n.rst @@ -984,7 +984,7 @@ requires no additional coding or configuration. The default locale negotiator implementation named :class:`~pyramid.i18n.default_locale_negotiator` uses the following -set of steps to dermine the locale name. +set of steps to determine the locale name. - First, the negotiator looks for the ``_LOCALE_`` attribute of the request object (possibly set directly by view code or by a listener -- cgit v1.2.3 From 221fff13b01b3419570630e0da1e617c0ed1a2d7 Mon Sep 17 00:00:00 2001 From: Matthew Wilkes Date: Fri, 23 Aug 2013 15:39:32 +0100 Subject: Fix documentation on using gettext plurals and include examples --- docs/narr/i18n.rst | 58 +++++++++++++++++++++++++++++++++++++++++++----------- 1 file changed, 46 insertions(+), 12 deletions(-) (limited to 'docs/narr/i18n.rst') diff --git a/docs/narr/i18n.rst b/docs/narr/i18n.rst index 2964686d3..555b06e0f 100644 --- a/docs/narr/i18n.rst +++ b/docs/narr/i18n.rst @@ -579,18 +579,9 @@ signature: def pluralize(singular, plural, n, domain=None, mapping=None): ... -The ``singular`` and ``plural`` arguments should each be a Unicode -value representing a :term:`message identifier`. ``n`` should be an -integer. ``domain`` should be a :term:`translation domain`, and -``mapping`` should be a dictionary that is used for *replacement -value* interpolation of the translated string. If ``n`` is plural -for the current locale, ``pluralize`` will return a Unicode -translation for the message id ``plural``, otherwise it will return a -Unicode translation for the message id ``singular``. - -The arguments provided as ``singular`` and/or ``plural`` may also be -:term:`translation string` objects, but the domain and mapping -information attached to those objects is ignored. +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: @@ -602,6 +593,49 @@ information attached to those objects is ignored. 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 ``plural`` value is ignored. +``domain`` should be a :term:`translation domain`, and +``mapping`` should be a dictionary that is used for *replacement +value* interpolation of the translated string. + +The value of ``n`` will be used to find the appropriate plural form for the +current language and ``pluralize`` will return a Unicode translation for the +message id ``singular``. The message file must have defined ``singular`` as a +translation with plural forms. + +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: + + from pyramid.i18n import get_localizer + + def aview(request): + localizer = get_localizer(request) + num = 1 + translated = localizer.pluralize(_('item_plural', default="${number} items"), + None, num, 'mydomain', mapping={'number':num}) + +The corresponding message catalog must have language plural definitions and +plural alternatives set. + +.. code-block:: text + :linenos: + + "Plural-Forms: nplurals=3; plural=n==0 ? 0 : n==1 ? 1 : 2;" + + msgid "item_plural" + msgid_plural "" + msgstr[0] "No items" + msgstr[1] "${number} item" + msgstr[2] "${number} items" + +More information on complex plurals can be found in the `gettext documentation +`_. + .. index:: single: locale name single: get_locale_name -- cgit v1.2.3 From 330164c3190d92a3e1df89baafba12570d03bd32 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Thu, 29 Aug 2013 05:08:53 -0400 Subject: make local_name an attribute of Request, move logic from get_localizer into Request.localizer, fix docs; closes #1099 --- docs/narr/i18n.rst | 77 +++++++++++++++++++++++------------------------------- 1 file changed, 32 insertions(+), 45 deletions(-) (limited to 'docs/narr/i18n.rst') diff --git a/docs/narr/i18n.rst b/docs/narr/i18n.rst index 555b06e0f..b62c16ff0 100644 --- a/docs/narr/i18n.rst +++ b/docs/narr/i18n.rst @@ -495,7 +495,6 @@ translations will be available to :app:`Pyramid`. .. index:: single: localizer - single: get_localizer single: translation single: pluralization @@ -503,19 +502,17 @@ 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:`pyramid.i18n.get_localizer` function to obtain a :term:`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. +pluralization "by hand" in an application. You may use the +:attr:`pyramid.request.Request.localizer` attribute to obtain a +:term:`localizer`. The localizer object will be configured to produce +translations implied by the active :term:`locale negotiator` or a default +localizer object if no explicit locale negotiator is registered. .. code-block:: python :linenos: - from pyramid.i18n import get_localizer - def aview(request): - locale = get_localizer(request) + localizer = request.localizer .. note:: @@ -538,22 +535,20 @@ translation in a view component of an application might look like so: .. code-block:: python :linenos: - from pyramid.i18n import get_localizer from pyramid.i18n import TranslationString ts = TranslationString('Add ${number}', mapping={'number':1}, domain='pyramid') def aview(request): - localizer = get_localizer(request) + localizer = request.localizer translated = localizer.translate(ts) # translation string # ... use translated ... -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:`pyramid.i18n.Localizer.translate` method will depend on the -``domain`` attribute of the provided translation string as well as the +The ``request.localizer`` attribute will be a :class:`pyramid.i18n.Localizer` +object bound to the locale name represented by the request. The translation +returned from its :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. .. note:: @@ -586,10 +581,8 @@ pluralization rules for the number ``n``, and interpolates ``mapping``. .. code-block:: python :linenos: - from pyramid.i18n import get_localizer - def aview(request): - localizer = get_localizer(request) + localizer = request.localizer translated = localizer.pluralize('Item', 'Items', 1, 'mydomain') # ... use translated ... @@ -611,13 +604,13 @@ object, but the domain and mapping information attached is ignored. .. code-block:: python :linenos: - from pyramid.i18n import get_localizer - def aview(request): - localizer = get_localizer(request) + localizer = request.localizer num = 1 - translated = localizer.pluralize(_('item_plural', default="${number} items"), - None, num, 'mydomain', mapping={'number':num}) + translated = localizer.pluralize( + _('item_plural', default="${number} items"), + None, num, 'mydomain', mapping={'number':num} + ) The corresponding message catalog must have language plural definitions and plural alternatives set. @@ -638,7 +631,6 @@ More information on complex plurals can be found in the `gettext documentation .. index:: single: locale name - single: get_locale_name single: negotiate_locale_name .. _obtaining_the_locale_name: @@ -647,25 +639,23 @@ Obtaining the Locale Name for a Request --------------------------------------- You can obtain the locale name related to a request by using the -:func:`pyramid.i18n.get_locale_name` function. +:func:`pyramid.request.Request.locale_name` attribute of the request. .. code-block:: python :linenos: - from pyramid.i18n import get_locale_name - def aview(request): - locale_name = get_locale_name(request) + locale_name = request.locale_name -This returns the locale name negotiated by the currently active -:term:`locale negotiator` or the :term:`default locale name` if the -locale negotiator returns ``None``. You can change the default locale -name by changing the ``pyramid.default_locale_name`` setting; see -:ref:`default_locale_name_setting`. +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 :term:`default locale name` if the locale negotiator returns ``None``. +You can change the default locale name by changing the +``pyramid.default_locale_name`` setting; see :ref:`default_locale_name_setting`. -Once :func:`~pyramid.i18n.get_locale_name` is first run, the locale +Once :func:`~pyramid.request.Request.locale_name` is first run, the locale name is stored on the request object. Subsequent calls to -:func:`~pyramid.i18n.get_locale_name` will return the stored locale +:func:`~pyramid.request.Request.locale_name` will return the stored locale name without invoking the :term:`locale negotiator`. To avoid this caching, you can use the :func:`pyramid.i18n.negotiate_locale_name` function: @@ -684,15 +674,13 @@ You can also obtain the locale name related to a request using the .. code-block:: python :linenos: - from pyramid.i18n import get_localizer - def aview(request): - localizer = get_localizer(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 calling the -:func:`~pyramid.i18n.get_locale_name` function. +to obtaining a locale name by asking for the +:func:`~pyramid.request.Request.locale_name` attribute. .. index:: single: date and currency formatting (i18n) @@ -720,10 +708,9 @@ obtain the locale name for a request to pass to the :linenos: from babel.core import Locale - from pyramid.i18n import get_locale_name def aview(request): - locale_name = get_locale_name(request) + locale_name = request.locale_name locale = Locale(locale_name) .. index:: @@ -1005,8 +992,8 @@ 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:`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. +consulted when :func:`~pyramid.request.Request.locale_name` is accessed or +when :func:`~pyramid.i18n.negotiate_locale_name` is invoked. .. _default_locale_negotiator: -- cgit v1.2.3 From 392a6c7df93b67d6889680133fda0f744970d61f Mon Sep 17 00:00:00 2001 From: Antti Haapala Date: Sun, 17 Nov 2013 00:11:37 +0200 Subject: Removed extra indentation from some examples (:linenos: should be indented with the same indentation as the rest of the code block) --- docs/narr/i18n.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) (limited to 'docs/narr/i18n.rst') diff --git a/docs/narr/i18n.rst b/docs/narr/i18n.rst index b62c16ff0..c9b782c08 100644 --- a/docs/narr/i18n.rst +++ b/docs/narr/i18n.rst @@ -309,7 +309,7 @@ In particular, add the ``Babel`` and ``lingua`` distributions to the application's ``setup.py`` file: .. code-block:: python - :linenos: + :linenos: setup(name="mypackage", # ... @@ -370,7 +370,7 @@ file of a ``pcreate`` -generated :app:`Pyramid` application has stanzas in it that look something like the following: .. code-block:: ini - :linenos: + :linenos: [compile_catalog] directory = myproject/locale @@ -398,7 +398,7 @@ that you'd like the domain of your translations to be ``mydomain`` instead, change the ``setup.cfg`` file stanzas to look like so: .. code-block:: ini - :linenos: + :linenos: [compile_catalog] directory = myproject/locale @@ -1041,7 +1041,7 @@ if no locale can be determined. Here's an implementation of a simple locale negotiator: .. code-block:: python - :linenos: + :linenos: def my_locale_negotiator(request): locale_name = request.params.get('my_locale') -- cgit v1.2.3 From 5431138583ee9d4382c1fe6dd0fb706ed514a4bf Mon Sep 17 00:00:00 2001 From: Matthew Wilkes Date: Tue, 10 Dec 2013 20:29:28 +0000 Subject: Use new pluralize calling convention recognised by Lingua 1.7 --- docs/narr/i18n.rst | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) (limited to 'docs/narr/i18n.rst') diff --git a/docs/narr/i18n.rst b/docs/narr/i18n.rst index c9b782c08..5f50ca212 100644 --- a/docs/narr/i18n.rst +++ b/docs/narr/i18n.rst @@ -607,10 +607,8 @@ object, but the domain and mapping information attached is ignored. def aview(request): localizer = request.localizer num = 1 - translated = localizer.pluralize( - _('item_plural', default="${number} items"), - None, num, 'mydomain', mapping={'number':num} - ) + 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. -- cgit v1.2.3 From e4dc7443ddf8e5e3d861c66e0cef565a6d907789 Mon Sep 17 00:00:00 2001 From: Wichert Akkerman Date: Tue, 8 Apr 2014 20:07:59 +0200 Subject: Update documentation for Lingua 2 --- docs/narr/i18n.rst | 182 ++++++++++++++--------------------------------------- 1 file changed, 48 insertions(+), 134 deletions(-) (limited to 'docs/narr/i18n.rst') diff --git a/docs/narr/i18n.rst b/docs/narr/i18n.rst index 5f50ca212..31b63664b 100644 --- a/docs/narr/i18n.rst +++ b/docs/narr/i18n.rst @@ -245,88 +245,69 @@ GNU gettext uses three types of files in the translation framework, A ``.po`` file is turned into a machine-readable binary file, which is the ``.mo`` file. Compiling the translations to machine code - makes the localized program run faster. + makes the localized program start faster. The tools for working with :term:`gettext` translation files related to a -:app:`Pyramid` application is :term:`Babel` and :term:`Lingua`. Lingua is a -Babel extension that provides support for scraping i18n references out of -Python and Chameleon files. +:app:`Pyramid` application are :term:`Lingua` and :term:`Gettext`. Lingua +can scrape i18n references out of Python and Chameleon files and create +the ``.pot`` file. Gettext includes tools to update a ``.po`` file from +an updated ``.pot`` file and to compile ``.po`` files to ``.mo`` files. .. index:: - single: Babel + single: Gettext single: Lingua .. _installing_babel: -Installing Babel and Lingua -~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Installing Lingua and Gettext +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ In order for the commands related to working with ``gettext`` translation -files to work properly, you will need to have :term:`Babel` and -:term:`Lingua` installed into the same environment in which :app:`Pyramid` is +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 ++++++++++++++++++++ -If the :term:`virtualenv` into which you've installed your :app:`Pyramid` -application lives in ``/my/virtualenv``, you can install Babel and Lingua -like so: +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 system run this command: .. code-block:: text - $ cd /my/virtualenv - $ $VENV/bin/easy_install Babel lingua + $ sudo apt-get install gettext -Installation on Windows -+++++++++++++++++++++++ - -If the :term:`virtualenv` into which you've installed your :app:`Pyramid` -application lives in ``C:\my\virtualenv``, you can install Babel and Lingua +Installing Lingua is done with the Python packaging tools. If the +:term:`virtualenv` into which you've installed your :app:`Pyramid` application +lives in ``/my/virtualenv``, you can install Lingua like so: .. code-block:: text - C> %VENV%\Scripts\easy_install Babel lingua + $ cd /my/virtualenv + $ $VENV/bin/pip install lingua -.. index:: - single: Babel; message extractors - single: Lingua +Installation on Windows ++++++++++++++++++++++++ -Changing the ``setup.py`` -+++++++++++++++++++++++++ +There are several ways to install Gettext on Windows: it is included in the +`Cygwin `_ collection, or you can use the `installer +from the GnuWin32 `_ +or compile it yourself. Make sure the installation path is added to your +``$PATH``. -You need to add a few boilerplate lines to your application's ``setup.py`` -file in order to properly generate :term:`gettext` files from your -application. -.. note:: See :ref:`project_narr` to learn about the - composition of an application's ``setup.py`` file. +Installing Lingua is done with the Python packaging tools. If the +:term:`virtualenv` into which you've installed your :app:`Pyramid` application +lives in ``C:\my\virtualenv``, you can install Lingua like so: -In particular, add the ``Babel`` and ``lingua`` distributions to the -``install_requires`` list and insert a set of references to :term:`Babel` -*message extractors* within the call to :func:`setuptools.setup` inside your -application's ``setup.py`` file: +.. code-block:: text -.. code-block:: python - :linenos: + C> %VENV%\Scripts\pip install lingua - setup(name="mypackage", - # ... - install_requires = [ - # ... - 'Babel', - 'lingua', - ], - message_extractors = { '.': [ - ('**.py', 'lingua_python', None ), - ('**.pt', 'lingua_xml', None ), - ]}, - ) - -The ``message_extractors`` stanza placed into the ``setup.py`` file causes -the :term:`Babel` message catalog extraction machinery to also consider -``*.pt`` files when doing message id extraction. .. index:: pair: extracting; messages @@ -336,90 +317,20 @@ the :term:`Babel` message catalog extraction machinery to also consider Extracting Messages from Code and Templates ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Once Babel and Lingua are 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 :app:`Pyramid` application. You run a ``setup.py`` command to -extract the messages: +Once Lingua is installed you may extract a message catalog template from the +code and :term:`Chameleon` templates which reside in your :app:`Pyramid` +application. You run a ``pot-create`` command to extract the messages: .. code-block:: text $ cd /place/where/myapplication/setup.py/lives $ mkdir -p myapplication/locale - $ $VENV/bin/python setup.py extract_messages + $ $VENT/bin/pot-create src > myapplication/locale/myapplication.pot The message catalog ``.pot`` template will end up in: ``myapplication/locale/myapplication.pot``. -.. index:: - single: translation domains - -Translation Domains -+++++++++++++++++++ - -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 -:app:`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 ``pcreate`` -generated :app:`Pyramid` application has stanzas in it -that look something like the following: - -.. code-block:: ini - :linenos: - - [compile_catalog] - directory = myproject/locale - domain = MyProject - statistics = true - - [extract_messages] - add_comments = TRANSLATORS: - output_file = myproject/locale/MyProject.pot - width = 80 - - [init_catalog] - domain = MyProject - input_file = myproject/locale/MyProject.pot - output_dir = myproject/locale - - [update_catalog] - domain = MyProject - input_file = myproject/locale/MyProject.pot - output_dir = myproject/locale - previous = true - -In the above example, the project name is ``MyProject``. To indicate -that you'd like the domain of your translations to be ``mydomain`` -instead, change the ``setup.cfg`` file stanzas to look like so: - -.. code-block:: ini - :linenos: - - [compile_catalog] - directory = myproject/locale - domain = mydomain - statistics = true - - [extract_messages] - add_comments = TRANSLATORS: - output_file = myproject/locale/mydomain.pot - width = 80 - - [init_catalog] - domain = mydomain - input_file = myproject/locale/mydomain.pot - output_dir = myproject/locale - - [update_catalog] - domain = mydomain - input_file = myproject/locale/mydomain.pot - output_dir = myproject/locale - previous = true .. index:: pair: initializing; message catalog @@ -432,15 +343,17 @@ Once you've extracted messages into a ``.pot`` file (see in the ``.pot`` file, you need to generate at least one ``.po`` file. A ``.po`` file represents translations of a particular set of messages to a particular locale. Initialize a ``.po`` file for a specific -locale from a pre-generated ``.pot`` template by using the ``setup.py -init_catalog`` command: +locale from a pre-generated ``.pot`` template by using the ``msginit`` +command: .. code-block:: text $ cd /place/where/myapplication/setup.py/lives - $ $VENV/bin/python setup.py init_catalog -l es + $ cd myapplication/locale + $ mkdir -p es/LC_MESSAGES + $ msginit -l es es/LC_MESSAGES/myapplication.po -By default, the message catalog ``.po`` file will end up in: +This will create a new the message catalog ``.po`` file will in: ``myapplication/locale/es/LC_MESSAGES/myapplication.po``. @@ -465,12 +378,13 @@ files based on changes to the ``.pot`` file, so that the new and changed messages can also be translated or re-translated. First, regenerate the ``.pot`` file as per :ref:`extracting_messages`. -Then use the ``setup.py update_catalog`` command. +Then use the ``msgmerge`` command. .. code-block:: text $ cd /place/where/myapplication/setup.py/lives - $ $VENV/bin/python setup.py update_catalog + $ cd myapplication/locale + $ msgmerge --update es/LC_MESSAGES/myapplication.po myapplication.pot .. index:: pair: compiling; message catalog @@ -481,12 +395,12 @@ Compiling a Message Catalog File ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Finally, to prepare an application for performing actual runtime -translations, compile ``.po`` files to ``.mo`` files: +translations, compile ``.po`` files to ``.mo`` files use the ``msgfmt``: .. code-block:: text $ cd /place/where/myapplication/setup.py/lives - $ $VENV/bin/python setup.py compile_catalog + $ msgfmt myapplication/locale/*/LC_MESSAGES/*.po This will create a ``.mo`` file for each ``.po`` file in your application. As long as the :term:`translation directory` in which -- cgit v1.2.3 From cfaec8b63b271e141789244ad276d3045e00a2a8 Mon Sep 17 00:00:00 2001 From: Wichert Akkerman Date: Tue, 8 Apr 2014 21:01:43 +0200 Subject: Keep using easy_install. --- docs/narr/i18n.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs/narr/i18n.rst') diff --git a/docs/narr/i18n.rst b/docs/narr/i18n.rst index 31b63664b..122f33130 100644 --- a/docs/narr/i18n.rst +++ b/docs/narr/i18n.rst @@ -288,7 +288,7 @@ like so: .. code-block:: text $ cd /my/virtualenv - $ $VENV/bin/pip install lingua + $ $VENV/bin/easy_install lingua Installation on Windows +++++++++++++++++++++++ @@ -306,7 +306,7 @@ lives in ``C:\my\virtualenv``, you can install Lingua like so: .. code-block:: text - C> %VENV%\Scripts\pip install lingua + C> %VENV%\Scripts\easy_install lingua .. index:: -- cgit v1.2.3 From d3a70e5e656eea3f527b56e9f03b6f754731dc4a Mon Sep 17 00:00:00 2001 From: Wichert Akkerman Date: Tue, 8 Apr 2014 21:04:57 +0200 Subject: Fix $VENT typo --- docs/narr/i18n.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/narr/i18n.rst') diff --git a/docs/narr/i18n.rst b/docs/narr/i18n.rst index 122f33130..50e5a6817 100644 --- a/docs/narr/i18n.rst +++ b/docs/narr/i18n.rst @@ -325,7 +325,7 @@ application. You run a ``pot-create`` command to extract the messages: $ cd /place/where/myapplication/setup.py/lives $ mkdir -p myapplication/locale - $ $VENT/bin/pot-create src > myapplication/locale/myapplication.pot + $ $VENV/bin/pot-create src > myapplication/locale/myapplication.pot The message catalog ``.pot`` template will end up in: -- cgit v1.2.3 From 0a4433df3711755170396090d8daa69bfaef76f9 Mon Sep 17 00:00:00 2001 From: Wichert Akkerman Date: Tue, 8 Apr 2014 21:09:34 +0200 Subject: Always mention the msg* commands come from Gettext --- docs/narr/i18n.rst | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) (limited to 'docs/narr/i18n.rst') diff --git a/docs/narr/i18n.rst b/docs/narr/i18n.rst index 50e5a6817..1de2c8941 100644 --- a/docs/narr/i18n.rst +++ b/docs/narr/i18n.rst @@ -250,8 +250,9 @@ GNU gettext uses three types of files in the translation framework, The tools for working with :term:`gettext` translation files related to a :app:`Pyramid` application are :term:`Lingua` and :term:`Gettext`. Lingua can scrape i18n references out of Python and Chameleon files and create -the ``.pot`` file. Gettext includes tools to update a ``.po`` file from -an updated ``.pot`` file and to compile ``.po`` files to ``.mo`` files. +the ``.pot`` file. Gettext includes ``msgmerge`` tool to update a ``.po`` file +from an updated ``.pot`` file and ``msgfmt`` to compile ``.po`` files to +``.mo`` files. .. index:: single: Gettext @@ -344,7 +345,7 @@ in the ``.pot`` file, you need to generate at least one ``.po`` file. A ``.po`` file represents translations of a particular set of messages to a particular locale. Initialize a ``.po`` file for a specific locale from a pre-generated ``.pot`` template by using the ``msginit`` -command: +command from Gettext: .. code-block:: text @@ -378,7 +379,7 @@ files based on changes to the ``.pot`` file, so that the new and changed messages can also be translated or re-translated. First, regenerate the ``.pot`` file as per :ref:`extracting_messages`. -Then use the ``msgmerge`` command. +Then use the ``msgmerge`` command from Gettext. .. code-block:: text @@ -395,7 +396,8 @@ Compiling a Message Catalog File ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Finally, to prepare an application for performing actual runtime -translations, compile ``.po`` files to ``.mo`` files use the ``msgfmt``: +translations, compile ``.po`` files to ``.mo`` files use the ``msgfmt`` +command from Gettext: .. code-block:: text -- cgit v1.2.3 From 5e61602652b2963ee0ef2df30ac81f29c42d3415 Mon Sep 17 00:00:00 2001 From: Alexey Torkhov Date: Mon, 14 Jul 2014 22:49:59 +0400 Subject: Update i18n.rst To set output file for pot-create -o flag should be used, not redirect. --- docs/narr/i18n.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/narr/i18n.rst') diff --git a/docs/narr/i18n.rst b/docs/narr/i18n.rst index 1de2c8941..cb2cd049c 100644 --- a/docs/narr/i18n.rst +++ b/docs/narr/i18n.rst @@ -326,7 +326,7 @@ application. You run a ``pot-create`` command to extract the messages: $ cd /place/where/myapplication/setup.py/lives $ mkdir -p myapplication/locale - $ $VENV/bin/pot-create src > myapplication/locale/myapplication.pot + $ $VENV/bin/pot-create -o myapplication/locale/myapplication.pot src The message catalog ``.pot`` template will end up in: -- cgit v1.2.3 From 4fcbd9e5351bb7ec417cb10ba89dc3af2a6ef9a7 Mon Sep 17 00:00:00 2001 From: Alexey Torkhov Date: Tue, 15 Jul 2014 12:35:13 +0400 Subject: Update i18n.rst msgfmt produces 'messages.mo' file in current dir by default, it needs -o to specify destination. Also, added ref to adding a translation directory. --- docs/narr/i18n.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs/narr/i18n.rst') diff --git a/docs/narr/i18n.rst b/docs/narr/i18n.rst index cb2cd049c..6bfbc5136 100644 --- a/docs/narr/i18n.rst +++ b/docs/narr/i18n.rst @@ -402,11 +402,11 @@ command from Gettext: .. code-block:: text $ cd /place/where/myapplication/setup.py/lives - $ msgfmt myapplication/locale/*/LC_MESSAGES/*.po + $ 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 is configured into your application, these +the ``.mo`` file ends up in is configured into your application (see :ref:`adding_a_translation_directory`), these translations will be available to :app:`Pyramid`. .. index:: -- cgit v1.2.3 From b4245a312bfe7f99080d46c1f9814f2c5da2cbf1 Mon Sep 17 00:00:00 2001 From: nick knouf Date: Tue, 15 Jul 2014 17:04:07 -0400 Subject: Updating to current msginit syntax --- docs/narr/i18n.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/narr/i18n.rst') diff --git a/docs/narr/i18n.rst b/docs/narr/i18n.rst index 6bfbc5136..95f663584 100644 --- a/docs/narr/i18n.rst +++ b/docs/narr/i18n.rst @@ -352,7 +352,7 @@ command from Gettext: $ cd /place/where/myapplication/setup.py/lives $ cd myapplication/locale $ mkdir -p es/LC_MESSAGES - $ msginit -l es es/LC_MESSAGES/myapplication.po + $ msginit -l es -o es/LC_MESSAGES/myapplication.po This will create a new the message catalog ``.po`` file will in: -- cgit v1.2.3 From ddc745ff6497a5c08c44e2fc8f722ad0034948dc Mon Sep 17 00:00:00 2001 From: Tim Tisdall Date: Thu, 14 Aug 2014 10:31:22 -0400 Subject: remove unnecessary use of `get_current_registry()` - We have a request object, so get the current registry properly through it. - make use of the built-in `aslist` function for parsing the result --- docs/narr/i18n.rst | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) (limited to 'docs/narr/i18n.rst') diff --git a/docs/narr/i18n.rst b/docs/narr/i18n.rst index 95f663584..3313f8dad 100644 --- a/docs/narr/i18n.rst +++ b/docs/narr/i18n.rst @@ -792,9 +792,11 @@ Then as a part of the code of a custom :term:`locale negotiator`: .. code-block:: python :linenos: - from pyramid.threadlocal import get_current_registry - settings = get_current_registry().settings - languages = settings['available_languages'].split() + from pyramid.settings import aslist + + 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. -- cgit v1.2.3 From 555969e05458b2e19305fd0a4f15ac3d27d3a90c Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Tue, 11 Nov 2014 00:50:29 -0800 Subject: fix grammar --- docs/narr/i18n.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/narr/i18n.rst') diff --git a/docs/narr/i18n.rst b/docs/narr/i18n.rst index 3313f8dad..3c804a158 100644 --- a/docs/narr/i18n.rst +++ b/docs/narr/i18n.rst @@ -354,7 +354,7 @@ command from Gettext: $ mkdir -p es/LC_MESSAGES $ msginit -l es -o es/LC_MESSAGES/myapplication.po -This will create a new the message catalog ``.po`` file will in: +This will create a new message catalog ``.po`` file in: ``myapplication/locale/es/LC_MESSAGES/myapplication.po``. -- cgit v1.2.3 From 82862ba554ff97932b5f6745c8e6b022dcdfe18c Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Tue, 1 Sep 2015 02:42:05 -0700 Subject: - add pylonswebframework to intersphinx config, sort entries so they can be found (meh! 79 char columns) - replace final pylonshq reference with RTD reference --- docs/narr/i18n.rst | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) (limited to 'docs/narr/i18n.rst') diff --git a/docs/narr/i18n.rst b/docs/narr/i18n.rst index 3c804a158..8d81418d9 100644 --- a/docs/narr/i18n.rst +++ b/docs/narr/i18n.rst @@ -219,10 +219,9 @@ by creating various kinds of gettext files. The steps a developer must take to work with :term:`gettext` :term:`message catalog` files within a :app:`Pyramid` application are very similar to the steps a :term:`Pylons` - developer must take to do the same. See the `Pylons - internationalization documentation - `_ - for more information. + developer must take to do the same. See the :ref:`Pylons + Internationalization and Localization documentation + ` for more information. GNU gettext uses three types of files in the translation framework, ``.pot`` files, ``.po`` files and ``.mo`` files. -- cgit v1.2.3 From 02801e33f5a11d069921e1a16933a0225fad45bc Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Thu, 1 Oct 2015 13:43:54 -0700 Subject: wrap to 79 chars --- docs/narr/i18n.rst | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) (limited to 'docs/narr/i18n.rst') diff --git a/docs/narr/i18n.rst b/docs/narr/i18n.rst index 8d81418d9..7b6903d01 100644 --- a/docs/narr/i18n.rst +++ b/docs/narr/i18n.rst @@ -403,10 +403,11 @@ command from Gettext: $ cd /place/where/myapplication/setup.py/lives $ 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 is configured into your application (see :ref:`adding_a_translation_directory`), these -translations will be available to :app:`Pyramid`. +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 (see +:ref:`adding_a_translation_directory`), these translations will be available +to :app:`Pyramid`. .. index:: single: localizer -- cgit v1.2.3 From d2b365b3cf9185fd979dbb2c2692499ede706513 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Tue, 20 Oct 2015 00:01:16 -0700 Subject: minor grammar, rewrap 79 columns --- docs/narr/i18n.rst | 632 +++++++++++++++++++++++++---------------------------- 1 file changed, 297 insertions(+), 335 deletions(-) (limited to 'docs/narr/i18n.rst') diff --git a/docs/narr/i18n.rst b/docs/narr/i18n.rst index 7b6903d01..bb0bbe511 100644 --- a/docs/narr/i18n.rst +++ b/docs/narr/i18n.rst @@ -9,16 +9,16 @@ Internationalization and Localization ===================================== -:term:`Internationalization` (i18n) is the act of creating software -with a user interface that can potentially be displayed in more than -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. +:term:`Internationalization` (i18n) is the act of creating software with a user +interface that can potentially be displayed in more than 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. -:app:`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. +:app:`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. .. index:: single: translation string @@ -29,15 +29,15 @@ native language of a user of your application. 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 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 :app:`Pyramid` translation machinery. +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 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 :app:`Pyramid` translation +machinery. -Using The ``TranslationString`` Class +Using the ``TranslationString`` Class ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The most primitive way to create a translation string is to use the @@ -53,17 +53,17 @@ This creates a Unicode-like object that is a TranslationString. .. note:: - For people more familiar with :term:`Zope` i18n, a TranslationString - is a lot like a ``zope.i18nmessageid.Message`` object. It is not a - subclass, however. For people more familiar with :term:`Pylons` or - :term:`Django` i18n, using a TranslationString is a lot like using - "lazy" versions of related gettext APIs. + For people more familiar with :term:`Zope` i18n, a TranslationString is a + lot like a ``zope.i18nmessageid.Message`` object. It is not a subclass, + however. For people more familiar with :term:`Pylons` or :term:`Django` + i18n, using a TranslationString is a lot like using "lazy" versions of + related gettext APIs. -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 -msgid may optionally contain *replacement markers*. For instance: +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 msgid may optionally contain *replacement +markers*. For instance: .. code-block:: python :linenos: @@ -71,10 +71,9 @@ msgid may optionally contain *replacement markers*. For instance: 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: +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: @@ -82,14 +81,14 @@ replacement marker itself: 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* will be replaced at translation time. The others -will not be interpolated and will be output literally. +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* +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. +represents a translation category to disambiguate it from other translations of +the same msgid, in case they conflict. .. code-block:: python :linenos: @@ -98,13 +97,12 @@ translations of the same msgid, in case they conflict. 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 filesystem which contains translations -for a given domain. In this case, if it were trying to translate -our msgid to German, it might try to find a translation from a -:term:`gettext` file within a :term:`translation directory` like this -one: +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 +filesystem which contains translations for a given domain. In this case, if it +were trying to translate our msgid to German, it might try to find a +translation from a :term:`gettext` file within a :term:`translation directory` +like this one: .. code-block:: text @@ -113,14 +111,13 @@ one: In other words, it would want to take translations from the ``form.mo`` translation file in the German language. -Finally, the TranslationString constructor accepts a ``default`` -argument. If a ``default`` argument is supplied, it replaces usages -of the ``msgid`` as the *default value* for the translation string. -When ``default`` is ``None``, the ``msgid`` 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: +Finally, the TranslationString constructor accepts a ``default`` argument. If +a ``default`` argument is supplied, it replaces usages of the ``msgid`` as the +*default value* for the translation string. When ``default`` is ``None``, the +``msgid`` 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: @@ -129,8 +126,7 @@ identifiers unrelated to their default text: ts = TranslationString('add-number', default='Add ${number}', domain='form', mapping={'number':1}) -When default text is used, Default text objects may contain -replacement values. +When default text is used, Default text objects may contain replacement values. .. index:: single: translation string factory @@ -139,10 +135,10 @@ Using the ``TranslationStringFactory`` Class ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Another way to generate a translation string is to use the -: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: +: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: .. code-block:: python :linenos: @@ -151,20 +147,18 @@ generated by using it. For example: _ = 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 tools. +.. note:: We assigned the translation string factory to the name ``_``. This + is a convention which will be supported by translation file generation + tools. After assigning ``_`` to the result of a -: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: +: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: @@ -173,12 +167,11 @@ to: 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 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: +You can set up your own translation string factory much like the one provided +above by using the :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: .. code-block:: python :linenos: @@ -187,71 +180,68 @@ do something like this: _ = 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 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:`pyramid.config.Configurator.add_translation_dirs` -method. +Creating a unique domain for your application via a translation string 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 their own. Instead they can just include your package's +:term:`translation directory` via the +:meth:`pyramid.config.Configurator.add_translation_dirs` method. .. note:: For people familiar with Zope internationalization, a TranslationStringFactory is a lot like a - ``zope.i18nmessageid.MessageFactory`` object. It is not a - subclass, however. + ``zope.i18nmessageid.MessageFactory`` object. It is not a subclass, + however. .. index:: single: gettext single: translation directories -Working With ``gettext`` Translation Files +Working with ``gettext`` Translation Files ------------------------------------------ -The basis of :app:`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. +The basis of :app:`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. .. note:: - The steps a developer must take to work with :term:`gettext` - :term:`message catalog` files within a :app:`Pyramid` - application are very similar to the steps a :term:`Pylons` - developer must take to do the same. See the :ref:`Pylons - Internationalization and Localization documentation + The steps a developer must take to work with :term:`gettext` :term:`message + catalog` files within a :app:`Pyramid` application are very similar to the + steps a :term:`Pylons` developer must take to do the same. See the + :ref:`Pylons Internationalization and Localization documentation ` for more information. -GNU gettext uses three types of files in the translation framework, -``.pot`` files, ``.po`` files and ``.mo`` files. +GNU gettext uses three types of files in the translation framework, ``.pot`` +files, ``.po`` files, and ``.mo`` files. ``.pot`` (Portable Object Template) files - A ``.pot`` file is created by a program which searches through your - project's source code and which picks out every :term:`message - identifier` passed to one of the ``_()`` functions - (eg. :term:`translation string` constructions). The list of all - message identifiers is placed into a ``.pot`` file, which serves as - a template for creating ``.po`` files. + A ``.pot`` file is created by a program which searches through your project's + source code and which picks out every :term:`message identifier` passed to + one of the ``_()`` functions (e.g., :term:`translation string` + constructions). The list of all message identifiers is placed into a ``.pot`` + file, which serves as a template for creating ``.po`` files. ``.po`` (Portable Object) files - The list of messages in a ``.pot`` file are translated by a human to - a particular language; the result is saved as a ``.po`` file. + The list of messages in a ``.pot`` file are translated by a human to a + particular language; the result is saved as a ``.po`` file. ``.mo`` (Machine Object) files - A ``.po`` file is turned into a machine-readable binary file, which - is the ``.mo`` file. Compiling the translations to machine code - makes the localized program start faster. + A ``.po`` file is turned into a machine-readable binary file, which is the + ``.mo`` file. Compiling the translations to machine code makes the + localized program start faster. The tools for working with :term:`gettext` translation files related to a -:app:`Pyramid` application are :term:`Lingua` and :term:`Gettext`. Lingua -can scrape i18n references out of Python and Chameleon files and create -the ``.pot`` file. Gettext includes ``msgmerge`` tool to update a ``.po`` file -from an updated ``.pot`` file and ``msgfmt`` to compile ``.po`` files to -``.mo`` files. +:app:`Pyramid` application are :term:`Lingua` and :term:`Gettext`. Lingua can +scrape i18n references out of Python and Chameleon files and create the +``.pot`` file. Gettext includes ``msgmerge`` tool to update a ``.po`` file from +an updated ``.pot`` file and ``msgfmt`` to compile ``.po`` files to ``.mo`` +files. .. index:: single: Gettext @@ -262,19 +252,18 @@ from an updated ``.pot`` file and ``msgfmt`` to compile ``.po`` files to Installing Lingua and Gettext ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -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. +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 ++++++++++++++++++++ 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 system run this command: +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 +system run this command: .. code-block:: text @@ -282,8 +271,7 @@ Ubuntu system run this command: Installing Lingua is done with the Python packaging tools. If the :term:`virtualenv` into which you've installed your :app:`Pyramid` application -lives in ``/my/virtualenv``, you can install Lingua -like so: +lives in ``/my/virtualenv``, you can install Lingua like so: .. code-block:: text @@ -295,11 +283,10 @@ Installation on Windows There are several ways to install Gettext on Windows: it is included in the `Cygwin `_ collection, or you can use the `installer -from the GnuWin32 `_ -or compile it yourself. Make sure the installation path is added to your +from the GnuWin32 `_, or +compile it yourself. Make sure the installation path is added to your ``$PATH``. - Installing Lingua is done with the Python packaging tools. If the :term:`virtualenv` into which you've installed your :app:`Pyramid` application lives in ``C:\my\virtualenv``, you can install Lingua like so: @@ -317,7 +304,7 @@ lives in ``C:\my\virtualenv``, you can install Lingua like so: Extracting Messages from Code and Templates ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Once Lingua is installed you may extract a message catalog template from the +Once Lingua is installed, you may extract a message catalog template from the code and :term:`Chameleon` templates which reside in your :app:`Pyramid` application. You run a ``pot-create`` command to extract the messages: @@ -327,8 +314,7 @@ application. You run a ``pot-create`` command to extract the messages: $ mkdir -p myapplication/locale $ $VENV/bin/pot-create -o myapplication/locale/myapplication.pot src -The message catalog ``.pot`` template will end up in: - +The message catalog ``.pot`` template will end up in ``myapplication/locale/myapplication.pot``. @@ -339,12 +325,11 @@ Initializing a Message Catalog File ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Once you've extracted messages into a ``.pot`` file (see -:ref:`extracting_messages`), to begin localizing the messages present -in the ``.pot`` file, you need to generate at least one ``.po`` file. -A ``.po`` file represents translations of a particular set of messages -to a particular locale. Initialize a ``.po`` file for a specific -locale from a pre-generated ``.pot`` template by using the ``msginit`` -command from Gettext: +:ref:`extracting_messages`), to begin localizing the messages present in the +``.pot`` file, you need to generate at least one ``.po`` file. A ``.po`` file +represents translations of a particular set of messages to a particular locale. +Initialize a ``.po`` file for a specific locale from a pre-generated ``.pot`` +template by using the ``msginit`` command from Gettext: .. code-block:: text @@ -353,18 +338,15 @@ command from Gettext: $ mkdir -p es/LC_MESSAGES $ msginit -l es -o es/LC_MESSAGES/myapplication.po -This will create a new message catalog ``.po`` file in: - +This will create a new message catalog ``.po`` file in ``myapplication/locale/es/LC_MESSAGES/myapplication.po``. -Once the file is there, it can be worked on by a human translator. -One tool which may help with this is `Poedit -`_. +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 :app:`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`. +Note that :app:`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`. .. index:: pair: updating; message catalog @@ -372,13 +354,13 @@ available, a ``.mo`` file must exist. See Updating a Catalog File ~~~~~~~~~~~~~~~~~~~~~~~ -If more translation strings are added to your application, or -translation strings change, you will need to update existing ``.po`` -files based on changes to the ``.pot`` file, so that the new and -changed messages can also be translated or re-translated. +If more translation strings are added to your application, or translation +strings change, you will need to update existing ``.po`` files based on changes +to the ``.pot`` file, so that the new and changed messages can also be +translated or re-translated. -First, regenerate the ``.pot`` file as per :ref:`extracting_messages`. -Then use the ``msgmerge`` command from Gettext. +First, regenerate the ``.pot`` file as per :ref:`extracting_messages`. Then use +the ``msgmerge`` command from Gettext. .. code-block:: text @@ -394,20 +376,21 @@ Then use the ``msgmerge`` command from Gettext. Compiling a Message Catalog File ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Finally, to prepare an application for performing actual runtime -translations, compile ``.po`` files to ``.mo`` files use the ``msgfmt`` -command from Gettext: +Finally, to prepare an application for performing actual runtime translations, +compile ``.po`` files to ``.mo`` files using the ``msgfmt`` command from +Gettext: .. code-block:: text $ cd /place/where/myapplication/setup.py/lives - $ msgfmt -o myapplication/locale/es/LC_MESSAGES/myapplication.mo myapplication/locale/es/LC_MESSAGES/myapplication.po + $ 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 is configured into your application (see -:ref:`adding_a_translation_directory`), these translations will be available -to :app:`Pyramid`. +:ref:`adding_a_translation_directory`), these translations will be available to +:app:`Pyramid`. .. index:: single: localizer @@ -418,10 +401,10 @@ 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 -:attr:`pyramid.request.Request.localizer` attribute to obtain a -:term:`localizer`. The localizer object will be configured to produce -translations implied by the active :term:`locale negotiator` or a default +pluralization "by hand" in an application. You may use the +:attr:`pyramid.request.Request.localizer` attribute to obtain a +:term:`localizer`. The localizer object will be configured to produce +translations implied by the active :term:`locale negotiator`, or a default localizer object if no explicit locale negotiator is registered. .. code-block:: python @@ -432,7 +415,7 @@ localizer object if no explicit locale negotiator is registered. .. note:: - If you need to create a localizer for a locale use the + If you need to create a localizer for a locale, use the :func:`pyramid.i18n.make_localizer` function. .. index:: @@ -444,9 +427,9 @@ Performing a Translation ~~~~~~~~~~~~~~~~~~~~~~~~ A :term:`localizer` has a ``translate`` method which accepts either a -:term:`translation string` or a Unicode string and which returns a -Unicode object representing the translation. So, generating a -translation in a view component of an application might look like so: +:term:`translation string` or a Unicode string and which returns a Unicode +object representing the translation. Generating a translation in a view +component of an application might look like so: .. code-block:: python :linenos: @@ -469,9 +452,8 @@ locale of the localizer. .. note:: - If you're using :term:`Chameleon` templates, you don't need - to pre-translate translation strings this way. See - :ref:`chameleon_translation_strings`. + If you're using :term:`Chameleon` templates, you don't need to pre-translate + translation strings this way. See :ref:`chameleon_translation_strings`. .. index:: single: pluralizing (i18n) @@ -481,8 +463,7 @@ locale of the localizer. Performing a Pluralization ~~~~~~~~~~~~~~~~~~~~~~~~~~ -A :term:`localizer` has a ``pluralize`` method with the following -signature: +A :term:`localizer` has a ``pluralize`` method with the following signature: .. code-block:: python :linenos: @@ -491,7 +472,7 @@ signature: ... The simplest case is the ``singular`` and ``plural`` arguments being passed as -unicode literals. This returns the appropriate literal according to the locale +Unicode literals. This returns the appropriate literal according to the locale pluralization rules for the number ``n``, and interpolates ``mapping``. .. code-block:: python @@ -502,15 +483,14 @@ pluralization rules for the number ``n``, and interpolates ``mapping``. 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 ``plural`` value is ignored. -``domain`` should be a :term:`translation domain`, and -``mapping`` should be a dictionary that is used for *replacement -value* interpolation of the translated string. +However, for support of other languages, the ``singular`` argument should be a +Unicode value representing a :term:`message identifier`. In this case the +``plural`` value is ignored. ``domain`` should be a :term:`translation domain`, +and ``mapping`` should be a dictionary that is used for *replacement value* +interpolation of the translated string. The value of ``n`` will be used to find the appropriate plural form for the -current language and ``pluralize`` will return a Unicode translation for the +current language, and ``pluralize`` will return a Unicode translation for the message id ``singular``. The message file must have defined ``singular`` as a translation with plural forms. @@ -561,18 +541,17 @@ You can obtain the locale name related to a request by using the 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 :term:`default locale name` if the locale negotiator returns ``None``. -You can change the default locale name by changing the -``pyramid.default_locale_name`` setting; see :ref:`default_locale_name_setting`. +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 +:term:`default locale name` if the locale negotiator returns ``None``. You can +change the default locale name by changing the ``pyramid.default_locale_name`` +setting. See :ref:`default_locale_name_setting`. -Once :func:`~pyramid.request.Request.locale_name` is first run, the locale -name is stored on the request object. Subsequent calls to -:func:`~pyramid.request.Request.locale_name` will return the stored locale -name without invoking the :term:`locale negotiator`. To avoid this -caching, you can use the :func:`pyramid.i18n.negotiate_locale_name` -function: +Once :func:`~pyramid.request.Request.locale_name` is first run, the locale name +is stored on the request object. Subsequent calls to +:func:`~pyramid.request.Request.locale_name` will return the stored locale name +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: @@ -592,8 +571,8 @@ You can also obtain the locale name related to a request using the 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 +Obtaining the locale name as an attribute of a localizer is equivalent to +obtaining a locale name by asking for the :func:`~pyramid.request.Request.locale_name` attribute. .. index:: @@ -603,20 +582,18 @@ to obtaining a locale name by asking for the Performing Date Formatting and Currency Formatting -------------------------------------------------- -:app:`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 +:app:`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 `_ -provides minimal information about how to perform date and currency -related locale operations. See :ref:`installing_babel` for -information about how to install Babel. +provides minimal information about how to perform date and currency 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 :app:`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: +The :class:`babel.core.Locale` class requires a :term:`locale name` as an +argument to its constructor. You can use :app:`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: .. code-block:: python :linenos: @@ -635,15 +612,14 @@ obtain the locale name for a request to pass to the Chameleon Template Support for Translation Strings -------------------------------------------------- -When a :term:`translation string` is used as the subject of textual -rendering by a :term:`Chameleon` template renderer, it will -automatically be translated to the requesting user's language if a -suitable translation exists. This is true of both the ZPT and text -variants of the Chameleon template renderers. +When a :term:`translation string` is used as the subject of textual rendering +by a :term:`Chameleon` template renderer, it will automatically be translated +to the requesting user's language if a suitable translation exists. This is +true of both the ZPT and text variants of the Chameleon template renderers. -For example, in a Chameleon ZPT template, the translation string -represented by "some_translation_string" in each example below will go -through translation before being rendered: +For example, in a Chameleon ZPT template, the translation string represented by +"some_translation_string" in each example below will go through translation +before being rendered: .. code-block:: xml :linenos: @@ -668,32 +644,31 @@ through translation before being rendered: .. XXX the last example above appears to not yet work as of Chameleon .. 1.2.3 -The features represented by attributes of the ``i18n`` namespace of -Chameleon will also consult the :app:`Pyramid` translations. -See http://chameleon.readthedocs.org/en/latest/reference.html#id50. +The features represented by attributes of the ``i18n`` namespace of Chameleon +will also consult the :app:`Pyramid` translations. See +http://chameleon.readthedocs.org/en/latest/reference.html#id50. .. note:: - Unlike when Chameleon is used outside of :app:`Pyramid`, when it - is used *within* :app:`Pyramid`, it does not support use of the - ``zope.i18n`` translation framework. Applications which use - :app:`Pyramid` should use the features documented in this - chapter rather than ``zope.i18n``. + Unlike when Chameleon is used outside of :app:`Pyramid`, when it is used + *within* :app:`Pyramid`, it does not support use of the ``zope.i18n`` + translation framework. Applications which use :app:`Pyramid` should use the + features documented in this chapter rather than ``zope.i18n``. -Third party :app:`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`. +Third party :app:`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`. .. index:: single: Mako i18n -Mako Pyramid I18N Support +Mako Pyramid i18n Support ------------------------- -There exists a recipe within the :term:`Pyramid Cookbook` named "Mako -Internationalization" which explains how to add idiomatic I18N support to -:term:`Mako` templates. +There exists a recipe within the :term:`Pyramid Cookbook` named ":ref:`Mako +Internationalization `" which explains how to add idiomatic +i18n support to :term:`Mako` templates. .. index:: single: localization deployment settings @@ -705,10 +680,9 @@ Localization-Related Deployment Settings ---------------------------------------- A :app:`Pyramid` application will have a ``pyramid.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:`~pyramid.config.Configurator` constructor at startup -time: +setting. This value represents the :term:`default locale name` used when the +:term:`locale negotiator` returns ``None``. Pass it to the +:mod:`~pyramid.config.Configurator` constructor at startup time: .. code-block:: python :linenos: @@ -729,11 +703,11 @@ application's ``.ini`` file: 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``. +If this value is not supplied via the Configurator constructor or via a config +file, it will default to ``en``. -If this setting is supplied within the :app:`Pyramid` application -``.ini`` file, it will be available as a settings key: +If this setting is supplied within the :app:`Pyramid` application ``.ini`` +file, it will be available as a settings key: .. code-block:: python :linenos: @@ -748,34 +722,32 @@ If this setting is supplied within the :app:`Pyramid` application "Detecting" Available Languages ------------------------------- -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. +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 :app:`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 -to anyway, regardless of which translation files are on disk. +It is by design that :app:`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 to anyway, regardless of which translation +files are on disk. -Here's why: it's not a given that because translations exist in a -particular language within the registered set of translation -directories that this particular deployment wants to allow translation -to that language. For example, some translations may exist but they -may be incomplete or incorrect. Or there may be translations to a -language but not for all translation domains. +Here's why: it's not a given that because translations exist in a particular +language within the registered set of translation directories that this +particular deployment wants to allow translation to that language. For +example, some translations may exist but they may be incomplete or incorrect. +Or there may be translations to a language but not for all translation domains. Any nontrivial application deployment will always need to be able to -selectively choose to allow only some languages even if that set of -languages is smaller than all those detected within registered -translation directories. The easiest way to allow for this is to make -the application entirely responsible for knowing which languages are -allowed to be translated to instead of relying on the framework to -divine this information from translation directory file info. +selectively choose to allow only some languages even if that set of languages +is smaller than all those detected within registered translation directories. +The easiest way to allow for this is to make the application entirely +responsible for knowing which languages are 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:`pyramid.settings` -mechanism: +You can set up a system to allow a deployer to select available languages based +on convention by using the :mod:`pyramid.settings` mechanism. Allow a deployer to modify your application's ``.ini`` file: @@ -798,8 +770,8 @@ Then as a part of the code of a custom :term:`locale negotiator`: languages = aslist(request.registry.settings['available_languages']) # ... -This is only a suggestion. You can create your own "available -languages" configuration scheme as necessary. +This is only a suggestion. You can create your own "available languages" +configuration scheme as necessary. .. index:: pair: translation; activating @@ -814,8 +786,8 @@ languages" configuration scheme as necessary. Activating Translation ---------------------- -By default, a :app:`Pyramid` application performs no translation. -To turn translation on, you must: +By default, a :app:`Pyramid` application performs no translation. To turn +translation on you must: - add at least one :term:`translation directory` to your application. @@ -829,24 +801,23 @@ To turn translation on, you must: Adding a Translation Directory ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -:term:`gettext` is the underlying machinery behind the -:app:`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 -``LC_MESSAGES`` directory should contain one or more ``.mo`` files. -Each ``.mo`` file represents a :term:`message catalog`, which is used -to provide translations to your application. +:term:`gettext` is the underlying machinery behind the :app:`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 ``LC_MESSAGES`` directory should contain one or more ``.mo`` +files. Each ``.mo`` file represents a :term:`message catalog`, which is used to +provide translations to your application. Adding a :term:`translation directory` registers all of its constituent -:term:`message catalog` files within your :app:`Pyramid` application to -be available to use for translation services. This includes all of the -``.mo`` files found within all ``LC_MESSAGES`` directories within each -locale directory in the translation directory. +:term:`message catalog` files within your :app:`Pyramid` application to be +available to use for translation services. This includes all of the ``.mo`` +files found within all ``LC_MESSAGES`` directories within each locale directory +in the translation directory. You can add a translation directory imperatively by using the -:meth:`pyramid.config.Configurator.add_translation_dirs` during -application startup. For example: +:meth:`pyramid.config.Configurator.add_translation_dirs` during application +startup. For example: .. code-block:: python :linenos: @@ -856,10 +827,10 @@ application startup. For example: 'another.application:locale/') A message catalog in a translation directory added via -:meth:`~pyramid.config.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`. +:meth:`~pyramid.config.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`. .. index:: pair: setting; locale @@ -867,32 +838,29 @@ locale and :term:`translation domain`. Setting the Locale ~~~~~~~~~~~~~~~~~~ -When the *default locale negotiator* (see -:ref:`default_locale_negotiator`) is in use, you can inform -:app:`Pyramid` of the current locale name by doing any of these -things before any translations need to be performed: +When the *default locale negotiator* (see :ref:`default_locale_negotiator`) is +in use, you can inform :app:`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 - (usually directly within view code). E.g. ``request._LOCALE_ = - 'de'``. +- Set the ``_LOCALE_`` attribute of the request to a valid locale name (usually + directly within view code), e.g., ``request._LOCALE_ = 'de'``. -- Ensure that a valid locale name value is in the ``request.params`` - dictionary under the key named ``_LOCALE_``. This is usually the - result of passing a ``_LOCALE_`` value in the query string or in the - body of a form post associated with a request. For example, - visiting ``http://my.application?_LOCALE_=de``. +- Ensure that a valid locale name value is in the ``request.params`` dictionary + under the key named ``_LOCALE_``. This is usually the result of passing a + ``_LOCALE_`` value in the query string or in the body of a form post + associated with a request. For example, visiting + ``http://my.application?_LOCALE_=de``. - Ensure that a valid locale name value is in the ``request.cookies`` - dictionary under the key named ``_LOCALE_``. This is usually the - result of setting a ``_LOCALE_`` cookie in a prior response, - e.g. ``response.set_cookie('_LOCALE_', 'de')``. + dictionary under the key named ``_LOCALE_``. This is usually the result of + setting a ``_LOCALE_`` cookie in a prior response, e.g., + ``response.set_cookie('_LOCALE_', 'de')``. .. note:: If this locale negotiation scheme is inappropriate for a particular - application, you can configure a custom :term:`locale negotiator` - function into that application as required. See - :ref:`custom_locale_negotiator`. + application, you can configure a custom :term:`locale negotiator` function + into that application as required. See :ref:`custom_locale_negotiator`. .. index:: single: locale negotiator @@ -902,57 +870,55 @@ things before any translations need to be performed: Locale Negotiators ------------------ -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:`pyramid.i18n.Localizer.translate` or -:meth:`pyramid.i18n.Localizer.pluralize` is invoked. It is also -consulted when :func:`~pyramid.request.Request.locale_name` is accessed or -when :func:`~pyramid.i18n.negotiate_locale_name` is invoked. +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:`pyramid.i18n.Localizer.translate` or +:meth:`pyramid.i18n.Localizer.pluralize` is invoked. It is also consulted when +:func:`~pyramid.request.Request.locale_name` is accessed or when +:func:`~pyramid.i18n.negotiate_locale_name` is invoked. .. _default_locale_negotiator: The Default Locale Negotiator ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Most applications can make use of the default locale negotiator, which -requires no additional coding or configuration. +Most applications can make use of the default locale negotiator, which requires +no additional coding or configuration. The default locale negotiator implementation named -:class:`~pyramid.i18n.default_locale_negotiator` uses the following -set of steps to determine the locale name. +:class:`~pyramid.i18n.default_locale_negotiator` uses the following set of +steps to determine the locale name. -- First, the negotiator looks for the ``_LOCALE_`` attribute of the - request object (possibly set directly by view code or by a listener - for an :term:`event`). +- First the negotiator looks for the ``_LOCALE_`` attribute of the request + object (possibly set directly by view code or by a listener for an + :term:`event`). - Then it looks for the ``request.params['_LOCALE_']`` value. - Then it looks for the ``request.cookies['_LOCALE_']`` value. -- If no locale can be found via the request, it falls back to using - the :term:`default locale name` (see - :ref:`localization_deployment_settings`). +- If no locale can be found via the request, it falls back to using the + :term:`default locale name` (see :ref:`localization_deployment_settings`). -- Finally, if the default locale name is not explicitly set, it uses - the locale name ``en``. +- Finally if the default locale name is not explicitly set, it uses the locale + name ``en``. .. _custom_locale_negotiator: Using a Custom Locale Negotiator ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Locale negotiation is sometimes policy-laden and complex. If the -(simple) default locale negotiation scheme described in -:ref:`activating_translation` is inappropriate for your application, -you may create and a special :term:`locale negotiator`. Subsequently -you may override the default locale negotiator by adding your newly -created locale negotiator to your application's configuration. +Locale negotiation is sometimes policy-laden and complex. If the (simple) +default locale negotiation scheme described in :ref:`activating_translation` is +inappropriate for your application, you may create a special :term:`locale +negotiator`. Subsequently you may override the default locale negotiator by +adding your newly created locale negotiator to your application's +configuration. -A locale negotiator is simply a callable which -accepts a request and returns a single :term:`locale name` or ``None`` -if no locale can be determined. +A locale negotiator is simply a callable which accepts a request and returns a +single :term:`locale name` or ``None`` if no locale can be determined. Here's an implementation of a simple locale negotiator: @@ -963,16 +929,14 @@ Here's an implementation of a simple locale negotiator: locale_name = request.params.get('my_locale') return locale_name -If a locale negotiator returns ``None``, it signifies to -:app:`Pyramid` that the default application locale name should be -used. +If a locale negotiator returns ``None``, it signifies to :app:`Pyramid` that +the default application locale name should be used. You may add your newly created locale negotiator to your application's configuration by passing 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:`~pyramid.config.Configurator` instance during application -startup. For example: +``locale_negotiator`` argument of the :class:`~pyramid.config.Configurator` +instance during application startup. For example: .. code-block:: python :linenos: @@ -980,9 +944,8 @@ startup. For example: from pyramid.config import Configurator config = Configurator(locale_negotiator=my_locale_negotiator) -Alternately, use the -:meth:`pyramid.config.Configurator.set_locale_negotiator` -method. +Alternatively, use the +:meth:`pyramid.config.Configurator.set_locale_negotiator` method. For example: @@ -992,4 +955,3 @@ For example: from pyramid.config import Configurator config = Configurator() config.set_locale_negotiator(my_locale_negotiator) - -- cgit v1.2.3 From 34515f33b3e391dd1c0c727bf5ef4af586b57889 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Thu, 14 Jan 2016 02:55:04 -0800 Subject: Rename Cookbook to Pyramid Community Cookbook - use .rst intersphinx labels for pages instead of broken URLs --- docs/narr/i18n.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'docs/narr/i18n.rst') diff --git a/docs/narr/i18n.rst b/docs/narr/i18n.rst index bb0bbe511..ecc48aa2b 100644 --- a/docs/narr/i18n.rst +++ b/docs/narr/i18n.rst @@ -666,9 +666,9 @@ can always use the more manual translation facility described in Mako Pyramid i18n Support ------------------------- -There exists a recipe within the :term:`Pyramid Cookbook` named ":ref:`Mako -Internationalization `" which explains how to add idiomatic -i18n support to :term:`Mako` templates. +There exists a recipe within the :term:`Pyramid Community Cookbook` named +:ref:`Mako Internationalization ` which explains how to add +idiomatic i18n support to :term:`Mako` templates. .. index:: single: localization deployment settings -- cgit v1.2.3 From 8d212aac349c381fa20c2c8927acdaf4873e394e Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Sat, 20 Feb 2016 19:09:34 -0800 Subject: fix links for babel and chameleon --- docs/narr/i18n.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) (limited to 'docs/narr/i18n.rst') diff --git a/docs/narr/i18n.rst b/docs/narr/i18n.rst index ecc48aa2b..839a48df4 100644 --- a/docs/narr/i18n.rst +++ b/docs/narr/i18n.rst @@ -585,10 +585,10 @@ Performing Date Formatting and Currency Formatting :app:`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 -`_ -provides minimal information about how to perform date and currency related -locale operations. See :ref:`installing_babel` for information about how to -install Babel. +`_ provides +minimal information about how to perform date and currency 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 :app:`Pyramid` APIs to obtain the -- cgit v1.2.3 From 88c92b8f01ace15b57550cec2ab5c9127667f300 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Fri, 8 Apr 2016 02:18:51 -0700 Subject: Add pyramid_jinja2 example to i18n docs. Fixes #2437. --- docs/narr/i18n.rst | 15 +++++++++++++++ 1 file changed, 15 insertions(+) (limited to 'docs/narr/i18n.rst') diff --git a/docs/narr/i18n.rst b/docs/narr/i18n.rst index 839a48df4..b385eaf96 100644 --- a/docs/narr/i18n.rst +++ b/docs/narr/i18n.rst @@ -670,6 +670,21 @@ There exists a recipe within the :term:`Pyramid Community Cookbook` named :ref:`Mako Internationalization ` which explains how to add idiomatic i18n support to :term:`Mako` templates. + +.. index:: + single: Jinja2 i18n + +Jinja2 Pyramid i18n Support +--------------------------- + +The add-on `pyramid_jinja2 `_ +provides a scaffold with an example of how to use internationalization with +Jinja2 in Pyramid. See the documentation sections `Internalization (i18n) +`_ +and `Paster Template I18N +`_. + + .. index:: single: localization deployment settings single: default_locale_name -- cgit v1.2.3 From d67566acebf890a603fad0e9069d5e131dfb5b31 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Tue, 12 Apr 2016 06:43:38 -0700 Subject: one does not simply "create a virtualenv". one should "create a virtual environment". - Fixes #2483 --- docs/narr/i18n.rst | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) (limited to 'docs/narr/i18n.rst') diff --git a/docs/narr/i18n.rst b/docs/narr/i18n.rst index b385eaf96..93e355ffe 100644 --- a/docs/narr/i18n.rst +++ b/docs/narr/i18n.rst @@ -270,12 +270,12 @@ system run this command: $ sudo apt-get install gettext Installing Lingua is done with the Python packaging tools. If the -:term:`virtualenv` into which you've installed your :app:`Pyramid` application -lives in ``/my/virtualenv``, you can install Lingua like so: +:term:`virtual environment` into which you've installed your :app:`Pyramid` +application lives in ``/my/venv``, you can install Lingua like so: .. code-block:: text - $ cd /my/virtualenv + $ cd /my/venv $ $VENV/bin/easy_install lingua Installation on Windows @@ -288,8 +288,8 @@ compile it yourself. Make sure the installation path is added to your ``$PATH``. Installing Lingua is done with the Python packaging tools. If the -:term:`virtualenv` into which you've installed your :app:`Pyramid` application -lives in ``C:\my\virtualenv``, you can install Lingua like so: +:term:`virtual environment` into which you've installed your :app:`Pyramid` +application lives in ``C:\my\venv``, you can install Lingua like so: .. code-block:: text -- cgit v1.2.3 From c843d60e56d1747dc04e022ea4b16dd53b78221c Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Tue, 12 Apr 2016 14:12:13 -0700 Subject: - zap easy_install straggler --- docs/narr/i18n.rst | 33 +++++++++++++++++---------------- 1 file changed, 17 insertions(+), 16 deletions(-) (limited to 'docs/narr/i18n.rst') diff --git a/docs/narr/i18n.rst b/docs/narr/i18n.rst index 93e355ffe..a3f730f0c 100644 --- a/docs/narr/i18n.rst +++ b/docs/narr/i18n.rst @@ -265,18 +265,18 @@ 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 system run this command: -.. code-block:: text +.. code-block:: bash $ 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` -application lives in ``/my/venv``, you can install Lingua like so: +application lives at the environment variable ``$VENV``, you can install Lingua +like so: -.. code-block:: text +.. code-block:: bash - $ cd /my/venv - $ $VENV/bin/easy_install lingua + $ $VENV/bin/pip install lingua Installation on Windows +++++++++++++++++++++++ @@ -289,11 +289,12 @@ compile it yourself. Make sure the installation path is added to your Installing Lingua is done with the Python packaging tools. If the :term:`virtual environment` into which you've installed your :app:`Pyramid` -application lives in ``C:\my\venv``, you can install Lingua like so: +application lives at the environment variable ``%VENV%``, you can install +Lingua like so: -.. code-block:: text +.. code-block:: ps1con - C> %VENV%\Scripts\easy_install lingua + C> %VENV%\Scripts\pip install lingua .. index:: @@ -308,9 +309,9 @@ Once Lingua is installed, you may extract a message catalog template from the code and :term:`Chameleon` templates which reside in your :app:`Pyramid` application. You run a ``pot-create`` command to extract the messages: -.. code-block:: text +.. code-block:: bash - $ cd /place/where/myapplication/setup.py/lives + $ cd /file/path/to/myapplication_setup.py $ mkdir -p myapplication/locale $ $VENV/bin/pot-create -o myapplication/locale/myapplication.pot src @@ -331,9 +332,9 @@ represents translations of a particular set of messages to a particular locale. Initialize a ``.po`` file for a specific locale from a pre-generated ``.pot`` template by using the ``msginit`` command from Gettext: -.. code-block:: text +.. code-block:: bash - $ cd /place/where/myapplication/setup.py/lives + $ cd /file/path/to/myapplication_setup.py $ cd myapplication/locale $ mkdir -p es/LC_MESSAGES $ msginit -l es -o es/LC_MESSAGES/myapplication.po @@ -362,9 +363,9 @@ translated or re-translated. First, regenerate the ``.pot`` file as per :ref:`extracting_messages`. Then use the ``msgmerge`` command from Gettext. -.. code-block:: text +.. code-block:: bash - $ cd /place/where/myapplication/setup.py/lives + $ cd /file/path/to/myapplication_setup.py $ cd myapplication/locale $ msgmerge --update es/LC_MESSAGES/myapplication.po myapplication.pot @@ -380,9 +381,9 @@ Finally, to prepare an application for performing actual runtime translations, compile ``.po`` files to ``.mo`` files using the ``msgfmt`` command from Gettext: -.. code-block:: text +.. code-block:: bash - $ cd /place/where/myapplication/setup.py/lives + $ cd /file/path/to/myapplication_setup.py $ msgfmt -o myapplication/locale/es/LC_MESSAGES/myapplication.mo \ myapplication/locale/es/LC_MESSAGES/myapplication.po -- cgit v1.2.3 From a651b357b17746281b429baf5ad9d93edb333072 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Sat, 16 Apr 2016 14:27:59 -0700 Subject: replace ps1con with doscon for lexer --- docs/narr/i18n.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/narr/i18n.rst') diff --git a/docs/narr/i18n.rst b/docs/narr/i18n.rst index a3f730f0c..014f314ad 100644 --- a/docs/narr/i18n.rst +++ b/docs/narr/i18n.rst @@ -292,7 +292,7 @@ Installing Lingua is done with the Python packaging tools. If the application lives at the environment variable ``%VENV%``, you can install Lingua like so: -.. code-block:: ps1con +.. code-block:: doscon C> %VENV%\Scripts\pip install lingua -- cgit v1.2.3