Skip to main content

Flask i18n: Bygg en flerspråklig app med Flask-Babel

Fra gettext-grunnleggende til driftsetting i produksjon: internasjonaliser Flask-appen din med Flask-Babel, PO-filer og automatisert AI-oversettelse.

1

Installer Flask-Babel

Flask-Babel er standardutvidelsen for internasjonalisering i Flask. Den integrerer GNU gettext med Flask og Jinja2-maler, og har innebygd støtte for oversettelsesfunksjoner, valg av språkinnstilling og tidssoner.

Flask-Babel bygger på Babel (Python-biblioteket for i18n) og integrerer det med Flasks livssyklus for forespørsler. Det gir deg funksjonene gettext(), ngettext() og lazy_gettext(), i tillegg til automatisk registrering av språkinnstillingen fra nettleserens HTTP-hoder.
Terminal
pip install Flask-Babel
2

Konfigurer Babel

Opprett en babel.cfg-fil for å fortelle pybabel hvor den skal lete etter oversettbare strenger, og initialiser deretter Flask-Babel med en funksjon som velger hvilket språk som skal brukes for hver forespørsel.

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)
Funksjonen locale_selector kalles for hver forespørsel. Hvis den returnerer en språkinnstilling som ikke har en kompilert .mo-fil, faller Flask-Babel stille tilbake til standardspråket. Ingen feil kastes — strengene vises bare uoversatt.
3

Merk strenger for oversettelse

Pakk inn hver brukervendte streng med gettext() i Python-kode og _() i Jinja2-maler. Bruk lazy_gettext() for strenger som defineres ved modulinnlasting (som skjemaetiketter og konfigurasjon) og som må oversettes senere ved forespørselstidspunktet.

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>
Bruk _() i Jinja2-maler i stedet for gettext() — det er den vanlige forkortelsen for gettext og holder malene dine rene. Flask-Babel registrerer _() som en global Jinja2-funksjon automatisk.
4

Trekk ut meldinger

Kjør pybabel extract for å skanne kildekoden og malene dine etter oversettbare strenger. Dette oppretter en .pot-fil (Portable Object Template). Initialiser deretter kataloger for hvert målspråk, eller oppdater eksisterende når kildestrengene endres.

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
Kjør alltid pybabel update (ikke init) etter den første ekstraheringen. Å kjøre init på en eksisterende språkkatalog overskriver alle eksisterende oversettelser. Update-kommandoen slår sammen nye strenger samtidig som eksisterende oversettelser bevares.
5

Oversett PO-filer

Åpne de genererte .po-filene og fyll inn msgstr-verdiene for hver msgid. PO-filer er ren tekst — du kan redigere dem direkte, bruke en PO-editor som Poedit, eller automatisere oversettelsen med AI-verktøy.

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"
PO-filer inneholder kontekstkommentarer (linjer som starter med #:) som viser hvor hver streng brukes i kildekoden. Oversettere bruker disse til å forstå konteksten. Behold dem — de genereres automatisk av pybabel extract.
6

Kompiler oversettelser

Kompiler .po-filene dine til binære .mo-filer ved hjelp av pybabel compile. Flask-Babel leser .mo-filer ved kjøretid — den kan ikke lese .po-filer direkte. Du må rekompilere etter hver oversettelsesoppdatering.

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.
Hvis oversettelser ikke vises etter at du har redigert en .po-fil, har du nesten helt sikkert glemt å kjøre pybabel compile. Dette er det vanligste problemet med Flask-Babel. Legg til kompileringssteget i driftsettingsskriptet ditt for å unngå det i produksjon.
7

Håndter flertallsformer og variabler

Bruk ngettext() for strenger som er følsomme for flertallsform. Den tar en entallsform, en flertallsform og antallet. Babel bruker automatisk riktig flertallsregel for hvert språk — engelsk har 2 former, mens russisk har 3, arabisk har 6, og japansk har 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 товаров в вашей корзине"
Bruk aldri if count == 1 for flertallslogikk. Språk som fransk behandler 0 som entall. Russisk og arabisk har former som engelsk ikke har. La ngettext() og Babels CLDR-flertallsregler håndtere valget.
8

Legg til bytte av locale

Bygg en språkvelger som lagrer brukerens valg i Flask-økten. Oppdater locale_selector-funksjonen din til å sjekke økten først, og deretter falle tilbake til nettleserdeteksjon.

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>
Etter at du har endret språkinnstillingen i økten, kall flask_babel.refresh() for å tvinge Flask-Babel til å lese språkinnstillingen på nytt for den aktive forespørselen. Uten refresh() brukes den gamle språkinnstillingen frem til neste forespørsel.
9

Automatiser oversettelser

Når Flask-Babel-oppsettet ditt er fullført, kan du oversette PO-filene dine ved hjelp av AI. Automatiser ekstraher-oversett-kompiler-syklusen i CI/CD-pipelinen din for å holde oversettelsene synkronisert med kildekoden.

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
Oversett trinnvis — når du legger til nye strenger og kjører pybabel update, oversett bare de nye uoversatte oppføringene (tomme msgstr-verdier) i stedet for å regenerere alt. Dette bevarer menneskelig kvalitetssikrede oversettelser.

Bonus: Smart locale-tilbakefall med flask-babel-locale-chain

Som standard faller Flask-Babel direkte tilbake til standardspråket når brukerens foretrukne språkinnstilling ikke er tilgjengelig. En pt-BR-bruker med bare pt-PT-oversettelser ser engelsk i stedet for portugisisk. flask-babel-locale-chain legger til konfigurerbare reservekjeder slik at relaterte språkinnstillinger brukes i en naturlig rekkefølge.

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 er en åpen kildekode-pakke for Python. Se den på GitHub på github.com/i18n-agent/flask-babel-locale-chain.

Automatiser oversettelseskvalitet

Fang opp manglende nøkler og ødelagte plassholdere før de driftsettes med i18n-validate. Test brukergrensesnittet ditt med pseudo-oversettelser ved hjelp av i18n-pseudo før de virkelige oversettelsene er klare.

Vanlige fallgruver

Glemte å kompilere .po til .mo

Flask-Babel leser kompilerte .mo-filer, ikke .po-filer. Hvis oversettelser ikke vises etter redigering av .po-filer, kjør pybabel compile -d translations. Legg til dette steget i driftsettingsskriptet ditt.

Bruker gettext() på modulnivå

gettext() krever en forespørselskontekst. Hvis du definerer oversatte strenger på modulnivå (klasseattributter, konstanter), bruker du lazy_gettext() i stedet. Den utsetter oversettelsen til strengen faktisk vises i en forespørsel.

Ekstrahering går glipp av strenger

pybabel extract skanner bare filer som matcher mønstrene i babel.cfg. Hvis strenger ikke blir ekstrahert: sjekk at babel.cfg-mønstrene dine matcher filstrukturen din, legg til -k lazy_gettext for å ekstrahere lazy-kall, og sørg for at Jinja2-malene bruker riktig filending (.html, .jinja2).

Tegnkodingsfeil i PO-filer

PO-filer må være UTF-8-kodet. Hvis du ser UnicodeDecodeError, sjekk Content-Type-headeren i .po-filen din: den skal si charset=UTF-8. Enkelte editorer lagrer med andre tegnkodinger — verifiser alltid etter redigering.

Anbefalt filstruktur

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/

Prøv i18n Agent nå

Slipp oversettelsesfilen din her

JSON, YAML, PO, XML, CSV, Markdown, Properties

eller klikk for å bla gjennom

Målspråk

Ingen registrering krevesUmiddelbart estimat

Flask i18n – ofte stilte spørsmål