
Flask i18n: crear una aplicació multilingüe amb Flask-Babel
Des dels fonaments de gettext fins al desplegament en producció: internacionalitzi la seva aplicació Flask amb Flask-Babel, fitxers PO i traducció automatitzada amb IA.
Instal·lar Flask-Babel
Flask-Babel és l’extensió d’internacionalització estàndard per a Flask. Integra GNU gettext amb Flask i les plantilles Jinja2 i proporciona funcions de traducció, selecció de la configuració regional i compatibilitat amb fusos horaris de sèrie.
pip install Flask-BabelConfigurar Babel
Creï un fitxer babel.cfg per indicar a pybabel on ha de cercar cadenes traduïbles i, després, inicialitzi Flask-Babel amb una funció de selecció de configuració regional que determini quin idioma s’ha d’utilitzar en cada sol·licitud.
# babel.cfg — tells pybabel where to find translatable strings
[python: **.py]
[jinja2: **/templates/**.html]
extensions=jinja2.ext.autoescape,jinja2.ext.with_from flask import Flask, request
from flask_babel import Babel
app = Flask(__name__)
app.config['BABEL_DEFAULT_LOCALE'] = 'en'
app.config['BABEL_DEFAULT_TIMEZONE'] = 'UTC'
# Directory where translations live (default: "translations")
app.config['BABEL_TRANSLATION_DIRECTORIES'] = 'translations'
def get_locale():
# 1. Check URL parameter or session
# 2. Fall back to browser Accept-Language header
return request.accept_languages.best_match(['en', 'de', 'ja', 'es', 'fr'])
babel = Babel(app, locale_selector=get_locale)Marcar les cadenes per traduir
Embolcalli totes les cadenes visibles per a l’usuari amb gettext() al codi Python i amb _() a les plantilles Jinja2. Utilitzi lazy_gettext() per a les cadenes definides durant la càrrega del mòdul, com ara les etiquetes dels formularis i la configuració, que s’hagin de traduir més endavant quan es processi una sol·licitud.
from flask_babel import gettext, ngettext, lazy_gettext
# In views — gettext() for immediate translation
@app.route('/')
def index():
flash(gettext('Your profile has been updated.'))
return render_template('index.html',
title=gettext('Home'))
# In forms/config — lazy_gettext() for deferred translation
class LoginForm(FlaskForm):
username = StringField(lazy_gettext('Username'))
password = PasswordField(lazy_gettext('Password'))
submit = SubmitField(lazy_gettext('Sign In')){# In Jinja2 templates, use _() shorthand for gettext #}
<h1>{{ _('Welcome to our app') }}</h1>
<p>{{ _('Hello, %(name)s!', name=user.name) }}</p>
<footer>
{{ _('Copyright %(year)s Example Corp.', year=2026) }}
</footer>Extreure els missatges
Executi pybabel extract per examinar el codi font i les plantilles a la recerca de cadenes traduïbles. Això crea un fitxer .pot (Portable Object Template). Després, inicialitzi els catàlegs de cada idioma de destinació o actualitzi els existents quan canviïn les cadenes d’origen.
# Extract translatable strings from source code
pybabel extract -F babel.cfg -k lazy_gettext -o messages.pot .
# Initialize a new language (first time only)
pybabel init -i messages.pot -d translations -l de
pybabel init -i messages.pot -d translations -l ja
pybabel init -i messages.pot -d translations -l es
# Update existing catalogs when source strings change
pybabel update -i messages.pot -d translationsTraduir els fitxers PO
Obri els fitxers .po generats i empleni els valors msgstr de cada msgid. Els fitxers PO són de text pla: pot editar-los directament, utilitzar un editor de PO com Poedit o automatitzar-ne la traducció amb eines d’IA.
# translations/de/LC_MESSAGES/messages.po
msgid "Welcome to our app"
msgstr "Willkommen in unserer App"
msgid "Hello, %(name)s!"
msgstr "Hallo, %(name)s!"
msgid "Your profile has been updated."
msgstr "Ihr Profil wurde aktualisiert."
msgid "Username"
msgstr "Benutzername"
msgid "Password"
msgstr "Passwort"
msgid "Sign In"
msgstr "Anmelden"Compilar les traduccions
Compili els fitxers .po en fitxers binaris .mo mitjançant pybabel compile. Flask-Babel llegeix fitxers .mo durant l’execució i no pot llegir directament els fitxers .po. Cal tornar-los a compilar després de cada actualització de les traduccions.
# Compile .po files to binary .mo files (required at runtime)
pybabel compile -d translations
# Flask-Babel reads .mo files, not .po files.
# You MUST compile after every translation update.Gestionar plurals i variables
Utilitzi ngettext() per a les cadenes que varien segons el plural. Rep una forma singular, una forma plural i la quantitat. Babel aplica automàticament la regla de plural correcta per a cada idioma: l’anglès té 2 formes, però el rus en té 3, l’àrab en té 6 i el japonès en té 1.
from flask_babel import ngettext
@app.route('/cart')
def cart():
count = len(session.get('cart_items', []))
message = ngettext(
'%(num)d item in your cart', # singular
'%(num)d items in your cart', # plural
count # determines which form
)
return render_template('cart.html', message=message)# English: 2 forms (nplurals=2)
msgid "%(num)d item in your cart"
msgid_plural "%(num)d items in your cart"
msgstr[0] "%(num)d item in your cart"
msgstr[1] "%(num)d items in your cart"
# German: 2 forms (nplurals=2)
msgid "%(num)d item in your cart"
msgid_plural "%(num)d items in your cart"
msgstr[0] "%(num)d Artikel in Ihrem Warenkorb"
msgstr[1] "%(num)d Artikel in Ihrem Warenkorb"
# Japanese: 1 form (nplurals=1)
msgid "%(num)d item in your cart"
msgid_plural "%(num)d items in your cart"
msgstr[0] "カートに%(num)d個の商品があります"
# Russian: 3 forms (nplurals=3)
msgid "%(num)d item in your cart"
msgid_plural "%(num)d items in your cart"
msgstr[0] "%(num)d товар в вашей корзине"
msgstr[1] "%(num)d товара в вашей корзине"
msgstr[2] "%(num)d товаров в вашей корзине"Afegir el canvi de configuració regional
Creï un selector d’idioma que emmagatzemi la tria de l’usuari a la sessió de Flask. Actualitzi la funció locale_selector perquè comprovi primer la sessió i, si no hi troba cap preferència, recorri a la detecció del navegador.
from flask import session, redirect, url_for, request
from flask_babel import refresh
@app.route('/set-language/<lang>')
def set_language(lang):
session['lang'] = lang
refresh() # Force Flask-Babel to re-read the locale
return redirect(request.referrer or url_for('index'))
# Update get_locale to check session first
def get_locale():
# 1. Explicit user choice (stored in session)
if 'lang' in session:
return session['lang']
# 2. Browser Accept-Language header
return request.accept_languages.best_match(
['en', 'de', 'ja', 'es', 'fr']
){# Language switcher component #}
<nav class="language-switcher">
{% for lang, name in [('en','English'),('de','Deutsch'),
('ja','日本語'),('es','Español'),
('fr','Français')] %}
<a href="{{ url_for('set_language', lang=lang) }}"
class="{{ 'active' if get_locale() == lang }}">
{{ name }}
</a>
{% endfor %}
</nav>Automatitzar les traduccions
Un cop completada la configuració de Flask-Babel, tradueixi els fitxers PO amb IA. Automatitzi el cicle d’extracció, traducció i compilació a la seva canalització de CI/CD per mantenir les traduccions sincronitzades amb el codi font.
# Translate your PO files with AI directly from your IDE
# or use the CLI in CI/CD:
npx i18n-agent translate translations/de/LC_MESSAGES/messages.po \
--source-lang en --target-lang de
# Bulk translate all languages at once:
npx i18n-agent translate messages.pot --lang de,ja,es,fr
# Then compile:
pybabel compile -d translationsExtra: alternatives intel·ligents de configuració regional amb flask-babel-locale-chain
Per defecte, Flask-Babel recorre directament a la configuració regional predeterminada quan la preferida de l’usuari no està disponible. Un usuari de pt-BR que només disposa de traduccions pt-PT veu el contingut en anglès en lloc de portuguès. flask-babel-locale-chain afegeix cadenes d’alternatives configurables perquè les configuracions regionals relacionades s’encadenin de manera natural.
# pip install flask-babel-locale-chain
from flask_babel_locale_chain import LocaleChain
# Define fallback chains: pt-BR falls back to pt before en
locale_chain = LocaleChain({
'pt-BR': ['pt-BR', 'pt', 'en'],
'pt-PT': ['pt-PT', 'pt', 'en'],
'zh-Hant': ['zh-Hant', 'zh-Hans', 'en'],
'en-GB': ['en-GB', 'en', 'en-US'],
})
def get_locale():
requested = request.accept_languages.best_match(
['en', 'pt-BR', 'pt', 'zh-Hant', 'zh-Hans']
)
# Returns the best available locale from the chain
return locale_chain.resolve(requested)Automatitzar la qualitat de les traduccions
Errors habituals
Oblidar-se de compilar els fitxers .po a .mo
Utilitzar gettext() al nivell del mòdul
L’extracció omet cadenes
Errors de codificació dels fitxers PO
Estructura de fitxers recomanada
my-flask-app/
├── app.py # Flask app with Babel config
├── babel.cfg # Extraction config
├── messages.pot # Template (extracted strings)
├── translations/
│ ├── de/
│ │ └── LC_MESSAGES/
│ │ ├── messages.po # German translations (editable)
│ │ └── messages.mo # Compiled binary (generated)
│ ├── ja/
│ │ └── LC_MESSAGES/
│ │ ├── messages.po
│ │ └── messages.mo
│ └── es/
│ └── LC_MESSAGES/
│ ├── messages.po
│ └── messages.mo
├── templates/
│ ├── base.html
│ ├── index.html
│ └── components/
│ └── language_switcher.html
├── requirements.txt
└── venv/Provar i18n Agent ara
Arrossegar aquí el fitxer de traducció
JSON, YAML, PO, XML, CSV, Markdown, Properties
o fer clic per explorar
Idiomes de destinació