{"id":8136,"date":"2026-09-03T06:00:00","date_gmt":"2026-09-03T06:00:00","guid":{"rendered":"https:\/\/poeditor.com\/blog\/?p=8136"},"modified":"2026-09-03T08:00:35","modified_gmt":"2026-09-03T08:00:35","slug":"python-gettext-localization","status":"publish","type":"post","link":"https:\/\/poeditor.com\/blog\/python-gettext-localization\/","title":{"rendered":"Python gettext localization: How to translate a Python app"},"content":{"rendered":"\n
\"\"<\/figure>\n\n\n\n

Python has had a localization module in its standard library for a long time. gettext<\/a> uses the GNU gettext file formats, it has no dependencies, and it behaves the same in a Django site, a Flask app, or a command-line script.<\/p>\n\n\n\n

Python gettext localization involves four main steps: marking the strings you want translated, extracting them into catalog files, translating those catalogs, and loading the right one when the app runs. Preparing the code is Python internationalization (i18n); producing the translations is localization (l10n).<\/p>\n\n\n\n

This guide covers the full cycle on a small Flask to-do app\u2014marking strings in Python and Jinja, extracting them with Babel, managing the translations in POEditor, handling plurals and ambiguous words, and switching the interface between English and French.<\/p>\n\n\n\n

Setting up the project<\/h2>\n\n\n\n
\"\"
The TO-DO app with a list of tasks<\/em><\/figcaption><\/figure>\n\n\n\n

To follow this guide you need Python 3.9 or newer\u2014pgettext(), which we use later for translation context, was added in 3.8.
We\u2019ll localize TO-DO app, a small Flask project where users register, log in, and manage their to-do lists:<\/p>\n\n\n\n

The app uses a few routes, SQLite, and Jinja templates, with the kinds of strings you would normally find in a real application: page titles, form labels, flash messages, button text, and counts that change with the number of items. If you\u2019re bringing your own app, everything from the extraction step onwards works the same way.
Install the dependencies:<\/p>\n\n\n\n

pip install Flask Flask-Babel<\/code><\/pre>\n\n\n\n
Flask-Babel pulls in Babel, so that\u2019s the only install you need:<\/p>\n\n\n\n
# requirements.txt\nFlask==3.1.3\nFlask-Babel==4.0.0\nBabel==2.18.0<\/code><\/pre>\n\n\n\n
Python\u2019s documentation names three extraction tools: xgettext, pygettext.py and Babel<\/a>. Babel is a good fit here because it reads Jinja templates as well as .py files, and it can also compile catalogs and format dates and numbers by locale.
Flask-Babel<\/a> hooks it into Flask and selects a locale per request.<\/p>\n\n\n\n
The structure we\u2019re working with:<\/p>\n\n\n\n
app\/
\u251c\u2500 wsgi.py
\u251c\u2500 requirements.txt
\u251c\u2500 babel.cfg                  # tells Babel which files to scan
\u251c\u2500 messages.pot               # extracted source strings (generated)
\u2514\u2500 todoapp\/
  \u251c\u2500 __init__.py             # create_app(), Babel setup, locale selection
  \u251c\u2500 config.py               # supported locales and Babel settings
  \u251c\u2500 auth.py                 # register \/ log in \/ log out
  \u251c\u2500 todos.py                # list and task CRUD
  \u251c\u2500 templates\/
  \u2502  \u251c\u2500 base.html            # header with the language switcher
  \u2502  \u251c\u2500 index.html
  \u2502  \u251c\u2500 list.html
  \u2502  \u2514\u2500 auth\/
  \u2502     \u251c\u2500 login.html
  \u2502     \u2514\u2500 register.html
  \u2514\u2500 translations\/           # one folder per language
      \u2514\u2500 en\/LC_MESSAGES\/
        \u251c\u2500 messages.po
        \u2514\u2500 messages.mo<\/code><\/pre>\n\n\n\n
Run it with:<\/p>\n\n\n\n
flask --app wsgi run<\/code><\/pre>\n\n\n\n
Flask prints the address it\u2019s serving on. Register an account and look around: every string you see is hardcoded English.<\/p>\n\n\n\n
How localization works in Python<\/h2>\n\n\n\n
Python localization with gettext is a six-step cycle. Steps 1 and 2 repeat whenever you add or change text; steps 3 to 6 whenever you add a language.<\/p>\n\n\n\n
    \n
  1. Mark the translatable strings<\/strong> with _() or one of its variants.<\/li>\n\n\n\n
  2. Extract them<\/strong> into a .pot template, using Babel.<\/li>\n\n\n\n
  3. Create one `.po` catalog per language<\/strong> from that template.<\/li>\n\n\n\n
  4. Translate the catalogs<\/strong>, by hand or in a platform such as POEditor.<\/li>\n\n\n\n
  5. Compile each `.po` into a `.mo`<\/strong>, the binary format gettext reads.<\/li>\n\n\n\n
  6. Select a locale and load its catalog<\/strong> when the app runs.<\/li>\n<\/ol>\n\n\n\n
    Babel covers steps 2, 3 and 5, gettext covers 1 and 6, and step 4 is where POEditor comes in.<\/p>\n\n\n\n
    msgid, msgstr, and the three file types<\/h3>\n\n\n\n
    Each catalog entry pairs a source string, the msgid, with its translation, the msgstr:<\/p>\n\n\n\n
    msgid \"Create list\"
    msgstr \"Cr\u00e9er une liste\"<\/code><\/pre>\n\n\n\n
    At runtime gettext looks up the msgid<\/code> for the active locale and returns the msgstr. With no catalog, or no entry, it returns the msgid<\/code>\u2014the English text. That is why an untranslated app still runs, and why TO-DO app already offers French but renders in English apart from the dates:<\/p>\n\n\n\n
    \"\"
    French selected with no French catalog compiled yet<\/em><\/figcaption><\/figure>\n\n\n\n
    Three file types carry those entries. `.pot`<\/strong> is the template: every extracted source string with empty translations, regenerated from source rather than edited. `.po`<\/strong> is one language\u2019s catalog, holding the translations plus metadata\u2014source references, contexts, plural rules. `.mo`<\/strong> is the compiled .po that gettext actually reads, so an edited translation does nothing until you recompile.<\/p>\n\n\n\n
    They live in a tree keyed by locale, each catalog named after the gettext domain<\/strong>\u2014messages here:<\/p>\n\n\n\n
    translations\/
    \u251c\u2500\u2500 en\/LC_MESSAGES\/messages.po, messages.mo
    \u2514\u2500\u2500 fr\/LC_MESSAGES\/messages.po, messages.mo<\/code><\/pre>\n\n\n\n
    The two gettext APIs<\/h3>\n\n\n\n
    The GNU-style API<\/strong> mirrors the C library: you bind a domain to a directory and install _() for the whole process.<\/p>\n\n\n\n
    Python\u2019s documentation is explicit: \u201cIf you use this API you will affect the translation of your entire application globally.\u201d That suits a command-line tool that picks its language once, from the environment.<\/p>\n\n\n\n
    The class-based API<\/strong> returns a translation object instead:<\/p>\n\n\n\n
    # app.py
    import gettext

    translation = gettext.translation(
        \"messages\", localedir=\"locale\", languages=[\"fr\"],
    )
    _ = translation.gettext<\/code><\/pre>\n\n\n\n
    The documentation calls this \u201cthe recommended way of localizing your Python applications and modules\u201d, and points to it for applications that \u201cneed to switch languages on the fly\u201d\u2014any web app, since it serves several languages from one process.<\/p>\n\n\n\n
    Frameworks wrap this API rather than replacing it. Flask-Babel and Django both call into gettext<\/code>, use the same .po<\/code> and .mo<\/code> files, and add per-request locale selection and template integration. TO-DO app imports gettext<\/code> from flask_babel<\/code>; everything from step 2 onward is identical either way.<\/p>\n\n\n\n
    Marking strings for translation<\/h2>\n\n\n\n
    Marking a string means wrapping it in a function call, which does two jobs: at runtime it looks the string up in the active catalog, and at extraction time it tells Babel the string needs translating.<\/p>\n\n\n\n
    In Python modules<\/h3>\n\n\n\n
    Import gettext<\/code> as _<\/code>, the name extraction tools look for by default. With Flask-Babel it comes from flask_babel<\/code> rather than the standard library:<\/p>\n\n\n\n
    # todoapp\/auth.py\nfrom flask_babel import gettext as _<\/code><\/pre>\n\n\n\n
    Then wrap the user-facing strings. The registration view, with its bare literals replaced:<\/p>\n\n\n\n
    # todoapp\/auth.py\nerror = _(\"Password must be at least 6 characters long.\")\nflash(_(\"Account created. You can log in now.\"), \"success\")\nreturn render_template(\"auth\/register.html\", title=_(\"Create an account\"))<\/code><\/pre>\n\n\n\n
    Page titles count, since they reach the <title><\/code> tag and the <h1><\/code>.<\/p>\n\n\n\n
    When a message contains a value, keep the whole sentence inside the call and pass the value as a named<\/strong> placeholder:<\/p>\n\n\n\n
    # todoapp\/auth.py\nerror = _(\"The username \u201c%(username)s\u201d is already taken.\", username=username)<\/code><\/pre>\n\n\n\n
    A translator can move %(username)s<\/code> anywhere the sentence requires, and can tell what will be substituted. Positional %s <\/code>gives them neither.<\/p>\n\n\n\n
    In Jinja templates<\/h3>\n\n\n\n
    Flask-Babel installs the same functions into the Jinja environment, so templates call _() with no import:<\/p>\n\n\n\n
    {# todoapp\/templates\/index.html #}\n<label for=\"name\" class=\"form-label\">{{ _('New list') }}<\/label>\n<input id=\"name\" name=\"name\" class=\"form-control\"\n      placeholder=\"{{ _('e.g. Groceries') }}\">\n<button type=\"submit\" class=\"btn btn-primary\">{{ _('Create list') }}<\/button><\/code><\/pre>\n\n\n\n
    Note the placeholder<\/code>. Attribute text sits outside the tags and is easy to miss, but a user reads it\u2014and so do title<\/code> and aria-label<\/code>, including the ones your UI framework generates. TO-DO app\u2019s _(\"Menu\"<\/code>) and _(\"Close\"<\/code>) strings come from Bootstrap\u2019s navbar toggle and dismissible alerts:<\/p>\n\n\n\n
    {# todoapp\/templates\/list.html #}
    <button type=\"submit\" title=\"{{ _('Toggle done') }}\"><\/code><\/pre>\n\n\n\n
    What to leave alone<\/h3>\n\n\n\n
    Not every string is for a human. Leaving these unmarked keeps the catalog to what translators can work on:<\/p>\n\n\n\n