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.
pip install Flask-BabelVerified import paths — ran on the pinned version, not inferred.
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.
Upgrade Python to 3.8 or newer. Alternatively, pin `Flask-Babel<4.0.0`.
Update `Babel` to version 12.2 or higher (`pip install -U Babel`).
Upgrade Python to 3.7+ (preferably 3.8+ for v4.0.0) and Jinja2 to version 3 or greater (`pip install -U Jinja2`).
Replace any usage of `Babel._date_formats` with `Babel.date_formats`.
Update import statements from `from flask.ext.babel import ...` to `from flask_babel import ...`.
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.
Replace `@babel.localeselector` with `@babel.app.localeselector` (and similarly for `timezoneselector`) ensuring `babel.init_app(app)` has been called. Alternatively, import and use `get_locale` or `get_timezone` directly from `flask_babel`.
Pass the locale selector function as the `locale_selector` argument to the `Babel` constructor or the `init_app` method.
```python
from flask import Flask, request
from flask_babel import Babel
app = Flask(__name__)
def get_locale():
return request.accept_languages.best_match(['en', 'de', 'fr'])
babel = Babel(app, locale_selector=get_locale)
# or if initializing later: babel.init_app(app, locale_selector=get_locale)
```Ensure `Flask-Babel` is correctly installed in your current Python environment: ```bash pip install Flask-Babel ``` And make sure to import from `flask_babel`: ```python from flask_babel import Babel, gettext ```
1. Verify your `BABEL_TRANSLATION_DIRECTORIES` configuration in `app.config` points to the correct absolute or relative path of your `translations` folder. 2. Ensure you've run the `pybabel` commands in the correct order: `pybabel extract`, `pybabel init`, and `pybabel compile`. 3. Check that your `locale_selector` function (passed to `Babel(locale_selector=...)` or `init_app(locale_selector=...)`) is returning the desired locale string. 4. Confirm that your translation directories (e.g., `translations/fr/LC_MESSAGES/messages.mo`) match the exact case of the locale codes your application expects, especially on Linux-based deployments. 5. For strings outside the request context or in forms, consider using `lazy_gettext`.
Initialize the `Babel` object by passing your Flask application instance to its constructor or by using the `init_app` method: ```python from flask import Flask from flask_babel import Babel app = Flask(__name__) babel = Babel(app) # Pass the app instance directly # Or, if configuring later: # babel = Babel() # babel.init_app(app) ```