Babel

Sending mail to people usually means speaking their language. So the natural next battery is internationalization. Our Babel extension wraps Babel and gives you familiar gettext in your templates, locale aware formatting filters and a database-backed translation store you can update at runtime.

Enabling Babel

Babel leans on the database for its runtime translations, so it requires the SQLAlchemy extension to be enabled. Flip both switches and you are set:

[general]
SECRET_KEY = supersecret

[data]
DATABASE_URI = sqlite:///app.db

[extensions]
EXT_SQLALCHEMY = 1
EXT_BABEL = 1

When Babel expands your fluid it installs the i18n extension into your jinja_env, registers a set of formatting filters and wires up a small WebSocket so the same translations can be reused on the client. It also brings its own models, I18nKey and I18nMessage, which are where runtime translations are persisted.

Translating in templates

The gettext callables are installed new-style, so the usual underscore helper is available everywhere in your templates — you don't need any special base layout for it, enabling Babel is enough. So we can sprinkle gettext straight into the hand-written index.html we've carried since Getting Started. A source string is its own key — if no translation is found, the source is returned untouched:

<title>{{ _('Home') }}</title>

<!-- ... -->

<h1>{{ _('Hello %(name)s!', name=name) }}</h1>
<p>{{ ngettext('%(num)d model', '%(num)d models', count) }}</p>

(We'll trade this hand-written page for the framework's own base layout once we reach the Frontend chapters — the translation calls stay exactly the same.) Alongside gettext you get ngettext (plurals), pgettext (contextual) and npgettext. For strings that are built outside of a request — module level constants, for example — reach for the lazy variants like babel.lazy_gettext, which only resolve once they are actually rendered.

Providing translations

The fastest way to ship translations is the runtime store. You hand Babel a resolver — a callable that returns your catalog — and it writes the messages into the translation table and the in-memory cache during startup. The easiest way to build such a resolver is from JSON files with the bundled translation_resolver helper. Note that updates are only accepted before the server is up.

Drop one JSON file per plural form and context into a folder. The plain default.json holds the singular (and non-plural) messages, and every file maps a source string to a list of translations — one entry per locale:

{
    "Home": ["Home", "Startseite"],
    "Hello %(name)s!": ["Hello %(name)s!", "Hallo %(name)s!"]
}

Plural forms and contexts are encoded in the file name. A file called pf-other.json carries the other plural form, and ctx-menu.json would carry messages in the menu context (you can even combine them, like pf-other_ctx-menu.json):

{
    "%(num)d model": ["%(num)d models", "%(num)d Modelle"]
}

Then build the resolver from that folder, mapping each locale to its index in the JSON lists, and hand it to Babel. This must run before fluid.mix(), so import the module from your config or factory:

from pathlib import Path
from webfluid.extensions.babel.utils import translation_resolver
from webfluid.core.ext import babel


# "en" is index 0, "de" is index 1 in every JSON list:
translations = translation_resolver(
    Path(__file__).parent, { "en": 0, "de": 1 }
)

# The default domain is called "messages". This must run before
# fluid.mix(), so make sure the module is imported by then.
babel.update_translations("messages", translations)

Prefer to keep the catalog in code? update_translations accepts any callable that returns the same shape (locale → key → message-data → message, where message-data is a JSON string like "{}" or {"pf": "other"}). The translation_resolver just builds that for you from the files above. If you prefer classic .po catalogs as a static fallback, extract them once with the CLI — more on that below.

Selecting the locale

Out of the box Babel resolves the active locale from the lang cookie, then the Accept-Language header (best match against your supported locales) and finally the default. The timezone works the same way through the tz cookie or the X-Timezone header. You declare your supported set in the config:

from webfluid.core.config import register_config


@register_config(10)
class MyConfig:
    SESSION_COOKIE_SECURE = True
    MYEXT_BAR = "crazy"

    BABEL_DEFAULT_LOCALE = "en"
    BABEL_DEFAULT_TIMEZONE = "UTC"
    BABEL_SUPPORTED_LOCALES = ["en", "de"]

Need your own logic? Register a selector. Whatever it returns wins over the defaults, and you can temporarily override both with the Babel.force / Babel.aforce context managers:

from webfluid.core.ext import babel


@babel.locale_selector
def select_locale():
    from webfluid.core.context import FluidContext
    user = FluidContext.current().request.session.get("user")
    return user["locale"] if user else babel.default_locale


# Render something in a fixed locale, no matter the request:
async with babel.aforce(locale="de"):
    subject = babel.gettext("Welcome aboard!")

Formatting filters

Numbers, dates and currencies should follow the user's locale too. Babel registers a family of filters for exactly that, all locale (and where it matters, timezone) aware:

<p>{{ model.created_at|datetimeformat }}</p>
<p>{{ model.created_at|dateformat('full') }}</p>
<p>{{ 1234.5|decimalformat }}</p>
<p>{{ 19.99|currencyformat('EUR') }}</p>
<p>{{ 0.75|percentformat }}</p>

The full set is datetimeformat, dateformat, timeformat, timedeltaformat, numberformat, decimalformat, currencyformat, percentformat and scientificformat.

On the frontend

Because the extension also exposes a translation WebSocket, the same catalog is reachable from the browser. WebFluid injects a small i18n.js client that mirrors the server API (_, _n, _p, _np) and caches the active locale in localStorage. We'll come back to client side wiring in the Frontend chapters — for now it is enough to know it is there.

Fallback catalogs

If you want gettext-style .po files as a static fallback below the runtime store, the Babel CLI extracts and compiles them for you, scanning both your project and the framework templates:

wf babel extract

This produces a messages.pot, initializes or updates the catalogs under translations/ and compiles them. The same step runs automatically if you ever scaffold a project with wf create project --babel-fallback.

Continue reading

From here you can continue straight with Security.