Django ships a complete translation system built on GNU gettext, but the pieces are spread across settings, middleware, URL config, two management commands, and a file format most web developers have never opened. This guide walks through the whole pipeline on Django 6, with every command and code sample tested on a real project.
Django does not translate anything at runtime by itself. It looks up strings you have marked in a compiled catalog for the active language. The pipeline has five steps:
gettext and in templates with {% translate %}.makemessages, which writes one .po file per language.msgstr entries in each .po file.compilemessages into binary .mo files, which are what Django actually reads.LocaleMiddleware, usually from a URL prefix like /de/.Most "my translations don't show up" bugs come from skipping step 4 or misconfiguring step 5, so both get their own sections below.
Start with four settings and one middleware:
# settings.py
from django.utils.translation import gettext_lazy as _
USE_I18N = True
LANGUAGE_CODE = "en"
LANGUAGES = [
("en", _("English")),
("de", _("German")),
("pl", _("Polish")),
]
LOCALE_PATHS = [BASE_DIR / "locale"]
MIDDLEWARE = [
"django.middleware.security.SecurityMiddleware",
"django.contrib.sessions.middleware.SessionMiddleware",
"django.middleware.locale.LocaleMiddleware",
"django.middleware.common.CommonMiddleware",
# ...
]LANGUAGES restricts Django to the languages you actually ship. Without it, Django falls back to its default list of 100 languages and will activate any of them from a browser header, so your pages can come out in a language you never translated.LOCALE_PATHS is where project-level catalogs live. App-level catalogs go in each app's own locale/ folder and are found automatically.LocaleMiddleware must come after SessionMiddleware and before CommonMiddleware. It reads the language from the URL prefix, then the language cookie, then the Accept-Language header.gettext_lazy in settings. The translation system is not ready when settings load, and the lazy version only translates when the value is rendered.Four functions cover almost everything. Here they are in one view:
# shop/views.py
from django.shortcuts import render
from django.utils.translation import gettext as _, ngettext, pgettext
def cart(request):
count = int(request.GET.get("n", 3))
context = {
"title": _("Your cart"),
"summary": ngettext(
"%(count)d item in your cart",
"%(count)d items in your cart",
count,
) % {"count": count},
"order_button": pgettext("verb", "Order"),
"count": count,
}
return render(request, "shop/cart.html", context)gettext (aliased to _) translates a single string at the moment it runs. Use it in views and functions.ngettext handles plurals. You pass the English singular and plural plus the count, and each language's catalog supplies as many forms as it needs. Polish needs four, Arabic six.pgettext adds context. "Order" as a verb on a button and "Order" as a noun in a table header are different words in German (Bestellen and Bestellung), and the context keeps them separate in the catalog.%(count)d, never f-strings or concatenation. An f-string is formatted before gettext sees it, so the lookup key changes with every value and nothing ever matches the catalog.
Model fields, Meta options, and form labels are evaluated once, when the module is imported. If you use plain gettext there, the string is frozen in whatever language was active at import time, usually the default one. Use gettext_lazy:
# shop/models.py
from django.db import models
from django.utils.translation import gettext_lazy as _
class Product(models.Model):
name = models.CharField(_("name"), max_length=200)
class Meta:
verbose_name = _("product")
verbose_name_plural = _("products"){% load i18n %}
<h1>{{ title }}</h1>
<p>{{ summary }}</p>
<button>{{ order_button }}</button>
<p>{% translate "Free shipping on orders over EUR 50" %}</p>
{% blocktranslate count counter=count trimmed %}
You saved money on {{ counter }} product.
{% plural %}
You saved money on {{ counter }} products.
{% endblocktranslate %}{% translate %} handles a plain string. It also accepts context "verb", the template equivalent of pgettext.{% blocktranslate %} handles strings with variables. Variables must be simple names, so assign anything more complex with with first.count counter=... plus {% plural %} gives you a plural-aware block.trimmed collapses the template's whitespace and line breaks, so the msgid in your catalog is one clean sentence instead of a string full of indentation.python manage.py makemessages -l de -l pl
This scans your Python files and templates and writes locale/de/LC_MESSAGES/django.po and locale/pl/LC_MESSAGES/django.po. Run it again whenever strings change; it merges new strings in and keeps existing translations. It needs the GNU gettext tools installed (brew install gettext on macOS, apt install gettext on Debian and Ubuntu). For JavaScript files, run it a second time with -d djangojs.
Here is what the plural string from the view looks like in the Polish catalog after translation:
"Plural-Forms: nplurals=4; plural=(n==1 ? 0 : (n%10>=2 && n%10<=4) && (n%100<12 || n%100>14) ? 1 : n!=1 && (n%10>=0 && n%10<=1) || (n%10>=5 && n%10<=9) || (n%100>=12 && n%100<=14) ? 2 : 3);\n"
#: shop/views.py:10
#, python-format
msgid "%(count)d item in your cart"
msgid_plural "%(count)d items in your cart"
msgstr[0] "%(count)d produkt w koszyku"
msgstr[1] "%(count)d produkty w koszyku"
msgstr[2] "%(count)d produktów w koszyku"
msgstr[3] "%(count)d produktu w koszyku"
#: shop/views.py:14
msgctxt "verb"
msgid "Order"
msgstr "Zamów"Plural-Forms header tells gettext how many forms the language has and which index to pick for a given number. Django fills it in from its own knowledge of each language; leave it alone.msgstr[0] to msgstr[3] are Polish's four forms. With this catalog, Django renders "1 produkt", "3 produkty", "5 produktów", and "22 produkty", following the Polish rule that 22 to 24 behave like 2 to 4.#, fuzzy marks an entry that makemessages guessed from a similar old string. Fuzzy entries are skipped at compile time, so a "translated" string that never appears is often just fuzzy. Review it and delete the flag.For more on how plural categories differ across languages, see our ICU MessageFormat plurals guide. gettext uses numbered forms instead of named categories, but the language rules underneath are the same CLDR data.
python manage.py compilemessages --ignore=.venv
This turns every .po file it finds into a .mo file. Django only reads .mo files, so a translation that is in your .po but not compiled does not exist as far as your site is concerned.
The --ignore flag matters more than it looks. compilemessages walks every directory under the project, and if your virtualenv lives inside the project folder, it will recompile the hundreds of catalogs that ship inside Django and every other installed package. That is slow at best and fails outright when those directories are read-only.
Decide where compilation happens in deployment. Either commit the .mo files, or run compilemessages in your build step next to collectstatic. Forgetting both is the single most common reason translations work locally and vanish in production.
# urls.py
from django.conf.urls.i18n import i18n_patterns
from django.urls import include, path
from shop import views
urlpatterns = [
path("i18n/", include("django.conf.urls.i18n")), # set_language view
]
urlpatterns += i18n_patterns(
path("cart/", views.cart, name="cart"),
prefix_default_language=False,
)
i18n_patterns serves /de/cart/ and /pl/cart/ in German and Polish. One setting decides what happens on the unprefixed URL, and it trips people up:
prefix_default_language |
Request for /cart/ with Accept-Language: pl |
|---|---|
True (default) |
302 redirect to /pl/cart/ |
False |
200, rendered in English (LANGUAGE_CODE) |
With False, the unprefixed URL is the default language, so Django does not redirect based on the browser's preferences. That is usually what you want for SEO, because every language has one stable URL that search engines can index and link with hreflang. If you want automatic redirects from the browser language, use True and accept that every URL carries a prefix, including the default language.
For a language switcher, post to the set_language view that django.conf.urls.i18n provides. It stores the choice in a cookie and redirects to the next URL.
If your templates load JavaScript that shows user-facing text, Django can serve a catalog for it:
# urls.py
from django.views.i18n import JavaScriptCatalog
urlpatterns += i18n_patterns(
path("jsi18n/", JavaScriptCatalog.as_view(), name="javascript-catalog"),
)
Include {% url 'javascript-catalog' %} as a script, and gettext(), ngettext(), and interpolate() become available in the browser. Extract the strings with makemessages -d djangojs -l de. For a heavy single-page frontend, a dedicated JavaScript i18n library is usually a better fit; see react-i18next or next-intl.
Use translation.override in tests to render a view or function in a specific language without touching request state:
from django.test import TestCase
from django.utils import translation
class CartTranslationTests(TestCase):
def test_polish_plural(self):
response = self.client.get("/pl/cart/?n=22")
self.assertContains(response, "22 produkty w koszyku")
def test_lazy_model_label(self):
from shop.models import Product
with translation.override("de"):
self.assertEqual(str(Product._meta.verbose_name), "Produkt")Test the plural edge cases for your hardest language, not just 1 and 5. For Polish that means 0, 1, 2, 5, 12, 22, and 25. Our pseudo-localization guide covers how to catch untranslated strings before a translator ever sees them.
.mo files were never compiled or deployed.gettext instead of gettext_lazy..po file but never appears. It is marked #, fuzzy, or the msgid no longer matches the source because someone edited the English text._("Hello") + ", " + name forces every language into English word order. Translate the whole sentence with a placeholder.LocaleMiddleware is in the wrong position, or prefix_default_language=False is serving the default language on unprefixed URLs as designed.LANGUAGES is not set, so Django activates languages you never translated.
The slow part of Django i18n is rarely the settings. It is wrapping hundreds of existing strings in gettext and {% translate %}, then keeping every .po file in sync as the code changes. Babelize does that step for Django projects: it marks strings in Python files (models, forms, admin, views) and templates, writes gettext .po catalogs while keeping existing translations, recompiles tracked .mo files, and sets LANGUAGES and LOCALE_PATHS, all delivered as a pull request you review like any other change.
gettext translates immediately, using the language active at that moment. gettext_lazy returns a proxy that translates when it is rendered. Use the lazy version anywhere that runs at import time, such as model fields, form labels, and settings, and plain gettext inside views and functions.
Check four things in order: the .mo files exist and are newer than the .po files, the entry is not marked fuzzy, the msgid exactly matches the source string, and LocaleMiddleware sits between SessionMiddleware and CommonMiddleware.
Either commit them or compile them in your build step. Committing is simpler and avoids needing gettext installed on the server. Compiling at build time keeps generated files out of the repository. What does not work is doing neither.
Each .po file has a Plural-Forms header with the number of forms and a formula that picks one for any number. ngettext and {% blocktranslate count %} use that formula, so Polish gets four msgstr entries and Arabic six, while your code passes only the English singular and plural.
Only when prefix_default_language is True. Then a request for an unprefixed URL is redirected to the prefixed URL for the language in the Accept-Language header. With False, unprefixed URLs are always served in LANGUAGE_CODE.
Set LANGUAGES, LOCALE_PATHS, and LocaleMiddleware. Mark strings with gettext, gettext_lazy for anything evaluated at import time, ngettext for plurals, and pgettext for ambiguous words. Run makemessages, translate, run compilemessages --ignore=.venv, and make sure the .mo files reach production. Use i18n_patterns for language URLs, and choose prefix_default_language deliberately.