# Internationalization (i18n)

URL: /docs/usage/i18n/
Section: usage
Tags: usage, i18n, translation

--------------------------------------------------------------------------------

Internationalization (i18n) Kida has built-in support for translatable templates. Mark strings with &#123;% trans %&#125;, wire up a gettext backend, and Kida handles escaping, pluralization, and variable interpolation. Quick start &#123;% trans %&#125;Hello, world!&#123;% endtrans %&#125; Without translations installed, strings pass through unchanged. Install a gettext translations object to translate them: import gettext translations = gettext.translation(&quot;myapp&quot;, &quot;locales&quot;, languages=[&quot;fr&quot;]) env = Environment(loader=loader) env.install_translations(translations) Now &#123;% trans %&#125;Hello, world!&#123;% endtrans %&#125; renders &quot;Bonjour, monde !&quot; (or whatever the French .po file says). Syntax Simple translation &#123;% trans %&#125;Hello, world!&#123;% endtrans %&#125; Message ID: &quot;Hello, world!&quot; With variables Declare variable bindings in the &#123;% trans %&#125; tag. Reference them as &#123;&#123; name &#125;&#125; in the body: &#123;% trans name=user.name %&#125;Hello, {{ name }}!&#123;% endtrans %&#125; Message ID: &quot;Hello, %(name)s!&quot; The translated string uses Python %-formatting. Variable values are HTML-escaped automatically (see Escaping below). Pluralization Use &#123;% plural %&#125; to provide singular and plural forms. A count variable is required -- it determines which form ngettext selects: &#123;% trans count=items | length %&#125; One item found. &#123;% plural %&#125; {{ count }} items found. &#123;% endtrans %&#125; Singular ID: &quot;One item found.&quot; Plural ID: &quot;%(count)s items found.&quot; When count is 1, the singular form renders. Otherwise, the plural form renders with count interpolated. Multiple variables Separate bindings with commas: &#123;% trans name=user.name, count=user.posts | length %&#125; {{ name }} has one post. &#123;% plural %&#125; {{ name }} has {{ count }} posts. &#123;% endtrans %&#125; Closing tags Both &#123;% endtrans %&#125; and &#123;% end %&#125; work: &#123;% trans %&#125;Hello&#123;% endtrans %&#125; &#123;% trans %&#125;Hello&#123;% end %&#125; Shorthand functions For inline translations, use the _ and _n globals: {{ _(&quot;Hello&quot;) }} {{ _n(&quot;%(count)s item&quot;, &quot;%(count)s items&quot;, count) }} These are regular functions available in any expression context -- output tags, filter arguments, default values, etc.: &#123;% def greeting(msg=_(&quot;Hello&quot;)) %&#125; &lt;h1&gt;{{ msg }}&lt;/h1&gt; &#123;% end %&#125; Whitespace handling Whitespace inside &#123;% trans %&#125; bodies is normalized. Leading and trailing whitespace is stripped, and internal whitespace is collapsed to single spaces: &#123;% trans %&#125; Hello, world! &#123;% endtrans %&#125; Message ID: &quot;Hello, world!&quot; (not &quot;\n Hello,\n world!\n&quot;) This keeps message IDs clean regardless of template indentation. Escaping Translation and escaping interact carefully: Scenario Behavior No variables Translated string is escaped via the autoescape function With variables String is wrapped in Markup, variable values are auto-escaped Markup values Not double-escaped -- Markup instances pass through Variable escaping &#123;% trans name=user_input %&#125;Hello, {{ name }}!&#123;% endtrans %&#125; If user_input is &quot;&lt;script&gt;alert(1)&lt;/script&gt;&quot;, the output is: Hello, &amp;lt;script&amp;gt;alert(1)&amp;lt;/script&amp;gt;! The translated string itself is trusted (translators produce safe content). Variable values are escaped on interpolation via Markup.__mod__. Pre-escaped values If a variable is already Markup, it is not double-escaped: from kida.utils.html import Markup template.render(safe_html=Markup(&quot;&lt;b&gt;bold&lt;/b&gt;&quot;)) &#123;% trans name=safe_html %&#125;Hello, {{ name }}!&#123;% endtrans %&#125; {# Hello, &lt;b&gt;bold&lt;/b&gt;! #} Body restrictions Inside &#123;% trans %&#125; bodies, only simple &#123;&#123; name &#125;&#125; references are allowed. Filters, attribute access, and method calls are not permitted in the body: {# Good -- bind the expression in the tag #} &#123;% trans name=user.name | title %&#125;Hello, {{ name }}!&#123;% endtrans %&#125; {# Bad -- complex expression in body #} &#123;% trans %&#125;Hello, {{ user.name | title }}!&#123;% endtrans %&#125; This constraint ensures message IDs are predictable and extractable. Bind complex expressions in the &#123;% trans %&#125; tag, then reference the bound name in the body. Configuration install_translations Pass a standard library gettext.GNUTranslations object (or any object with gettext() and ngettext() methods): import gettext translations = gettext.translation(&quot;myapp&quot;, &quot;locales&quot;, languages=[&quot;fr&quot;]) env.install_translations(translations) install_gettext_callables Pass the translation functions directly: env.install_gettext_callables( gettext=my_gettext_func, ngettext=my_ngettext_func, ) Default behavior When no translations are installed, Kida uses identity functions: _(&quot;Hello&quot;) returns &quot;Hello&quot; _n(&quot;item&quot;, &quot;items&quot;, 1) returns &quot;item&quot; _n(&quot;item&quot;, &quot;items&quot;, 5) returns &quot;items&quot; Templates render untranslated strings. No configuration needed for single-language projects. Patterns Per-request language switching In web applications, install translations per request: def get_translations(locale: str): return gettext.translation(&quot;myapp&quot;, &quot;locales&quot;, languages=[locale]) @app.before_request def set_locale(): locale = request.accept_languages.best_match([&quot;en&quot;, &quot;fr&quot;, &quot;de&quot;]) app.jinja_env.install_translations(get_translations(locale)) Translation in components &#123;% trans %&#125; works inside &#123;% def %&#125; components: &#123;% def nav_link(href, active=false) %&#125; &lt;a href=&quot;{{ href }}&quot; &#123;% if active %&#125;class=&quot;active&quot;&#123;% end %&#125;&gt; &#123;% slot %&#125;&#123;% end %&#125; &lt;/a&gt; &#123;% end %&#125; &#123;% call nav_link(&quot;/settings&quot;) %&#125; &#123;% trans %&#125;Settings&#123;% endtrans %&#125; &#123;% end %&#125; Pluralized counts with formatting &#123;% trans count=notifications | length %&#125; You have one new notification. &#123;% plural %&#125; You have {{ count }} new notifications. &#123;% endtrans %&#125; Static content with no variables For simple strings, &#123;% trans %&#125; requires no bindings: &lt;footer&gt; &#123;% trans %&#125;Copyright 2026. All rights reserved.&#123;% endtrans %&#125; &lt;/footer&gt;

--------------------------------------------------------------------------------

Metadata:
- Word Count: 754
- Reading Time: 4 minutes