Theme
Version
GitHub PyPI Discord
On this page

Internationalization

Internationalization (i18n) lets one application show its pages in several languages. Citry's built-in i18n extension handles the parts that differ between languages:

  • translated text, including accessible labels such as aria-label;
  • numbers, currencies, dates, times, lists, and units written the way each language writes them;
  • reading numbers and dates that users type into forms;
  • the lang and dir attributes, including right-to-left languages such as Arabic.

This page walks through the basic setup: write text as messages, add the languages users can choose, and pick a language for each request. The other pages in this section cover each part in depth.

Write messages

A message is a piece of user-visible text with a stable ID. Write messages in the component's messages block, using Fluent, a translation format designed so translators can handle each language's grammar. Call a message from the template with tr():

In these examples, app is your Citry engine:

from citry import Component

class AccountCard(Component):
    class I18n:
        messages_locale = "en-US"

    class Kwargs:
        name: str

    citry = app

    template = """
      <article>
        <h2>{{ tr("my-app-account-greeting", name=name) }}</h2>
      </article>
    """

    messages = """
      # @param {str} $name - User name.
      my-app-account-greeting = Welcome, { $name }.
    """

messages_locale says which language the messages are written in. Here it is en-US, a locale: a language code with an optional region.

The @param comment declares the type of each variable the message uses. Citry checks tr() calls against it, so a missing or wrongly typed argument is reported.

tr() returns plain text, and the template escapes it like any other value.

This works without any i18n settings and adds no browser code. Any registered component can call my-app-account-greeting, even when AccountCard is not on the page. Write messages covers the Fluent syntax.

Add languages

To offer more than the source language, list the locales in the engine's i18n settings:

from citry import Citry

app = Citry(
    extensions_defaults={
        "i18n": {
            "source_locale": "en-US",
            "default_locale": "en-US",
            "locales": ("en-US", "cs-CZ", "ar-EG"),
        },
    },
)

Citry checks these settings when it creates the engine. An invalid locale name, two names for the same locale, or a default locale missing from locales raises an error.

The translations themselves go in a catalog package: a Python package of Fluent files, one folder per locale. See Organize catalogs.

Choose the language

Read the locale from the request, such as a URL parameter or a cookie. Build a locale context from it, then pass the context to the root render. A locale context is a read-only value that holds the selected locale and everything derived from it, such as the writing direction:

from citry.ext.i18n import make_context

def render_account_page(locale: str):
    context = make_context(app, locale=locale)

    account_page = AccountPage()
    return account_page.render(
        provides={"citry_i18n": context},
    )

Every component in that render uses the context. A component that calls render() itself must pass it again. Nothing changes for other requests, because Citry keeps no global "current locale".

Inside a component, Python code reads the same context through self.i18n, for example self.i18n.tr(...). Locales and context covers time zones, a different language for one part of the page, and use outside a component.

Switch in the browser

By default, text is translated on the server and arrives as ordinary HTML:

<h1>{{ tr("my-app-account-title") }}</h1>

To switch the whole page to another language, send the new locale with the next request, for example in the URL, and render the page again.

When a small part of the page must change language without a reload, wrap it in <c-i18n client> and translate with $i18n in Vue expressions:

<c-i18n tag="section" client>
  <h1 v-text="$i18n.tr('my-app-account-title')"></h1>
  <button @click="$i18n.switchLocale('cs-CZ')">
    Čeőtina
  </button>
</c-i18n>

The switch changes only the Vue-owned text inside that element. Text rendered on the server with tr() stays in its original language. Browser i18n explains when to use each option.

Continue by task