Skip to main content

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.

1

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.

Flask-Babel encapsula Babel (la biblioteca d’i18n per a Python) i l’integra amb el cicle de vida de les sol·licituds de Flask. Proporciona les funcions gettext(), ngettext() i lazy_gettext(), a més de la detecció automàtica de la configuració regional mitjançant les capçaleres del navegador.
Terminal
pip install Flask-Babel
2

Configurar 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
# babel.cfg — tells pybabel where to find translatable strings
[python: **.py]
[jinja2: **/templates/**.html]
extensions=jinja2.ext.autoescape,jinja2.ext.with_
app.py
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)
La funció locale_selector es crida en cada sol·licitud. Si retorna una configuració regional que no disposa d’un fitxer .mo compilat, Flask-Babel recorre silenciosament a la configuració regional predeterminada. No es genera cap error: les cadenes simplement apareixen sense traduir.
3

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.

app.py
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'))
templates/index.html
{# 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>
Utilitzi _() a les plantilles Jinja2 en lloc de gettext(): és l’abreviació estàndard de gettext i ajuda a mantenir netes les plantilles. Flask-Babel registra _() automàticament com a funció global de Jinja2.
4

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.

Terminal
# 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 translations
Executi sempre pybabel update i no init, després de la primera extracció. Si executa init en un directori d’idioma existent, se sobreescriuran totes les traduccions existents. L’ordre update incorpora les cadenes noves i conserva les traduccions existents.
5

Traduir 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
# 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"
Els fitxers PO inclouen comentaris contextuals (línies que comencen per #:) que mostren on s’utilitza cada cadena al codi font. Els traductors els fan servir per entendre el context. Conservi’ls: pybabel extract els genera automàticament.
6

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.

Terminal
# 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.
Si les traduccions no apareixen després d’editar un fitxer .po, gairebé segur que s’ha oblidat d’executar pybabel compile. Aquest és el problema més habitual de Flask-Babel. Afegeixi el pas de compilació al seu script de desplegament per evitar-lo en producció.
7

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.

app.py
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)
Plural forms in .po files
# 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 товаров в вашей корзине"
No utilitzi mai if count == 1 per implementar la lògica dels plurals. Idiomes com el francès tracten el 0 com a singular. El rus i l’àrab tenen formes que no existeixen en anglès. Deixi que ngettext() i les regles de plural CLDR de Babel facin la selecció.
8

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.

app.py
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']
    )
templates/components/language_switcher.html
{# 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>
Després de canviar la configuració regional de la sessió, cridi flask_babel.refresh() per forçar Flask-Babel a tornar a llegir-la per a la sol·licitud actual. Sense refresh(), la configuració regional anterior es manté fins a la sol·licitud següent.
9

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.

Terminal
# 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 translations
Tradueixi de manera incremental: quan afegeixi cadenes noves i executi pybabel update, tradueixi només les entrades noves sense traduir (valors msgstr buits), en lloc de regenerar-ho tot. Així es conserven les traduccions revisades per persones.

Extra: 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.

app.py
# 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)
flask-babel-locale-chain és un paquet Python de codi obert. Consulti’l a GitHub: github.com/i18n-agent/flask-babel-locale-chain.

Automatitzar la qualitat de les traduccions

Detecti amb i18n-validate les claus absents i els marcadors de posició malmesos abans que arribin a producció. Provi la interfície amb pseudotraduccions mitjançant i18n-pseudo abans que arribin les traduccions reals.

Errors habituals

Oblidar-se de compilar els fitxers .po a .mo

Flask-Babel llegeix fitxers .mo compilats, no fitxers .po. Si les traduccions no apareixen després d’editar els fitxers .po, executi pybabel compile -d translations. Afegeixi aquest pas al seu script de desplegament.

Utilitzar gettext() al nivell del mòdul

gettext() requereix un context de sol·licitud. Si defineix cadenes traduïdes al nivell del mòdul (atributs de classe o constants), utilitzi lazy_gettext(). Aquesta funció ajorna la traducció fins que la cadena es mostra realment en una sol·licitud.

L’extracció omet cadenes

pybabel extract només examina els fitxers que coincideixen amb els patrons de babel.cfg. Si no s’extreuen algunes cadenes, comprovi que els patrons de babel.cfg coincideixin amb l’estructura dels fitxers, afegeixi -k lazy_gettext per extreure les crides diferides i asseguri’s que les plantilles Jinja2 utilitzin l’extensió correcta (.html, .jinja2).

Errors de codificació dels fitxers PO

Els fitxers PO han d’estar codificats en UTF-8. Si veu UnicodeDecodeError, comprovi la capçalera Content-Type del fitxer .po: ha d’indicar charset=UTF-8. Alguns editors desen els fitxers amb codificacions diferents; verifiqui-ho sempre després d’editar-los.

Estructura de fitxers recomanada

Project Structure
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ó

No cal registrePressupost instantani

Preguntes freqüents sobre Flask i18n