i18n Extension

Import name:jinja2.ext.i18n

The i18n extension can be used in combination with gettext or babel. Ifthe i18n extension is enabled Jinja2 provides a trans statement that marksthe wrapped string as translatable and calls gettext.

After enabling, dummy __ function that forwards calls to _gettext is addedto the environment globals. An internationalized application then has toprovide a gettext function and optionally an ngettext function into thenamespace, either globally or for each rendering.

Environment Methods

After enabling the extension, the environment provides the followingadditional methods:

• jinja2.Environment.installgettext_translations(_translations, newstyle=False)
• Installs a translation globally for that environment. The translationsobject provided must implement at least ugettext and ungettext.The gettext.NullTranslations and gettext.GNUTranslations classesas well as Babels Translations class are supported.

Changelog

Changed in version 2.5: newstyle gettext added

• jinja2.Environment.installnull_translations(_newstyle=False)
• Install dummy gettext functions. This is useful if you want to preparethe application for internationalization but don’t want to implement thefull internationalization system yet.

Changelog

Changed in version 2.5: newstyle gettext added

• jinja2.Environment.installgettext_callables(_gettext, ngettext, newstyle=False)
• Installs the given gettext and ngettext callables into theenvironment as globals. They are supposed to behave exactly like thestandard library’s gettext.ugettext() andgettext.ungettext() functions.

If newstyle is activated, the callables are wrapped to work likenewstyle callables. See Whitespace Trimming for more information.

Changelog

New in version 2.5.

• jinja2.Environment.uninstall_gettext_translations()
• Uninstall the translations again.

• jinja2.Environment.extracttranslations(_source)
• Extract localizable strings from the given template node or source.

For every string found this function yields a (lineno, function,message) tuple, where:

• lineno is the number of the line on which the string was found,

• function is the name of the gettext function used (if thestring was extracted from embedded Python code), and

• message is the string itself (a unicode object, or a tupleof unicode objects for functions with multiple string arguments).

If Babel is installed, the babel integrationcan be used to extract strings for babel.

For a web application that is available in multiple languages but gives allthe users the same language (for example a multilingual forum softwareinstalled for a French community) may load the translations once and add thetranslation methods to the environment at environment generation time:

translations = get_gettext_translations()
env = Environment(extensions=['jinja2.ext.i18n'])
env.install_gettext_translations(translations)

The get_gettext_translations function would return the translator for thecurrent configuration. (For example by using gettext.find)

The usage of the i18n extension for template designers is covered as partof the template documentation.

Whitespace Trimming

New in version 2.10.

Linebreaks and surrounding whitespace can be automatically trimmed by enablingthe ext.i18n.trimmed policy.

Newstyle Gettext

Changelog

New in version 2.5.

Starting with version 2.5 you can use newstyle gettext calls. These areinspired by trac’s internal gettext functions and are fully supported bythe babel extraction tool. They might not work as expected by otherextraction tools in case you are not using Babel’s.

What’s the big difference between standard and newstyle gettext calls? Ingeneral they are less to type and less error prone. Also if they are usedin an autescaping environment they better support automatic escaping.Here are some common differences between old and new calls:

standard gettext:

{{ gettext('Hello World!') }}
{{ gettext('Hello %(name)s!')|format(name='World') }}
{{ ngettext('%(num)d apple', '%(num)d apples', apples|count)|format(
    num=apples|count
)}}

newstyle gettext looks like this instead:

{{ gettext('Hello World!') }}
{{ gettext('Hello %(name)s!', name='World') }}
{{ ngettext('%(num)d apple', '%(num)d apples', apples|count) }}

The advantages of newstyle gettext are that you have less to type and thatnamed placeholders become mandatory. The latter sounds like adisadvantage but solves a lot of troubles translators are often facingwhen they are unable to switch the positions of two placeholder. Withnewstyle gettext, all format strings look the same.

Furthermore with newstyle gettext, string formatting is also used if noplaceholders are used which makes all strings behave exactly the same.Last but not least are newstyle gettext calls able to properly markstrings for autoescaping which solves lots of escaping related issues manytemplates are experiencing over time when using autoescaping.