bag.web.pyramid.locale module

A little plugin supporting human language alternation in Pyramid.

It lets you enable and disable locales (as your translations allow) in the configuration file.

This module also offers BaseLocalizedView, a useful mixin class for your application’s base view.

Enabling the module in 2 steps

1) Add a setting to your .ini file with the locales you want to enable, such as:

bag.locale.enable = en pt_BR es de fr

  1. Add to your initialization file:

    config.include('bag.web.pyramid.locale')

Effects of enabling this module as described above

1) A view is registered so the user can, for instance, browse to /locale/pt_BR in order to change the locale to Brazilian Portuguese. This works by setting the locale cookie.

2) To improve the experience of first-time visitors, a locale negotiator is registered that checks the browser’s stated preferred languages against the “bag.locale.enable” setting in the .ini file.

3) The “bag.locale.enable” setting is replaced with an OrderedDictionary that is useful for you to build a user interface for locale choice.

  1. In templates, that dictionary is available as enabled_locales.

For instance, you might do this in your template to list the available locales so the user can click and change languages:

<span class='languages-selector'
    py:with="locales = enabled_locales.values()">
  <py:for each="loc in locales">
    <a href="${url('locale', locale=loc.code)}"
       title="${loc.title}"
       py:strip="locale_code == loc.code"
       py:content="loc.code[:2]" />
    <span py:if="not loc is locales[-1]" class="separator">|</span>
  </py:for>
</span>

5) In your master template, you can set the 2 lang attributes on the <html> tag:

xml:lang="${locale_code[:2]}" lang="${locale_code[:2]}"

…because the variable locale_code is made available to template context.

class bag.web.pyramid.locale.BaseLocalizedView[source]

Bases: object

A mixin class for your application’s base view class.

format_currency(n, currency=None, format=None)[source]
format_number(n)[source]
class bag.web.pyramid.locale.LocaleDict[source]

Bases: collections.OrderedDict

A dictionary of dictionaries grouping:

  • locale codes (i.e. “pt_BR”),

  • human-readable and translatable language names such as “English”, and

  • titles such as “Change to English”, written in THAT language.

add(code, display_name=None, english_name=None, title=None)[source]
class bag.web.pyramid.locale.LocaleInfo(code, display_name, english_name, title=None, babel_locale=None)[source]

Bases: object

bag.web.pyramid.locale.add_template_globals(event)[source]

Makes the following variables readily available in template context:

  • enabled_locales: OrderedDict containing the enabled locales

bag.web.pyramid.locale.format_currency(request, n, currency='USD', format=None)[source]
bag.web.pyramid.locale.includeme(config)[source]

Integrate this module into a Pyramid app.

bag.web.pyramid.locale.language_dropdown(settings, title='Locale', name='locale', blank_option_at_top=True)[source]

Let the user select a locale from the enabled ones.

If you use Deform, you can use this to get a SchemaNode for that.

Return HTTP header setting the cookie that stores the Pyramid locale.

bag.web.pyramid.locale.locale_exists_validator(settings)[source]

If you use Deform or even just Colander, you can use this to get a validator that you can use on your user preferences form, so a user can only choose a locale that is enabled in the system.

TODO: Test this new implementation when I use colander again…

bag.web.pyramid.locale.locale_from_browser(request)[source]

The browser provides the user’s preferred languages, ordered. They come in the Accept-Language header.

This function returns the best match between that list and the enabled languages.

Most of the implementation is in the WebOb request object.

bag.web.pyramid.locale.locale_negotiator(request)[source]

This is a locale negotiator that decorates Pyramid’s default one.

If the default locale negotiator’s schemes should fail, we try to match the browser’s stated preferred languages with our configured enabled locales.

bag.web.pyramid.locale.locale_view(request)[source]

View that sets the locale cookie – as long as the requested locale is enabled – and redirects back to the referer.

bag.web.pyramid.locale.prepare_enabled_locales(settings, Dict=<class 'bag.web.pyramid.locale.LocaleDict'>)[source]

If you have a bag.locale.enable setting with a value such as “en pt-BR es fr de” (without the quotes), this method substitutes that setting with a dictionary of Locale objects which is useful to build a web interface for the user to change the locale.

bag.web.pyramid.locale.sorted_countries(arg, top_entry=True)[source]

arg may be either the desired locale code or the request object, from which the locale will be discovered.

Returns a list of tuples like ('BR', 'Brazil'), already sorted, ready for inclusion in your web form.