| ============================= |
| 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 %} |