docs/src/templatei18n.txt

=============================
Template Internationalization
=============================

If the application is configured for i18n, you can define translatable blocks
for translators using the `trans` tag or the special underscore function:

.. sourcecode:: jinja

    {% trans %}
        this is a translatable block
    {% endtrans %}

    {% trans "This is a translatable string" %}

    {{ _("This is a translatable string") }}

The latter one is useful if you want translatable arguments for filters etc.
If you want to use the ``_()`` syntax in an expression and have variables in
the string you can add a substituation marker (``%s``) and use the `|format`
filter to fill the slot:

.. sourcecode:: jinja

    {{ _('Hello %s!')|format(username) }}

If you have more than one substitution variable consider using the
``{% trans %}`` tags or the `|dformat` filter, the latter however is new
in Jinja 1.1.

If you want to have plural forms too, use the `pluralize` block:

.. sourcecode:: jinja

    {% trans users=users %}
        One user found.
    {% pluralize %}
        {{ users }} users found.
    {% endtrans %}

    {% trans first=(users|first).username|escape, user=users|length %}
        one user {{ first }} found.
    {% pluralize users %}
        {{ users }} users found, the first one is called {{ first }}.
    {% endtrans %}

If you have multiple arguments, the first one is assumed to be the indicator (the
number that is used to determine the correct singular or plural form. If you
don't have the indicator variable on position 1 you have to tell the `pluralize`
tag the correct variable name.

Inside translatable blocks you cannot use blocks or expressions (however you can
still use the ``raw`` block which will work as expected). The variable
print syntax (``{{ variablename }}``) is the only way to insert the variables
defined in the ``trans`` header. Filters must be applied in the header.

.. admonition:: note

    Please make sure that you always use pluralize blocks where required.
    Many languages have more complex plural forms than the English language.
    
    Never try to workaround that issue by using something like this:

    .. sourcecode:: jinja

        {% if count != 1 %}
            {{ count }} users found.
        {% else %}
            one user found.
        {% endif %}

*New in Jinja 1.1*: It's now possible to use the marker name as implicit
default:

.. sourcecode:: jinja

    instead of this version:

        {% trans username=username %}Hello {{ username }}!{% endtrans %}

    you can now write this:

        {% trans username %}Hello {{ username }}!{% endtrans %}