Flask-Babel

4.0.0 · active · verified Mon Apr 06

Flask-Babel is an extension for the Flask micro-framework that adds internationalization (i18n) and localization (l10n) support to Flask applications. It provides built-in features for date and time formatting with timezone support, as well as a friendly interface for gettext translations. The library is actively maintained, with the current version being 4.0.0, and has a consistent release cadence.

Warnings

breaking Version 4.0.0 dropped support for Python 3.7. Applications running on Python 3.7 or older must upgrade their Python environment or use an older Flask-Babel version.
Fix: Upgrade Python to 3.8 or newer. Alternatively, pin `Flask-Babel<4.0.0`.
breaking Version 3.1.0 requires Babel 12.2 or greater. Ensure your `babel` package is updated to avoid compatibility issues, particularly with localized time formatting.
Fix: Update `Babel` to version 12.2 or higher (`pip install -U Babel`).
breaking Version 3.0.0 made several significant breaking changes, including dropping support for Python 3.5 and 3.6, and requiring Jinja version 3 or greater.
Fix: Upgrade Python to 3.7+ (preferably 3.8+ for v4.0.0) and Jinja2 to version 3 or greater (`pip install -U Jinja2`).
breaking In version 3.0.0, the internal attribute `Babel._date_formats` was removed. Users should now use the public `Babel.date_formats` attribute instead.
Fix: Replace any usage of `Babel._date_formats` with `Babel.date_formats`.
gotcha Older Flask extensions used the `flask.ext` namespace (e.g., `flask.ext.babel`). This pattern is deprecated. Always import directly from `flask_babel`.
Fix: Update import statements from `from flask.ext.babel import ...` to `from flask_babel import ...`.
gotcha Flask-Babel defaults the `BABEL_DEFAULT_TIMEZONE` to 'UTC'. It is crucial that your application internally uses 'UTC' for date and time storage to prevent unexpected behavior with user-facing localized dates.
Fix: Ensure all date and time storage and manipulation within your application consistently uses UTC. Convert to local timezones only at the presentation layer using Flask-Babel's formatting functions.

Install

pip install Flask-Babel Install latest version

Imports

Babel
```
from flask_babel import Babel
```
The `flask.ext` prefix was deprecated in Flask for extensions; direct import from `flask_babel` is correct since Flask 0.8.
gettext
```
from flask_babel import gettext
from flask_babel import _
```
Both `gettext` and `_` are commonly used aliases for marking translatable strings.

Quickstart

This quickstart demonstrates how to initialize Flask-Babel with a Flask application, set up default locales and available languages, and define a `localeselector` function to determine the user's preferred language. It also includes basic usage of `gettext` for string internationalization and outlines the necessary `pybabel` commands for translation file management.

from flask import Flask, render_template, request
from flask_babel import Babel, gettext

app = Flask(__name__)
app.config['BABEL_DEFAULT_LOCALE'] = 'en'
app.config['LANGUAGES'] = {'en': 'English', 'de': 'Deutsch'}

babel = Babel(app)

@babel.localeselector
def get_locale():
    # Try to guess the language from the user's browser accept header
    # or use a default/configured locale.
    return request.accept_languages.best_match(list(app.config['LANGUAGES'].keys()))

@app.route('/')
def index():
    return f"<h1>{gettext('Hello, World!')}</h1>"

# To run this example, you would also need a `messages.po` file and compile it.
# 1. Create a `babel.cfg` file:
#    [python: **.py]
#    [jinja2: **/templates/**.html]
# 2. Extract messages:
#    pybabel extract -F babel.cfg -o messages.pot .
# 3. Initialize translation for a language (e.g., German):
#    pybabel init -i messages.pot -d translations -l de
# 4. Translate strings in `translations/de/LC_MESSAGES/messages.po`
# 5. Compile translations:
#    pybabel compile -d translations

if __name__ == '__main__':
    app.run(debug=True)

view raw JSON →