21.11. LOCALE NEGOTIATORS

21.10.2 Setting the Locale

When the default locale negotiator (see The Default Locale Negotiator) is in use, you can inform 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’.

• 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’).

latex-note.png

If this locale negotiation scheme is inappropriate for a particular application, you can conﬁgure a custom locale negotiator function into that application as required. See Using a Custom Locale Negotiator.

21.11 Locale Negotiators

A locale negotiator informs the operation of a localizer by telling it what locale name is related to a particular request. A locale negotiator is a bit of code which accepts a request and which returns a locale name. It is consulted when pyramid.i18n.Localizer.translate() or pyramid.i18n.Localizer.pluralize() is invoked. It is also consulted when get_locale_name() or negotiate_locale_name() is invoked.

245

21. INTERNATIONALIZATION AND LOCALIZATION

21.11.1 The Default Locale Negotiator

Most applications can make use of the default locale negotiator, which requires no additional coding or conﬁguration.

The default locale negotiator implementation named default_locale_negotiator uses the following set of steps to dermine 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 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 default locale name (see

Localization-Related Deployment Settings).

•Finally, if the default locale name is not explicitly set, it uses the locale name en.

21.11.2 Using a Custom Locale Negotiator

Locale negotiation is sometimes policy-laden and complex. If the (simple) default locale negotiation scheme described in Activating Translation is inappropriate for your application, you may create and a special locale negotiator. Subsequently you may override the default locale negotiator by adding your newly created locale negotiator to your application’s conﬁguration.

A locale negotiator is simply a callable which accepts a request and returns a single locale name or None if no locale can be determined.

Here’s an implementation of a simple locale negotiator:

def my_locale_negotiator(request):

locale_name = request.params.get(’my_locale’) return locale_name

If a locale negotiator returns None, it signiﬁes to Pyramid that the default application locale name should be used.

You may add your newly created locale negotiator to your application’s conﬁguration by passing an object which can act as the negotiator (or a dotted Python name referring to the object) as the locale_negotiator argument of the Configurator instance during application startup. For example:

246