Django i18n: Internationalization & Translation Guide

From settings.py to production: configure Django's translation system, write PO files, handle plurals, and automate translations with AI.

1

Install & Extract Strings

Django's i18n framework is built-in -- you just need to enable it. Install django-locale-chain for smart locale fallbacks, then use makemessages to extract translatable strings from your Python code and templates into PO files.

Django uses GNU gettext under the hood. The makemessages command scans your code for gettext calls and template tags, then generates .po files. After translation, compilemessages converts them to binary .mo files for fast lookup at runtime.
Terminal
pip install django-locale-chain
Terminal
# Extract all translatable strings from Python and template files
python manage.py makemessages -l de -l ja -l es -l fr

# After translating .po files, compile to .mo (binary)
python manage.py compilemessages

# Project structure after running makemessages:
# locale/
# ├── de/
# │   └── LC_MESSAGES/
# │       ├── django.po    <-- translate this
# │       └── django.mo    <-- compiled (auto-generated)
# ├── ja/
# │   └── LC_MESSAGES/
# │       ├── django.po
# │       └── django.mo
# └── es/
#     └── LC_MESSAGES/
#         ├── django.po
#         └── django.mo
2

Configure Settings & Middleware

Enable internationalization in settings.py by setting USE_I18N = True, defining your supported LANGUAGES list, and adding LocaleMiddleware to your MIDDLEWARE stack. LocaleMiddleware detects the user's language from the URL prefix, session, cookies, or Accept-Language header.

settings.py
# settings.py

from django.utils.translation import gettext_lazy as _

# Default language
LANGUAGE_CODE = 'en'

# Enable i18n
USE_I18N = True
USE_L10N = True

# Languages your site supports
LANGUAGES = [
    ('en', _('English')),
    ('de', _('German')),
    ('ja', _('Japanese')),
    ('es', _('Spanish')),
    ('fr', _('French')),
    ('pt-br', _('Brazilian Portuguese')),
]

# Where Django looks for .po files
LOCALE_PATHS = [
    BASE_DIR / 'locale',
]

MIDDLEWARE = [
    'django.middleware.security.SecurityMiddleware',
    'django.contrib.sessions.middleware.SessionMiddleware',
    'django.middleware.locale.LocaleMiddleware',       # <-- enables i18n
    'locale_chain.middleware.LocaleChainMiddleware',    # <-- smart fallbacks
    'django.middleware.common.CommonMiddleware',
    'django.middleware.csrf.CsrfViewMiddleware',
    'django.contrib.auth.middleware.AuthenticationMiddleware',
    'django.contrib.messages.middleware.MessageMiddleware',
    'django.middleware.clickjacking.XFrameOptionsMiddleware',
]
LocaleMiddleware must come after SessionMiddleware (it reads the session) and before CommonMiddleware. If placed in the wrong order, language detection silently fails and all users see the default LANGUAGE_CODE.

URL Internationalization

Use i18n_patterns() to automatically prefix your URLs with the active language code. This gives each language its own URL namespace (/en/about/, /de/about/) which is better for SEO and allows users to share language-specific links.

urls.py
# urls.py
from django.conf.urls.i18n import i18n_patterns
from django.urls import path, include

urlpatterns = [
    # Non-localized URLs (API, admin, etc.)
    path('api/', include('api.urls')),
]

urlpatterns += i18n_patterns(
    # These get prefixed with the language code: /en/about/, /de/about/
    path('', include('myapp.urls')),
    path('admin/', admin.site.urls),
    prefix_default_language=False,  # Skip prefix for default language
)
3

Mark Strings for Translation

Django provides two main translation functions: gettext() (aliased as _()) for strings evaluated at request time, and gettext_lazy() for strings evaluated at import time. In templates, use the {% trans %} and {% blocktrans %} tags.

In Views (Python Code)

views.py
from django.utils.translation import gettext as _
from django.utils.translation import ngettext
from django.http import HttpResponse

def greeting_view(request):
    # Simple translation
    welcome = _("Welcome to our site")

    # Translation with variables (Python string formatting)
    user_greeting = _("Hello, %(name)s!") % {"name": request.user.username}

    # Plurals
    count = request.user.order_set.count()
    order_text = ngettext(
        "You have %(count)d order.",
        "You have %(count)d orders.",
        count,
    ) % {"count": count}

    return HttpResponse(f"{welcome}<br>{user_greeting}<br>{order_text}")

In Templates

templates/myapp/index.html
{# Load the i18n template tags #}
{% load i18n %}

{# Simple translation #}
<h1>{% trans "Welcome to our site" %}</h1>

{# Translation with variables #}
{% blocktrans with name=user.username %}
  Hello, {{ name }}!
{% endblocktrans %}

{# Plurals in templates #}
{% blocktrans count count=order_count %}
  You have {{ count }} order.
{% plural %}
  You have {{ count }} orders.
{% endblocktrans %}

{# Mark strings as translatable but don't output them (for attributes, etc.) #}
{% trans "Submit" as submit_label %}
<button type="submit">{{ submit_label }}</button>

In Models & Forms

models.py
from django.db import models
from django.utils.translation import gettext_lazy as _

class Product(models.Model):
    name = models.CharField(_("product name"), max_length=200)
    description = models.TextField(_("description"), blank=True)

    class Meta:
        verbose_name = _("product")
        verbose_name_plural = _("products")

    def __str__(self):
        return self.name

# IMPORTANT: Use gettext_lazy (_) for anything evaluated at import time:
# - Model field labels, verbose_name, help_text
# - Form field labels
# - Class-level attributes
# Use gettext for anything evaluated at request time:
# - View functions, template tags
Using gettext() instead of gettext_lazy() in model fields, form labels, or class-level attributes causes strings to be translated once at import time (when the server starts) rather than per-request. The translation will be frozen in whatever language was active during import -- usually the default LANGUAGE_CODE.

PO File Format

After running makemessages, Django generates .po (Portable Object) files for each language. These contain msgid/msgstr pairs. Translate the msgstr values, then run compilemessages to generate the binary .mo files Django reads at runtime.

locale/de/LC_MESSAGES/django.po
# locale/de/LC_MESSAGES/django.po

msgid "Welcome to our site"
msgstr "Willkommen auf unserer Seite"

msgid "Hello, %(name)s!"
msgstr "Hallo, %(name)s!"

#, python-format
msgid "You have %(count)d order."
msgid_plural "You have %(count)d orders."
msgstr[0] "Sie haben %(count)d Bestellung."
msgstr[1] "Sie haben %(count)d Bestellungen."

msgid "product name"
msgstr "Produktname"

msgid "description"
msgstr "Beschreibung"

msgid "product"
msgstr "Produkt"

msgid "products"
msgstr "Produkte"

msgid "Submit"
msgstr "Absenden"
4

Handle Plurals & Variables

Django uses ngettext() for pluralization, which follows GNU gettext's plural rules. Each language defines how many plural forms it has and the formula for selecting the right form. PO files declare this with a Plural-Forms header.

Plural forms by language
# English: 2 forms (singular, plural)
msgid "%(count)d item"
msgid_plural "%(count)d items"
msgstr[0] "%(count)d item"
msgstr[1] "%(count)d items"

# German: 2 forms (singular, plural)
msgstr[0] "%(count)d Artikel"
msgstr[1] "%(count)d Artikel"

# Russian: 3 forms (one, few, many)
msgstr[0] "%(count)d товар"        # 1 item
msgstr[1] "%(count)d товара"       # 2-4 items
msgstr[2] "%(count)d товаров"      # 5+ items

# Arabic: 6 forms (zero, one, two, few, many, other)
msgstr[0] "لا عناصر"               # 0
msgstr[1] "عنصر واحد"              # 1
msgstr[2] "عنصران"                 # 2
msgstr[3] "%(count)d عناصر"        # 3-10
msgstr[4] "%(count)d عنصرًا"       # 11-99
msgstr[5] "%(count)d عنصر"         # 100+

# Japanese: 1 form (no plural distinction)
msgstr[0] "%(count)d個のアイテム"

# In Python code, always use ngettext:
from django.utils.translation import ngettext

msg = ngettext(
    "%(count)d item",
    "%(count)d items",
    count,
) % {"count": count}
Never use Python f-strings or .format() inside gettext calls. The translation extractor cannot parse them. Use old-style %() formatting: _('Hello, %(name)s!') % {'name': name}. This also ensures translators see the variable placeholders in their PO editors.

Automate Translation Quality

Catch missing keys and broken placeholders before they ship with i18n-validate. Test your UI with pseudo-translations using i18n-pseudo before real translations arrive.

Common Pitfalls

gettext() vs gettext_lazy() Confusion

Use gettext_lazy() (imported as _) for model fields, form labels, and any class-level attribute evaluated at import time. Use gettext() for view functions and request-time code. Mixing them up freezes translations in the server's startup language.

Forgot to Run compilemessages

Django reads .mo (compiled) files, not .po files. If you edit a .po file and don't run 'python manage.py compilemessages', your changes won't appear. Add compilemessages to your deployment script.

LOCALE_PATHS Not Configured

If LOCALE_PATHS is empty or points to the wrong directory, makemessages creates .po files in the wrong place and Django can't find them at runtime. Always set LOCALE_PATHS = [BASE_DIR / 'locale'] and verify the directory exists.

Missing i18n_patterns in URLs

Without i18n_patterns(), URLs have no language prefix and Django relies solely on cookies/headers for language detection. This hurts SEO (no language-specific URLs) and breaks language switching via URL. Wrap your user-facing URL patterns with i18n_patterns().

Smart Locale Fallbacks with django-locale-chain

Django's translation system falls back directly to LANGUAGE_CODE when a regional variant is missing. A pt-BR user sees English even when you have pt-PT translations. django-locale-chain fixes this by installing gettext fallback chains: pt-BR tries pt-PT, then pt, before falling back to your default language.

settings.py
# settings.py -- Smart fallback with django-locale-chain
# pip install django-locale-chain

MIDDLEWARE = [
    # ...
    'django.middleware.locale.LocaleMiddleware',
    'locale_chain.middleware.LocaleChainMiddleware',  # after LocaleMiddleware
    # ...
]

# That's it! 75 built-in fallback chains are now active:
# pt-BR user → tries pt-PT → tries pt → falls back to LANGUAGE_CODE
# es-MX user → tries es-419 → tries es → falls back to LANGUAGE_CODE
# fr-CA user → tries fr → falls back to LANGUAGE_CODE

# Optional: customize specific chains
LOCALE_FALLBACK_CHAINS = {
    "pt-BR": ["pt-PT", "pt"],
    "es-MX": ["es-419", "es"],
    "fr-CA": ["fr"],
}

# Or configure programmatically in AppConfig.ready():
from locale_chain import configure

class MyAppConfig(AppConfig):
    name = "myapp"

    def ready(self):
        configure(overrides={"zh-Hant-HK": ["zh-Hant-TW", "zh-Hant"]})

Recommended Project Structure

Project Structure
myproject/
├── myproject/
│   ├── settings.py          # i18n config, MIDDLEWARE, LANGUAGES
│   ├── urls.py              # i18n_patterns for URL prefixing
│   └── wsgi.py
├── myapp/
│   ├── models.py            # gettext_lazy for field labels
│   ├── views.py             # gettext for request-time strings
│   └── templates/
│       └── myapp/
│           └── index.html   # {% load i18n %}, {% trans %}, {% blocktrans %}
├── locale/                  # Created by makemessages
│   ├── de/
│   │   └── LC_MESSAGES/
│   │       ├── django.po    # German translations
│   │       └── django.mo    # Compiled binary
│   ├── ja/
│   │   └── LC_MESSAGES/
│   │       ├── django.po
│   │       └── django.mo
│   └── es/
│       └── LC_MESSAGES/
│           ├── django.po
│           └── django.mo
├── manage.py
└── requirements.txt

Also translate:

PO/Gettext Files
JSON Files
YAML Files
CSV Files
XML Files
Markdown Files

Try i18n Agent Now

Drop your translation file here

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

or click to browse

Target languages

No signup requiredInstant estimate

Frequently Asked Questions