Файл: pyramid.pdf

21. INTERNATIONALIZATION AND LOCALIZATION

21.4 Obtaining the Locale Name for a Request

pyramid.i18n.get_locale_name() function.

This returns the locale name negotiated by the currently active locale negotiator or the 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 Default Locale Name.

Once get_locale_name() is first run, the locale name is stored on the request object. Subsequent calls to get_locale_name() will return the stored locale name without invoking the locale negotiator. To avoid this caching, you can use the pyramid.i18n.negotiate_locale_name() function:

You can also obtain the locale name related to a request using the locale_name attribute of a localizer.

Obtaining the locale name as an attribute of a localizer is equivalent to obtaining a locale name by calling the get_locale_name() function.

21.5 Performing Date Formatting and Currency Formatting

Pyramid does not itself perform date and currency formatting for different locales. However, Babel can help you do this via the babel.core.Locale class. The Babel documentation for this class provides

240

21.6. CHAMELEON TEMPLATE SUPPORT FOR TRANSLATION STRINGS

minimal information about how to perform date and currency related locale operations. See Installing Babel and Lingua for information about how to install Babel.

The babel.core.Locale class requires a locale name as an argument to its constructor. You can use Pyramid APIs to obtain the locale name for a request to pass to the babel.core.Locale constructor; see Obtaining the Locale Name for a Request. For example:

21.6 Chameleon Template Support for Translation Strings

When a translation string is used as the subject of textual rendering by a 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:

1<span tal:content="some_translation_string"/>

1<span tal:replace="some_translation_string"/>

1<span>${some_translation_string}</span>

1<a tal:attributes="href some_translation_string">Click here</a>

The features represented by attributes of the i18n namespace of Chameleon will also consult the Pyramid translations. See http://chameleon.repoze.org/docs/latest/i18n.html#the-i18n-namespace.

241

21. INTERNATIONALIZATION AND LOCALIZATION

latex-note.png

Unlike when Chameleon is used outside of Pyramid, when it is used within Pyramid, it does not support use of the zope.i18n translation framework. Applications which use Pyramid should use the features documented in this chapter rather than zope.i18n.

Third party 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

Performing a Translation.

21.7 Mako Pyramid I18N Support

There exists a recipe within the Pyramid Cookbook named “Mako Internationalization” which explains how to add idiomatic I18N support to Mako templates.

21.8 Localization-Related Deployment Settings

A Pyramid application will have a pyramid.default_locale_name setting. This value represents the default locale name used when the locale negotiator returns None. Pass it to the Configurator constructor at startup time:

You may alternately supply a pyramid.default_locale_name via an application’s .ini file:

242

21.9. “DETECTING” AVAILABLE LANGUAGES

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 Pyramid application .ini file, it will be available as a settings key:

21.9 “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.

It is by design that 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.

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.

You can set up a system to allow a deployer to select available languages based on convention by using the pyramid.settings mechanism:

Allow a deployer to modify your application’s .ini file:

Then as a part of the code of a custom locale negotiator:

243

21. INTERNATIONALIZATION AND LOCALIZATION

This is only a suggestion. You can create your own “available languages” configuration scheme as necessary.

21.10 Activating Translation

By default, a Pyramid application performs no translation. To turn translation on, you must:

•add at least one translation directory to your application.

•ensure that your application sets the locale name correctly.

21.10.1 Adding a Translation Directory

gettext is the underlying machinery behind the Pyramid translation machinery. A translation directory is a directory organized to be useful to 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 message catalog, which is used to provide translations to your application.

Adding a translation directory registers all of its constituent message catalog files within your 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 pyramid.config.Configurator.add_translation_dirs() during application startup. For example:

A message catalog in a translation directory added via 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 translation domain.

244