Internationalization with Flask-Babel

pip install Flask-Babel

from datetime import date
from decimal import Decimal

from flask import Flask, abort, g, render_template, request, url_for
from flask_babel import Babel, force_locale, get_locale, gettext as _, lazy_gettext as _l, ngettext
from pytz import all_timezones_set

LANGUAGES = ["en", "es"]
BOOKS = [
    {"title": "Dune", "added": date(2026, 3, 14), "price": Decimal("12.50")},
    {"title": "Solaris", "added": date(2026, 9, 2), "price": Decimal("9.99")},
]
STATUS_LABELS = {"available": _l("Available"), "lent": _l("Lent out")}


def select_locale():
    lang_code = g.get("lang_code")          # set by the URL preprocessor below
    if lang_code in LANGUAGES:
        return lang_code
    return request.accept_languages.best_match(LANGUAGES)


def select_timezone():
    tz = request.cookies.get("tz")
    return tz if tz in all_timezones_set else None


def create_app():
    app = Flask(__name__)
    app.config["BABEL_DEFAULT_LOCALE"] = "en"
    Babel(app, locale_selector=select_locale, timezone_selector=select_timezone)

    @app.url_value_preprocessor
    def pull_lang_code(endpoint, values):
        if values and "lang_code" in values:
            g.lang_code = values.pop("lang_code")
            if g.lang_code not in LANGUAGES:
                abort(404)

    @app.url_defaults
    def add_lang_code(endpoint, values):
        if "lang_code" not in values and "lang_code" in g and app.url_map.is_endpoint_expecting(endpoint, "lang_code"):
            values["lang_code"] = g.lang_code

    @app.context_processor
    def inject_locale():
        locale = get_locale()
        return {"locale": locale, "languages": LANGUAGES}

    @app.route("/<lang_code>/books/")
    def books():
        title = ngettext("%(num)d book on the shelf", "%(num)d books on the shelf", len(BOOKS))
        return render_template("books.html", books=BOOKS, heading=title, statuses=STATUS_LABELS)

    @app.route("/<lang_code>/books/<int:book_id>/borrow", methods=["POST"])
    def borrow(book_id):
        return {"message": _("Book %(id)d is now lent out", id=book_id)}

    return app

app = create_app()
client = app.test_client()

# no prefix in the URL: the helper below is called with the header only
with app.test_request_context("/", headers={"Accept-Language": "fr-CH, fr;q=0.9, es;q=0.8"}):
    assert str(get_locale()) == "es"            # French is not supported, Spanish is the best match
with app.test_request_context("/", headers={"Accept-Language": "de"}):
    assert str(get_locale()) == "en"            # nothing matches: BABEL_DEFAULT_LOCALE
with app.test_request_context("/", headers={"Accept-Language": "es"}):
    assert get_locale().language == "es"

from flask_babel import get_timezone

with app.test_request_context("/", headers={"Cookie": "tz=Europe/Madrid"}):
    assert str(get_timezone()) == "Europe/Madrid"
with app.test_request_context("/", headers={"Cookie": "tz=Not/AZone"}):
    assert str(get_timezone()) == "UTC"          # rejected by select_timezone, default used

from flask_babel import refresh

with app.test_request_context("/", headers={"Accept-Language": "en"}):
    assert str(get_locale()) == "en"
    g.lang_code = "es"                           # imagine the profile form just saved this
    assert str(get_locale()) == "en"             # still cached
    refresh()
    assert str(get_locale()) == "es"

with app.test_request_context("/", headers={"Accept-Language": "es"}):
    assert _("Bookshelf") == "Estantería"
    assert _("Book %(id)d is now lent out", id=7) == "El libro 7 está ahora prestado"
    assert ngettext("%(num)d book on the shelf", "%(num)d books on the shelf", 1) == "1 libro en la estantería"
    assert ngettext("%(num)d book on the shelf", "%(num)d books on the shelf", 5) == "5 libros en la estantería"
with app.test_request_context("/", headers={"Accept-Language": "en"}):
    assert _("Bookshelf") == "Bookshelf"
assert _("Bookshelf") == "Bookshelf"             # no Flask context at all: the text is returned unchanged

<!doctype html>
<html lang="{{ locale }}" dir="{{ locale.text_direction }}">
<head><title>{{ _("Bookshelf") }}</title></head>
<body>
<h1>{{ _("Bookshelf") }}</h1>
<p>{{ heading }}</p>
{% trans user="Ada" %}Welcome back, {{ user }}!{% endtrans %}
<ul>
{% for book in books %}
  <li>{{ book.title }}
    <time datetime="{{ book.added.isoformat() }}">{{ book.added|dateformat("long") }}</time>
    {{ book.price|currencyformat("EUR") }}</li>
{% endfor %}
</ul>
<p>{% trans count=books|length %}{{ count }} book added this year.{% pluralize %}{{ count }} books added this year.{% endtrans %}</p>
<p>{{ statuses.available }}</p>
{% for code in languages %}<a href="{{ url_for('books', lang_code=code) }}" hreflang="{{ code }}">{{ code }}</a> {% endfor %}
</body>
</html>

[python: **.py]
[jinja2: templates/**.html]

# 1. extract every marked string into a template (.pot); -k also looks for lazy_gettext and the alias _l
pybabel extract -F babel.cfg -k lazy_gettext -k _l -o messages.pot .

# 2. create the catalog of a new language (writes translations/es/LC_MESSAGES/messages.po)
pybabel init -i messages.pot -d translations -l es

# 3. after the code changed: re-extract and merge new strings into the existing catalogs
pybabel extract -F babel.cfg -k lazy_gettext -k _l -o messages.pot .
pybabel update -i messages.pot -d translations

# 4. compile the .po files into the binary .mo files that Flask-Babel loads
pybabel compile -d translations --statistics

"Language: es\n"
"Plural-Forms: nplurals=2; plural=(n != 1);\n"

#: app.py:52
#, python-format
msgid "%(num)d book on the shelf"
msgid_plural "%(num)d books on the shelf"
msgstr[0] "%(num)d libro en la estantería"
msgstr[1] "%(num)d libros en la estantería"

#: templates/books.html:3 templates/books.html:5
msgid "Bookshelf"
msgstr "Estantería"

bookshelf-i18n/
├── app.py
├── babel.cfg
├── messages.pot
├── templates/
│   └── books.html
└── translations/
    └── es/
        └── LC_MESSAGES/
            ├── messages.mo
            └── messages.po

client = app.test_client()
spanish = client.get("/es/books/")
english = client.get("/en/books/")
assert spanish.status_code == 200 and english.status_code == 200
assert "<h1>Estantería</h1>" in spanish.text
assert "<h1>Bookshelf</h1>" in english.text
assert "2 libros en la estantería" in spanish.text
assert '<html lang="es" dir="ltr">' in spanish.text
assert 'href="/en/books/" hreflang="en"' in spanish.text       # language switcher keeps the same page
assert client.get("/fr/books/").status_code == 404

# the Accept-Language header does not override an explicit prefix
assert "<h1>Estantería</h1>" in client.get("/es/books/", headers={"Accept-Language": "en"}).text
assert client.post("/es/books/1/borrow").json == {"message": "El libro 1 está ahora prestado"}

from datetime import date, datetime, time, timedelta
from decimal import Decimal

from flask_babel import (format_currency, format_date, format_datetime, format_decimal, format_percent,
                         format_time, format_timedelta, to_user_timezone, to_utc)

moment = datetime(2026, 10, 7, 12, 0)             # naive datetimes are interpreted as UTC
with app.test_request_context("/", headers={"Accept-Language": "es"}):
    assert format_date(date(2026, 3, 14), "long") == "14 de marzo de 2026"
    assert format_currency(Decimal("1234.50"), "EUR") == "1.234,50\xa0€"
    assert format_decimal(1234567.891) == "1.234.567,891"
    assert format_percent(0.256) == "26\xa0%"
    assert format_timedelta(timedelta(days=3)) == "3 días"
with app.test_request_context("/", headers={"Accept-Language": "en"}):
    assert format_date(date(2026, 3, 14), "long") == "March 14, 2026"
    assert format_currency(Decimal("1234.50"), "EUR") == "€1,234.50"
    assert format_decimal(1234567.891) == "1,234,567.891"
    assert format_time(time(14, 30), "short") == "2:30\u202fPM"
    assert format_timedelta(timedelta(days=3), add_direction=True) == "in 3 days"

with app.test_request_context("/", headers={"Accept-Language": "en", "Cookie": "tz=Europe/Madrid"}):
    assert format_datetime(moment, "short") == "10/7/26, 2:00\u202fPM"                    # 12:00 UTC is 14:00 in Madrid in October
    assert format_datetime(moment, "short", rebase=False) == "10/7/26, 12:00\u202fPM"
    assert format_datetime(moment, "yyyy-MM-dd HH:mm zzz") == "2026-10-07 14:00 +0200"
    assert to_user_timezone(datetime(2026, 7, 1, 12)).hour == 14
    assert to_utc(datetime(2026, 7, 1, 14)) == datetime(2026, 7, 1, 12)           # the user typed 14:00 local time

import os
from flask_babel import Domain

admin_domain = Domain(translation_directories=[os.path.join(app.root_path, "translations")], domain="messages")
with app.test_request_context("/", headers={"Accept-Language": "es"}):
    assert admin_domain.gettext("Bookshelf") == "Estantería"
    assert repr(admin_domain).startswith("<Domain(")

import secrets

from flask_wtf import FlaskForm
from wtforms import StringField
from wtforms.validators import DataRequired

app.config["SECRET_KEY"] = secrets.token_hex()            # generated for this demo, never written in the source
app.config["WTF_CSRF_ENABLED"] = False                    # only to keep this demo short


class BookForm(FlaskForm):
    title = StringField(_l("Title"), validators=[DataRequired()])


with app.test_request_context("/", method="POST", headers={"Accept-Language": "es"}):
    form = BookForm()
    assert not form.validate()
    assert form.title.errors == ["Este campo es obligatorio."]
    assert str(form.title.label.text) == "Title"        # no catalog entry in the demo, so the original text is returned

from flask_babel import force_locale


def render_receipt(user_locale: str, book_id: int) -> str:
    with force_locale(user_locale):
        return _("Book %(id)d is now lent out", id=book_id)


with app.test_request_context("/", headers={"Accept-Language": "en"}):
    assert _("Bookshelf") == "Bookshelf"
    assert render_receipt("es", 3) == "El libro 3 está ahora prestado"      # the recipient's language
    assert _("Bookshelf") == "Bookshelf"                                  # the request's own language is restored

# a worker or a CLI command has an application context only
with app.app_context():
    assert render_receipt("es", 4) == "El libro 4 está ahora prestado"
    assert render_receipt("en", 4) == "Book 4 is now lent out"

import subprocess
import sys
import tempfile
from pathlib import Path

with tempfile.TemporaryDirectory() as tmp:
    pot = Path(tmp) / "messages.pot"
    result = subprocess.run(
        [sys.executable, "-m", "babel.messages.frontend", "extract", "-F", "babel.cfg", "-k", "lazy_gettext", "-k", "_l",
         "--no-location", "-o", str(pot), "."],
        capture_output=True, text=True, check=True)
    text = pot.read_text(encoding="utf-8")
    assert 'msgid "Bookshelf"' in text and 'msgid "Lent out"' in text

    stats = subprocess.run(
        [sys.executable, "-m", "babel.messages.frontend", "compile", "-d", "translations", "--statistics"],
        capture_output=True, text=True)
    assert "7 of 7 messages (100%) translated" in (stats.stdout + stats.stderr)