Internationalization & Translation

English has two plural forms; Polish has three, Arabic six, Japanese one. Django therefore never asks you to decide which form to use: you give the singular, the plural and the number, and the catalogue’s Plural-Forms rule picks.

Source: Django: Translation — Pluralization

The Polish catalogue in the scratch project declares nplurals=3 with the standard Polish rule, and the test below passes 1, 2, 5 and 22 to the same call:

Source: Django: Translation — Pluralization

Three pitfalls the official page spells out:

Source: Django: Translation — Lazy translations and plural

If a lazy plural string contains exactly one unnamed placeholder you can interpolate the number directly: message % number.

The English word May is a month and a verb; many languages use two different words. pgettext(context, message) (and npgettext(context, singular, plural, number) when it also pluralizes) adds a context string that becomes a msgctxt line, so the same msgid can have one translation per context.

Source: Django: Translation — Contextual markers

With the Dutch catalogue active, the home page prints mei / mogen / mei for pgettext("month name", …), pgettext("verb", …) and the template tag {% translate "May" context "month name" %} respectively.

gettext_noop marks a string for extraction but returns it unchanged. Use it for constants that must stay in the source language because they travel through other systems (a status stored in a database, a value in an API) and that you translate at the last moment, when they are shown.

Source: Django: Translation — Marking strings as no-op

Under the Dutch catalogue STATUS_LABELS["live"] is still "Published" while shown becomes Concept, Online gezet (the project-level catalogue overrides the app’s, see How Django discovers catalogues).

get_language_info(code) (and the template tags and filters in Marking strings in templates) returns a dictionary with the language’s code, its English name, its name in itself, its name in the currently active language, and a right-to-left flag:

Source: Django: Translation — Localized names of languages

The name_translated key is the one to use in a language menu shown in the visitor’s own language. The same shell session, run in the scratch project, returned exactly German Deutsch Allemand False.

{% translate %} translates a constant string (single or double quotes) or the value of a variable. Internally it is a gettext call. When you pass a variable, the tag first resolves it and then looks the resulting string up in the catalogue; it cannot mix variables inside a literal (use blocktranslate for that).

Source: Django: Translation — translate template tag

Rendered with the Dutch catalogue the three lines become Terug naar de plank (twice: link text and title), mei / mogen / mei and Zoeken. The comment block above the button is the template equivalent of a # Translators: comment: it is copied to the .po file as #. Translators: label of a button that triggers search. The one-line form {# Translators: … #} works too.

{% blocktranslate %} marks a whole sentence that contains variables. Variables appear as {{ name }} placeholders and become %(name)s in the msgid. To translate an expression (an attribute lookup, a filter) bind it to a local name with with; other block tags such as for or if are not allowed inside the block. A failed lookup of a block argument temporarily deactivates the language (deactivate_all()), so the message falls back to the source text.

Source: Django: Translation — blocktranslate template tag

The corresponding .po entries are the ones makemessages writes: trimmed keeps msgid on one line, the counter becomes %(counter)s, and the context becomes msgctxt.

The Dutch page printed by runserver (the curl output of /nl/):

Note the decimal comma: {{ price }} is a variable, and variables are formatted for the active language. That is localization, not translation, and it is why the same template prints 9.50 under en and 9,50 under nl. See Localization & Time Zones.

Rules specific to blocktranslate:

Source: Django: Translation — blocktranslate template tag

A string literal written as _("…") in an argument of a tag or filter is extracted and translated before the tag sees it:

Source: Django: Translation — String literals passed to tags and filters

The unit translated is the whole string "yes,no", not "yes" and "no" separately, so a German translator must keep the comma: ja,nein.

The language block activates a language for the enclosed section only. The home page uses it to show one sentence in English while the page is Dutch, and to build a link to the same view in every language:

Source: Django: Translation — Switching language in templates

Output of the page under /nl/ (note that the link for each language is built with that language’s own URL pattern, including the translated path segment):

The Polish link is /pl/about/ because no Polish translation of the URL segment exists, so the source text is used.

The base template of the scratch project uses get_current_language, get_current_language_bidi and get_language_info_list to set lang and dir on <html> and to build the switcher. Under /nl/ it produced <html lang="nl" dir="ltr"> and the line nl Nederlands Dutch Nederlands False from get_language_info. The filter test {{ "de"|language_name }}|{{ "de"|language_name_local }}|{{ "ar"|language_bidi }} returned German|Deutsch|True.

makemessages shells out to xgettext, msguniq and msgmerge, and compilemessages to msgfmt. The official minimum is gettext 0.19 (raised from 0.15 in Django 5.2). Install the package called gettext with your system’s package manager; on Windows download a precompiled gettext build and make sure xgettext --version works at a command prompt. JavaScript template strings additionally need gettext 0.21 or newer.

On the machine used to verify this page no gettext tools are installed. The official page still says that without gettext makemessages "will create empty files"; with Django 6.1.1 the commands instead stop with an explicit error:

Source: Django: Translation — Message files

Because of this, the .po files in the scratch project were written by hand following the format below, and compiled with a small Python stand-in so the tests could exercise real .mo files. In a real project you run the two commands.

Run it from the project root (the directory containing manage.py) or from an app’s root:

Source: Django: django-admin — makemessages

Where the strings land: run from the project root, a string from an app that has its own locale/ directory goes into that app’s message file; a string from an app without one goes into the first directory in LOCALE_PATHS, or the command fails if LOCALE_PATHS is empty. That is the reason the scratch project defines LOCALE_PATHS. Locale names are written with an underscore (pt_BR, de_AT, sr_Latn); since Django 4.2 locales with private sub-tags work, and since 3.2 a locale containing a hyphen is no longer silently processed.

The command does not need configured settings, but without settings it cannot skip MEDIA_ROOT and STATIC_ROOT or include LOCALE_PATHS. A practical command for a project with vendored front-end code is django-admin makemessages -l nl -i node_modules -i "static/vendor/*".

Two behavioural changes are worth knowing for version control: since Django 4.1 makemessages no longer rewrites a .po file that is already up to date (before, POT-Creation-Date changed on every run and produced noisy diffs), and msgmerge marks entries whose msgid changed slightly as fuzzy.

The scratch project’s Dutch file shows the whole format. After makemessages -l nl the entries have empty msgstr values and a #: location comment; the translator fills them in.

Source: Django: Translation — Message files

django-admin compilemessages turns every .po it finds into a .mo next to it. Run it from the same directory as makemessages, or point it at the settings file (--settings=path.to.settings) so it also processes every directory in LOCALE_PATHS.

Source: Django: django-admin — compilemessages

Treat .mo files as build artifacts: generate them in CI or in the image build (RUN python manage.py compilemessages, covered on the production deployment page of this section), keep the .po files in version control, and do not forget that a deployment without .mo files silently shows English.

To teach the extractor an extra keyword (for example a project helper called mytrans) subclass the command and extend xgettext_options. The file must live in an app’s management/commands/ directory under the same name, so it overrides the built-in one:

Source: Django: Translation — Customizing the makemessages command

Loaded through Django’s command machinery in the scratch project, the class reports ['--from-code=UTF-8', '--add-comments=Translators', '--keyword=mytrans'], while the built-in class lists only the first two. For per-run keywords, add an argument in add_arguments and extend xgettext_options inside handle, as the official page shows.

makemessages understands only the Django template language. A project that renders Jinja2 templates must extract their strings with Babel instead, using a babel.cfg that lists the Python and Jinja2 extractors; Babel produces the same .po files and does not depend on gettext at all, which also makes it a way to extract on a machine without gettext.

Django assumes English source strings. If you write the source strings in another language you can, but: gettext offers only two plural forms for the original messages, so you must also provide a translation for the base language when its plural rule differs from English; and a visitor using an English variant, when an English translation is missing, gets the original strings, not the project’s LANGUAGE_CODE. For example, an English user visiting a site whose LANGUAGE_CODE is Spanish and whose source strings are Russian sees Russian. Most teams keep English sources and add en only if they need to polish wording.

Middleware order matters, and the official guidance has three rules:

Source: Django: Translation — How Django discovers language preference

For each request the middleware tries these sources in order and stops at the first that yields a usable language:

Rules that apply at every step:

The scratch project’s tests walk through the order. The URL prefix beats the cookie and the header; the cookie beats the header (a cookie for a language outside LANGUAGES is ignored); an unprefixed URL with only a header is redirected:

Source: Django: Translation — How Django discovers language preference

In the second and third responses the explicit /nl/ or /en/ prefix won over the cookie. nl-BE from the header was reduced to nl because LANGUAGES lists only nl.

On the way out LocaleMiddleware does three things that matter for caches and clients:

Inside a view, the active language is request.LANGUAGE_CODE (dynamic translation) or settings.LANGUAGE_CODE (static). Prefer django.utils.translation.get_language(), which also works in code that does not receive the request.

Source: Django: django.utils.translation

Source: Django: Translation — Language prefix in URL patterns

i18n_patterns(*urls, prefix_default_language=True) returns a single resolver that prepends the current language code to its routes. Routes outside the call keep their plain paths: the language switcher endpoint, health checks, robots.txt, webhooks and API endpoints usually belong outside it.

A test that asserts the reverse results, in the active language:

Source: Django: Translation — Translating URL patterns

Source: Django: Translation — Translating URL patterns

With the Dutch catalogue, reverse("catalog:about") returns /nl/over/ and /nl/about/ is a 404, while the same name under English returns /en/about/. Remember that:

A test with override_settings(ROOT_URLCONF="config.urls_noprefix") shows prefix_default_language=False:

Source: Django: Translation — Language prefix in URL patterns

Source: Django: Translation — Language prefix in URL patterns

Note the third assertion: with prefix_default_language=False, an unprefixed URL always means the default language and the Accept-Language header is ignored for it, because the middleware sets the language to LANGUAGE_CODE when no prefix is present. Sites that want "redirect to my browser’s language on first visit" need the default prefix_default_language=True.

When the preference comes from elsewhere (a user profile, a single-sign-on claim), activate it for the request and persist it in the cookie so the next request finds it. activate affects only the current thread or task:

Source: Django: Translation — Explicitly setting the active language

The test posts language=nl and receives Welkom bij de Boekenplank. with django_language=nl in the cookies; a 600-character code returns 400 (check_for_language rejects codes longer than 500 characters), and a GET returns 405.

Do not store the language in the session. Older tutorials set request.session["_language"] or request.session[translation.LANGUAGE_SESSION_KEY]. Django 3.0 stopped reading the language from the session in LocaleMiddleware and stopped preserving it across logout(); Django 4.0 removed the code that set_language used to store it. The cookie is the only supported store.

Since Django 2.1 management commands run with the language that is active, no longer with translations deactivated. If a command must write untranslated text (for example into the database), decorate the work with @no_translations; otherwise pick a language with override. The same applies to anything that runs outside a request: a Celery or django.tasks worker, a cron-driven script, a signal receiver. Wrap the rendering of a user-facing message in override(<that user’s language>).

Source: Django: Custom management commands — Management commands and locales

[None] is the signature of deactivate_all(): get_language() returns None and every gettext returns its argument. The decorator cannot be used by commands that run without configured settings, because deactivation needs them.

The active translation is stored in an asgiref.local.Local (see trans_real.py in the Django source), which is thread-local under WSGI and task-local under ASGI. Consequences:

The async view and the test that proves it: fifteen requests in three languages run concurrently, each view sleeps 50 ms (so the requests interleave) and each still answers in its own language.

Source: Django: Asynchronous support

Source: Django: Testing tools — Testing asynchronous code

django.views.i18n.JavaScriptCatalog is a class-based view with two attributes:

Source: Django: Translation — The JavaScriptCatalog view

Create the strings with the djangojs domain, not with -e js, and compile as usual:

Source: Django: Translation — Creating message files from JavaScript source code

Load the script before the code that uses it. The template resolves its URL by name, so the language prefix is right:

Source: Django: Translation — Using the JavaScript translation catalog

The page /nl/over/ renders the <script src="/nl/jsi18n/"> tag (checked by a test). The catalogue is plain JavaScript, so it can be run outside a browser; this Node script loads the file served at /nl/jsi18n/ and calls the functions:

Source: Django: Translation — Using the JavaScript translation catalog

Notes on the output: an unknown string comes back unchanged; ngettext returns the format string and interpolate fills the placeholders (singular %s boek is returned uninterpolated because ngettext only chooses a form); and in 6.1.1 pluralidx returns the numbers 1 or 0 where the official page describes true and false, so treat the result as truthy.

For a client-side library that brings its own i18n machinery (i18next, FormatJS, a framework’s loader) use JSONCatalog. It takes the same domain and packages attributes and returns JSON with the catalogue, the locale formats and the plural expression. The scratch project’s endpoint returned:

Source: Django: Translation — The JSONCatalog view

(The real response lists every format name and the input-format arrays; they are elided with … here.) A plural entry is an array indexed by the plural form, and plural is the gettext expression to evaluate for a count.

Both views rebuild the catalogue from .mo files on every request. The output is constant between deployments, so cache it on the server, on the client, or build it at deploy time. Server-side with cache_page and a key prefix that changes when translations change; client-side with a conditional-GET decorator (or ConditionalGetMiddleware ETags):

Source: Django: Translation — Note on performance

With a local-memory cache and a trimmed middleware list, the test checks that the second request is served from the cache (the Cache-Control header carries max-age=86400) and that a request with If-Modified-Since set to the Last-Modified value of the conditional view gets 304. The most radical option is to pre-generate the catalogue during the build and serve it as a static file; the django-statici18n package does that.

For a handful of short labels, plain columns are enough. The Genre model above has name_en and name_nl, and one method that chooses the column for a language with an explicit fallback to English:

Source: Django: Translating text stored in models

This pattern stops being pleasant around three languages or ten fields. That is when a package earns its dependency.

The package keeps your model as it is and adds one column per language to the registered fields. You register the model in a translation.py that the package auto-discovers in each app:

Source: django-modeltranslation: Registering models and their fields

The documented setup is: add modeltranslation to INSTALLED_APPS (before django.contrib.admin if you use the admin integration), keep USE_I18N = True, list your languages in LANGUAGES (the first one is the default language), create translation.py, then makemigrations and migrate. Related settings include MODELTRANSLATION_DEFAULT_LANGUAGE and MODELTRANSLATION_FALLBACK_LANGUAGES. For the admin, derive your ModelAdmin from modeltranslation.admin.TranslationAdmin. The update_translation_fields command copies existing values into the default language’s new column.

Parler stores translations in a separate table. The model derives from TranslatableModel and declares its translatable fields in a TranslatedFields block:

Source: django-parler: Quick start guide

You add parler to INSTALLED_APPS, filter with MyModel.objects.translated(title=…) or active_translations(…), and set the language of an instance with set_current_language(…); PARLER_LANGUAGES and PARLER_DEFAULT_LANGUAGE_CODE configure fallbacks. The admin class is parler.admin.TranslatableAdmin.