In order to make a Django project translatable, you have to add a minimal\nnumber of hooks to your Python code and templates. These hooks are called\ntranslation strings. They tell Django: “This text\nshould be translated into the end user’s language, if a translation for this\ntext is available in that language.” It’s your responsibility to mark\ntranslatable strings; the system can only translate strings it knows about.
\nDjango then provides utilities to extract the translation strings into a\nmessage file. This file is a convenient way for translators to provide\nthe equivalent of the translation strings in the target language. Once the\ntranslators have filled in the message file, it must be compiled. This process\nrelies on the GNU gettext toolset.
\nOnce this is done, Django takes care of translating web apps on the fly in each\navailable language, according to users’ language preferences.
\nDjango’s internationalization hooks are on by default, and that means there’s a\nbit of i18n-related overhead in certain places of the framework. If you don’t\nuse internationalization, you should take the two seconds to set\nUSE_I18N = False in your settings file. Then Django will\nmake some optimizations so as not to load the internationalization machinery.
Specify a translation string by using the function\ngettext(). It’s convention to import this\nas a shorter alias, _, to save typing.
In this example, the text "Welcome to my site." is marked as a translation\nstring:
from django.http import HttpResponse\nfrom django.utils.translation import gettext as _\n\n\ndef my_view(request):\n output = _("Welcome to my site.")\n return HttpResponse(output)\nYou could code this without using the alias. This example is identical to the\nprevious one:
\nfrom django.http import HttpResponse\nfrom django.utils.translation import gettext\n\n\ndef my_view(request):\n output = gettext("Welcome to my site.")\n return HttpResponse(output)\nTranslation works on computed values. This example is identical to the previous\ntwo:
\ndef my_view(request):\n words = ["Welcome", "to", "my", "site."]\n output = _(" ".join(words))\n return HttpResponse(output)\nTranslation works on variables. Again, here’s an identical example:
\ndef my_view(request):\n sentence = "Welcome to my site."\n output = _(sentence)\n return HttpResponse(output)\n(The caveat with using variables or computed values, as in the previous two\nexamples, is that Django’s translation-string-detecting utility,\ndjango-admin makemessages, won’t be able to find\nthese strings. More on makemessages later.)
The strings you pass to _() or gettext() can take placeholders,\nspecified with Python’s standard named-string interpolation syntax. Example:
def my_view(request, m, d):\n output = _("Today is %(month)s %(day)s.") % {"month": m, "day": d}\n return HttpResponse(output)\nThis technique lets language-specific translations reorder the placeholder\ntext. For example, an English translation may be "Today is November 26.",\nwhile a Spanish translation may be "Hoy es 26 de noviembre." – with the\nmonth and the day placeholders swapped.
For this reason, you should use named-string interpolation (e.g., %(day)s)\ninstead of positional interpolation (e.g., %s or %d) whenever you\nhave more than a single parameter. If you used positional interpolation,\ntranslations wouldn’t be able to reorder placeholder text.
Since string extraction is done by the xgettext command, only syntaxes\nsupported by gettext are supported by Django. Python f-strings cannot be used directly with gettext functions because\nf-string expressions are evaluated before they reach gettext. This means\n_(f"Welcome {name}") will not work as expected, as the variable is\nsubstituted before translation occurs. Instead, use named-string\ninterpolation:
# Good\n_("Welcome %(name)s") % {"name": name}\n\n# Good\n_("Welcome {name}").format(name=name)\n\n# Bad\n_(f"Welcome {name}") # f-string evaluated before translation.\nJavaScript template strings need gettext 0.21+.
If you would like to give translators hints about a translatable string, you\ncan add a comment prefixed with the Translators keyword on the line\npreceding the string, e.g.:
def my_view(request):\n # Translators: This message appears on the home page only\n output = gettext("Welcome to my site.")\nThe comment will then appear in the resulting .po file associated with the\ntranslatable construct located below it and should also be displayed by most\ntranslation tools.
This also works in templates. See Comments for translators in templates for\nmore details.
\nUse the function django.utils.translation.gettext_noop() to mark a\nstring as a translation string without translating it. The string is later\ntranslated from a variable.
Use this if you have constant strings that should be stored in the source\nlanguage because they are exchanged over systems or users – such as strings\nin a database – but should be translated at the last possible point in time,\nsuch as when the string is presented to the user.
\nUse the function django.utils.translation.ngettext() to specify\npluralized messages.
ngettext() takes three arguments: the singular translation string, the\nplural translation string and the number of objects.
This function is useful when you need your Django application to be localizable\nto languages where the number and complexity of plural forms is\ngreater than the two forms used in English (‘object’ for the singular and\n‘objects’ for all the cases where count is different from one, irrespective\nof its value.)
For example:
\nfrom django.http import HttpResponse\nfrom django.utils.translation import ngettext\n\n\ndef hello_world(request, count):\n page = ngettext(\n "there is %(count)d object",\n "there are %(count)d objects",\n count,\n ) % {\n "count": count,\n }\n return HttpResponse(page)\nIn this example the number of objects is passed to the translation\nlanguages as the count variable.
Note that pluralization is complicated and works differently in each language.\nComparing count to 1 isn’t always the correct rule. This code looks\nsophisticated, but will produce incorrect results for some languages:
from django.utils.translation import ngettext\nfrom myapp.models import Report\n\ncount = Report.objects.count()\nif count == 1:\n name = Report._meta.verbose_name\nelse:\n name = Report._meta.verbose_name_plural\n\ntext = ngettext(\n "There is %(count)d %(name)s available.",\n "There are %(count)d %(name)s available.",\n count,\n) % {"count": count, "name": name}\nDon’t try to implement your own singular-or-plural logic; it won’t be correct.\nIn a case like this, consider something like the following:
\ntext = ngettext(\n "There is %(count)d %(name)s object available.",\n "There are %(count)d %(name)s objects available.",\n count,\n) % {\n "count": count,\n "name": Report._meta.verbose_name,\n}\nSometimes words have several meanings, such as "May" in English, which\nrefers to a month name and to a verb. To enable translators to translate\nthese words correctly in different contexts, you can use the\ndjango.utils.translation.pgettext() function, or the\ndjango.utils.translation.npgettext() function if the string needs\npluralization. Both take a context string as the first variable.
In the resulting .po file, the string will then appear as often as there\nare different contextual markers for the same string (the context will appear\non the msgctxt line), allowing the translator to give a different\ntranslation for each of them.
For example:
\nfrom django.utils.translation import pgettext\n\nmonth = pgettext("month name", "May")\nor:
\nfrom django.db import models\nfrom django.utils.translation import pgettext_lazy\n\n\nclass MyThing(models.Model):\n name = models.CharField(\n help_text=pgettext_lazy("help text for MyThing model", "This is the help text")\n )\nwill appear in the .po file as:
msgctxt "month name"\nmsgid "May"\nmsgstr ""\nContextual markers are also supported by the translate and\nblocktranslate template tags.
Use the lazy versions of translation functions in\ndjango.utils.translation (easily recognizable by the lazy suffix in\ntheir names) to translate strings lazily – when the value is accessed rather\nthan when they’re called.
These functions store a lazy reference to the string – not the actual\ntranslation. The translation itself will be done when the string is used in a\nstring context, such as in template rendering.
\nThis is essential when calls to these functions are located in code paths that\nare executed at module load time.
\nThis is something that can easily happen when defining models, forms and\nmodel forms, because Django implements these such that their fields are\nactually class-level attributes. For that reason, make sure to use lazy\ntranslations in the following cases:
\nverbose_name and help_text option valuesLink to this heading#For example, to translate the help text of the name field in the following\nmodel, do the following:
\nfrom django.db import models\nfrom django.utils.translation import gettext_lazy as _\n\n\nclass MyThing(models.Model):\n name = models.CharField(help_text=_("This is the help text"))\nYou can mark names of ForeignKey,\nManyToManyField or\nOneToOneField relationship as translatable by using\ntheir verbose_name options:
class MyThing(models.Model):\n kind = models.ForeignKey(\n ThingKind,\n on_delete=models.CASCADE,\n related_name="kinds",\n verbose_name=_("kind"),\n )\nJust like you would do in verbose_name you\nshould provide a lowercase verbose name text for the relation as Django will\nautomatically titlecase it when required.
It is recommended to always provide explicit\nverbose_name and\nverbose_name_plural options rather than\nrelying on the fallback English-centric and somewhat naïve determination of\nverbose names Django performs by looking at the model’s class name:
from django.db import models\nfrom django.utils.translation import gettext_lazy as _\n\n\nclass MyThing(models.Model):\n name = models.CharField(_("name"), help_text=_("This is the help text"))\n\n class Meta:\n verbose_name = _("my thing")\n verbose_name_plural = _("my things")\ndescription argument to the @display decoratorLink to this heading#For model methods, you can provide translations to Django and the admin site\nwith the description argument to the display()\ndecorator:
from django.contrib import admin\nfrom django.db import models\nfrom django.utils.translation import gettext_lazy as _\n\n\nclass MyThing(models.Model):\n kind = models.ForeignKey(\n ThingKind,\n on_delete=models.CASCADE,\n related_name="kinds",\n verbose_name=_("kind"),\n )\n\n @admin.display(description=_("Is it a mouse?"))\n def is_mouse(self):\n return self.kind.type == MOUSE_TYPE\nThe result of a gettext_lazy() call can be used wherever you would use a\nstring (a str object) in other Django code, but it may not work with\narbitrary Python code. For example, the following won’t work because the\nrequests library doesn’t handle gettext_lazy objects:
body = gettext_lazy("I \\u2764 Django") # (Unicode :heart:)\nrequests.post("https://example.com/send", data={"body": body})\nYou can avoid such problems by casting gettext_lazy() objects to text\nstrings before passing them to non-Django code:
requests.post("https://example.com/send", data={"body": str(body)})\nIf you don’t like the long gettext_lazy name, you can alias it as _\n(underscore), like so:
from django.db import models\nfrom django.utils.translation import gettext_lazy as _\n\n\nclass MyThing(models.Model):\n name = models.CharField(help_text=_("This is the help text"))\nUsing gettext_lazy() and ngettext_lazy() to mark strings in models\nand utility functions is a common operation. When you’re working with these\nobjects elsewhere in your code, you should ensure that you don’t accidentally\nconvert them to strings, because they should be converted as late as possible\n(so that the correct locale is in effect). This necessitates the use of the\nhelper function described next.
When using lazy translation for a plural string (n[p]gettext_lazy), you\ngenerally don’t know the number argument at the time of the string\ndefinition. Therefore, you are authorized to pass a key name instead of an\ninteger as the number argument. Then number will be looked up in the\ndictionary under that key during string interpolation. Here’s example:
from django import forms\nfrom django.core.exceptions import ValidationError\nfrom django.utils.translation import ngettext_lazy\n\n\nclass MyForm(forms.Form):\n error_message = ngettext_lazy(\n "You only provided %(num)d argument",\n "You only provided %(num)d arguments",\n "num",\n )\n\n def clean(self):\n # ...\n if error:\n raise ValidationError(self.error_message % {"num": number})\nIf the string contains exactly one unnamed placeholder, you can interpolate\ndirectly with the number argument:
class MyForm(forms.Form):\n error_message = ngettext_lazy(\n "You provided %d argument",\n "You provided %d arguments",\n )\n\n def clean(self):\n # ...\n if error:\n raise ValidationError(self.error_message % number)\nformat_lazy()Link to this heading#Python’s str.format() method will not work when either the\nformat_string or any of the arguments to str.format()\ncontains lazy translation objects. Instead, you can use\ndjango.utils.text.format_lazy(), which creates a lazy object\nthat runs the str.format() method only when the result is included\nin a string. For example:
from django.utils.text import format_lazy\nfrom django.utils.translation import gettext_lazy\n\n...\nname = gettext_lazy("John Lennon")\ninstrument = gettext_lazy("guitar")\nresult = format_lazy("{name}: {instrument}", name=name, instrument=instrument)\nIn this case, the lazy translations in result will only be converted to\nstrings when result itself is used in a string (usually at template\nrendering time).
For any other case where you would like to delay the translation, but have to\npass the translatable string as argument to another function, you can wrap\nthis function inside a lazy call yourself. For example:
\nfrom django.utils.functional import lazy\nfrom django.utils.translation import gettext_lazy as _\n\n\ndef to_lower(string):\n return string.lower()\n\n\nto_lower_lazy = lazy(to_lower, str)\nAnd then later:
\nlazy_string = to_lower_lazy(_("My STRING!"))\nThe get_language_info() function provides detailed information about\nlanguages:
>>> from django.utils.translation import activate, get_language_info\n>>> activate("fr")\n>>> li = get_language_info("de")\n>>> print(li["name"], li["name_local"], li["name_translated"], li["bidi"])\nGerman Deutsch Allemand False\nThe name, name_local, and name_translated attributes of the\ndictionary contain the name of the language in English, in the language\nitself, and in your current active language respectively. The bidi\nattribute is True only for bi-directional languages.
The source of the language information is the django.conf.locale module.\nSimilar access to this information is available for template code. See below.
Translations in Django templates uses two\ntemplate tags and a slightly different syntax than in Python code. To give your\ntemplate access to these tags, put {% load i18n %} toward the top of your\ntemplate. As with all template tags, this tag needs to be loaded in all\ntemplates which use translations, even those templates that extend from other\ntemplates which have already loaded the i18n tag.
translate template tagLink to this heading#The {% translate %} template tag translates either a constant string\n(enclosed in single or double quotes) or variable content:
<title>{% translate "This is the title." %}</title>\n<title>{% translate myvar %}</title>\nIf the noop option is present, variable lookup still takes place but the\ntranslation is skipped. This is useful when “stubbing out” content that will\nrequire translation in the future:
<title>{% translate "myvar" noop %}</title>\nInternally, inline translations use a\ngettext() call.
In case a template var (myvar above) is passed to the tag, the tag will\nfirst resolve such variable to a string at run-time and then look up that\nstring in the message catalogs.
It’s not possible to mix a template variable inside a string within\n{% translate %}. If your translations require strings with variables\n(placeholders), use {% blocktranslate %} instead.
If you’d like to retrieve a translated string without displaying it, you can\nuse the following syntax:
\n{% translate "This is the title" as the_title %}\n\n<title>{{ the_title }}</title>\n<meta name="description" content="{{ the_title }}">\nIn practice you’ll use this to get a string you can use in multiple places in a\ntemplate or so you can use the output as an argument for other template tags or\nfilters:
\n{% translate "starting point" as start %}\n{% translate "end point" as end %}\n{% translate "La Grande Boucle" as race %}\n\n<h1>\n <a href="/" title="{% blocktranslate %}Back to '{{ race }}' homepage{% endblocktranslate %}">{{ race }}</a>\n</h1>\n<p>\n{% for stage in tour_stages %}\n {% cycle start end %}: {{ stage }}{% if forloop.counter|divisibleby:2 %}<br>{% else %}, {% endif %}\n{% endfor %}\n</p>\n{% translate %} also supports contextual markers\nusing the context keyword:
{% translate "May" context "month name" %}\nblocktranslate template tagLink to this heading#Contrarily to the translate tag, the blocktranslate tag allows you\nto mark complex sentences consisting of literals and variable content for\ntranslation by making use of placeholders:
{% blocktranslate %}This string will have {{ value }} inside.{% endblocktranslate %}\nTo translate a template expression – say, accessing object attributes or\nusing template filters – you need to bind the expression to a local variable\nfor use within the translation block. Examples:
\n{% blocktranslate with amount=article.price %}\nThat will cost $ {{ amount }}.\n{% endblocktranslate %}\n\n{% blocktranslate with myvar=value|filter %}\nThis will have {{ myvar }} inside.\n{% endblocktranslate %}\nYou can use multiple expressions inside a single blocktranslate tag:
{% blocktranslate with book_t=book|title author_t=author|title %}\nThis is {{ book_t }} by {{ author_t }}\n{% endblocktranslate %}\nOther block tags (for example {% for %} or {% if %})\nare not allowed inside a blocktranslate tag.
If resolving one of the block arguments fails, blocktranslate will fall\nback to the default language by deactivating the currently active language\ntemporarily with the deactivate_all()\nfunction.
This tag also provides for pluralization. To use it:
\nDesignate and bind a counter value with the name count. This value will\nbe the one used to select the right plural form.
Specify both the singular and plural forms separating them with the\n{% plural %} tag within the {% blocktranslate %} and\n{% endblocktranslate %} tags.
An example:
\n{% blocktranslate count counter=list|length %}\nThere is {{ counter }} {{ name }} object.\n{% plural %}\nThere are {{ counter }} {{ name }} objects.\n{% endblocktranslate %}\nA more complex example:
\n{% blocktranslate with amount=article.price count years=i.length %}\nThat will cost $ {{ amount }} per year.\n{% plural %}\nThat will cost $ {{ amount }} per {{ years }} years.\n{% endblocktranslate %}\nWhen you use both the pluralization feature and bind values to local variables\nin addition to the counter value, keep in mind that the blocktranslate\nconstruct is internally converted to an ngettext call. This means the\nsame notes regarding ngettext variables\napply.
Reverse URL lookups cannot be carried out within the blocktranslate and\nshould be retrieved (and stored) beforehand:
{% url 'path.to.view' arg arg2 as the_url %}\n{% blocktranslate %}\nThis is a URL: {{ the_url }}\n{% endblocktranslate %}\nIf you’d like to retrieve a translated string without displaying it, you can\nuse the following syntax:
\n{% blocktranslate asvar the_title %}The title is {{ title }}.{% endblocktranslate %}\n<title>{{ the_title }}</title>\n<meta name="description" content="{{ the_title }}">\nIn practice you’ll use this to get a string you can use in multiple places in a\ntemplate or so you can use the output as an argument for other template tags or\nfilters.
\n{% blocktranslate %} also supports contextual\nmarkers using the context keyword:
{% blocktranslate with name=user.username context "greeting" %}Hi {{ name }}{% endblocktranslate %}\nAnother feature {% blocktranslate %} supports is the trimmed option.\nThis option will remove newline characters from the beginning and the end of\nthe content of the {% blocktranslate %} tag, replace any whitespace at the\nbeginning and end of a line and merge all lines into one using a space\ncharacter to separate them. This is quite useful for indenting the content of a\n{% blocktranslate %} tag without having the indentation characters end up\nin the corresponding entry in the .po file, which makes the translation\nprocess easier.
For instance, the following {% blocktranslate %} tag:
{% blocktranslate trimmed %}\n First sentence.\n Second paragraph.\n{% endblocktranslate %}\nwill result in the entry "First sentence. Second paragraph." in the .po\nfile, compared to "\\n First sentence.\\n Second paragraph.\\n", if the\ntrimmed option had not been specified.
Just like with Python code, these notes for\ntranslators can be specified using comments, either with the comment\ntag:
{% comment %}Translators: View verb{% endcomment %}\n{% translate "View" %}\n\n{% comment %}Translators: Short intro blurb{% endcomment %}\n<p>{% blocktranslate %}A multiline translatable\nliteral.{% endblocktranslate %}</p>\nor with the {# … #}\none-line comment constructs:
{# Translators: Label of a button that triggers search #}\n<button type="submit">{% translate "Go" %}</button>\n\n{# Translators: This is a text of the base template #}\n{% blocktranslate %}Ambiguous translatable block of text{% endblocktranslate %}\nIf you want to select a language within a template, you can use the\nlanguage template tag:
{% load i18n %}\n\n{% get_current_language as LANGUAGE_CODE %}\n<!-- Current language: {{ LANGUAGE_CODE }} -->\n<p>{% translate "Welcome to our page" %}</p>\n\n{% language 'en' %}\n {% get_current_language as LANGUAGE_CODE %}\n <!-- Current language: {{ LANGUAGE_CODE }} -->\n <p>{% translate "Welcome to our page" %}</p>\n{% endlanguage %}\nWhile the first occurrence of “Welcome to our page” uses the current language,\nthe second will always be in English.
\nAdding translations to JavaScript poses some problems:
\nJavaScript code doesn’t have access to a gettext implementation.
JavaScript code doesn’t have access to .po or .mo files; they need to\nbe delivered by the server.
The translation catalogs for JavaScript should be kept as small as\npossible.
Django provides an integrated solution for these problems: It passes the\ntranslations into JavaScript, so you can call gettext, etc., from within\nJavaScript.
The main solution to these problems is the following JavaScriptCatalog\nview, which generates a JavaScript code library with functions that mimic the\ngettext interface, plus an array of translation strings.
JavaScriptCatalog viewLink to this heading#A view that produces a JavaScript code library with functions that mimic\nthe gettext interface, plus an array of translation strings.
Attributes
\nTranslation domain containing strings to add in the view output.\nDefaults to 'djangojs'.
A list of application names among\ninstalled applications. Those apps should contain a locale\ndirectory. All those catalogs plus all catalogs found in\nLOCALE_PATHS (which are always included) are merged into one\ncatalog. Defaults to None, which means that all available\ntranslations from all INSTALLED_APPS are provided in the\nJavaScript output.
Example with default values:
\nfrom django.views.i18n import JavaScriptCatalog\n\nurlpatterns = [\n path("jsi18n/", JavaScriptCatalog.as_view(), name="javascript-catalog"),\n]\nExample with custom packages:
\nurlpatterns = [\n path(\n "jsi18n/myapp/",\n JavaScriptCatalog.as_view(packages=["your.app.label"]),\n name="javascript-catalog",\n ),\n]\nIf your root URLconf uses i18n_patterns(),\nJavaScriptCatalog must also be wrapped by i18n_patterns() for the\ncatalog to be correctly generated.
Example with i18n_patterns():
from django.conf.urls.i18n import i18n_patterns\n\nurlpatterns = i18n_patterns(\n path("jsi18n/", JavaScriptCatalog.as_view(), name="javascript-catalog"),\n)\nThe precedence of translations is such that the packages appearing later in the\npackages argument have higher precedence than the ones appearing at the\nbeginning. This is important in the case of clashing translations for the same\nliteral.
If you use more than one JavaScriptCatalog view on a site and some of them\ndefine the same strings, the strings in the catalog that was loaded last take\nprecedence.
To use the catalog, pull in the dynamically generated script like this:
\n<script src="{% url 'javascript-catalog' %}"></script>\nThis uses reverse URL lookup to find the URL of the JavaScript catalog view.\nWhen the catalog is loaded, your JavaScript code can use the following methods:
\ngettext
ngettext
interpolate
get_format
gettext_noop
pgettext
npgettext
pluralidx
gettextLink to this heading#The gettext function behaves similarly to the standard gettext\ninterface within your Python code:
document.write(gettext("this is to be translated"))\nngettextLink to this heading#The ngettext function provides an interface to pluralize words and\nphrases:
const objectCount = 1 // or 0, or 2, or 3, ...\nconst string = ngettext(\n 'literal for the singular case',\n 'literal for the plural case',\n objectCount\n);\ninterpolateLink to this heading#The interpolate function supports dynamically populating a format string.\nThe interpolation syntax is borrowed from Python, so the interpolate\nfunction supports both positional and named interpolation:
Positional interpolation: obj contains a JavaScript Array object\nwhose elements values are then sequentially interpolated in their\ncorresponding fmt placeholders in the same order they appear.\nFor example:
const formats = ngettext(\n 'There is %s object. Remaining: %s',\n 'There are %s objects. Remaining: %s',\n 11\n);\nconst string = interpolate(formats, [11, 20]);\n// string is 'There are 11 objects. Remaining: 20'\nNamed interpolation: This mode is selected by passing the optional\nboolean named parameter as true. obj contains a JavaScript\nobject or associative array. For example:
const data = {\n count: 10,\n total: 50\n};\n\nconst formats = ngettext(\n 'Total: %(total)s, there is %(count)s object',\n 'there are %(count)s of a total of %(total)s objects',\n data.count\n);\nconst string = interpolate(formats, data, true);\nYou shouldn’t go over the top with string interpolation, though: this is still\nJavaScript, so the code has to make repeated regular-expression substitutions.\nThis isn’t as fast as string interpolation in Python, so keep it to those\ncases where you really need it (for example, in conjunction with ngettext\nto produce proper pluralizations).
get_formatLink to this heading#The get_format function has access to the configured i18n formatting\nsettings and can retrieve the format string for a given setting name:
document.write(get_format('DATE_FORMAT'));\n// 'N j, Y'\nIt has access to the following settings:
\nThis is useful for maintaining formatting consistency with the Python-rendered\nvalues.
\ngettext_noopLink to this heading#This emulates the gettext function but does nothing, returning whatever\nis passed to it:
document.write(gettext_noop("this will not be translated"))\nThis is useful for stubbing out portions of the code that will need translation\nin the future.
\npgettextLink to this heading#The pgettext function behaves like the Python variant\n(pgettext()), providing a contextually\ntranslated word:
document.write(pgettext("month name", "May"))\nnpgettextLink to this heading#The npgettext function also behaves like the Python variant\n(npgettext()), providing a pluralized\ncontextually translated word:
document.write(npgettext('group', 'party', 1));\n// party\ndocument.write(npgettext('group', 'party', 2));\n// parties\npluralidxLink to this heading#The pluralidx function works in a similar way to the pluralize\ntemplate filter, determining if a given count should use a plural form of\na word or not:
document.write(pluralidx(0));\n// true\ndocument.write(pluralidx(1));\n// false\ndocument.write(pluralidx(2));\n// true\nIn the simplest case, if no custom pluralization is needed, this returns\nfalse for the integer 1 and true for all other numbers.
However, pluralization is not this simple in all languages. If the language\ndoes not support pluralization, an empty value is provided.
\nAdditionally, if there are complex rules around pluralization, the catalog view\nwill render a conditional expression. This will evaluate to either a true\n(should pluralize) or false (should not pluralize) value.
JSONCatalog viewLink to this heading#In order to use another client-side library to handle translations, you may\nwant to take advantage of the JSONCatalog view. It’s similar to\nJavaScriptCatalog but returns a JSON response.
See the documentation for JavaScriptCatalog\nto learn about possible values and use of the domain and packages\nattributes.
The response format is as follows:
\n{\n "catalog": {\n # Translations catalog\n },\n "formats": {\n # Language formats for date, time, etc.\n },\n "plural": "..." # Expression for plural forms, or null.\n}\nThe various JavaScript/JSON i18n views generate the catalog from .mo files\non every request. Since its output is constant, at least for a given version\nof a site, it’s a good candidate for caching.
Server-side caching will reduce CPU load. It’s easily implemented with the\ncache_page() decorator. To trigger cache\ninvalidation when your translations change, provide a version-dependent key\nprefix, as shown in the example below, or map the view at a version-dependent\nURL:
from django.views.decorators.cache import cache_page\nfrom django.views.i18n import JavaScriptCatalog\n\n# The value returned by get_version() must change when translations change.\nurlpatterns = [\n path(\n "jsi18n/",\n cache_page(86400, key_prefix="jsi18n-%s" % get_version())(\n JavaScriptCatalog.as_view()\n ),\n name="javascript-catalog",\n ),\n]\nClient-side caching will save bandwidth and make your site load faster. If\nyou’re using ETags (ConditionalGetMiddleware),\nyou’re already covered. Otherwise, you can apply conditional decorators. In the following example, the cache is invalidated\nwhenever you restart your application server:
from django.utils import timezone\nfrom django.views.decorators.http import last_modified\nfrom django.views.i18n import JavaScriptCatalog\n\nlast_modified_date = timezone.now()\n\nurlpatterns = [\n path(\n "jsi18n/",\n last_modified(lambda req, **kw: last_modified_date)(\n JavaScriptCatalog.as_view()\n ),\n name="javascript-catalog",\n ),\n]\nYou can even pre-generate the JavaScript catalog as part of your deployment\nprocedure and serve it as a static file. This radical technique is implemented\nin django-statici18n.
\nDjango provides two mechanisms to internationalize URL patterns:
\nAdding the language prefix to the root of the URL patterns to make it\npossible for LocaleMiddleware to detect\nthe language to activate from the requested URL.
Making URL patterns themselves translatable via the\ndjango.utils.translation.gettext_lazy() function.
This function can be used in a root URLconf and Django will automatically\nprepend the current active language code to all URL patterns defined within\ni18n_patterns().
Setting prefix_default_language to False removes the prefix from the\ndefault language (LANGUAGE_CODE). This can be useful when adding\ntranslations to existing site so that the current URLs won’t change.
Example URL patterns:
\nfrom django.conf.urls.i18n import i18n_patterns\nfrom django.urls import include, path\n\nfrom about import views as about_views\nfrom news import views as news_views\nfrom sitemap.views import sitemap\n\nurlpatterns = [\n path("sitemap.xml", sitemap, name="sitemap-xml"),\n]\n\nnews_patterns = (\n [\n path("", news_views.index, name="index"),\n path("category/<slug:slug>/", news_views.category, name="category"),\n path("<slug:slug>/", news_views.details, name="detail"),\n ],\n "news",\n)\n\nurlpatterns += i18n_patterns(\n path("about/", about_views.main, name="about"),\n path("news/", include(news_patterns, namespace="news")),\n)\nAfter defining these URL patterns, Django will automatically add the\nlanguage prefix to the URL patterns that were added by the i18n_patterns\nfunction. Example:
>>> from django.urls import reverse\n>>> from django.utils.translation import activate\n\n>>> activate("en")\n>>> reverse("sitemap-xml")\n'/sitemap.xml'\n>>> reverse("news:index")\n'/en/news/'\n\n>>> activate("nl")\n>>> reverse("news:detail", kwargs={"slug": "news-slug"})\n'/nl/news/news-slug/'\nWith prefix_default_language=False and LANGUAGE_CODE='en', the URLs\nwill be:
>>> activate("en")\n>>> reverse("news:index")\n'/news/'\n\n>>> activate("nl")\n>>> reverse("news:index")\n'/nl/news/'\nURL patterns can also be marked translatable using the\ngettext_lazy() function. Example:
from django.conf.urls.i18n import i18n_patterns\nfrom django.urls import include, path\nfrom django.utils.translation import gettext_lazy as _\n\nfrom about import views as about_views\nfrom news import views as news_views\nfrom sitemaps.views import sitemap\n\nurlpatterns = [\n path("sitemap.xml", sitemap, name="sitemap-xml"),\n]\n\nnews_patterns = (\n [\n path("", news_views.index, name="index"),\n path(_("category/<slug:slug>/"), news_views.category, name="category"),\n path("<slug:slug>/", news_views.details, name="detail"),\n ],\n "news",\n)\n\nurlpatterns += i18n_patterns(\n path(_("about/"), about_views.main, name="about"),\n path(_("news/"), include(news_patterns, namespace="news")),\n)\nAfter you’ve created the translations, the reverse()\nfunction will return the URL in the active language. Example:
>>> from django.urls import reverse\n>>> from django.utils.translation import activate\n\n>>> activate("en")\n>>> reverse("news:category", kwargs={"slug": "recent"})\n'/en/news/category/recent/'\n\n>>> activate("nl")\n>>> reverse("news:category", kwargs={"slug": "recent"})\n'/nl/nieuws/categorie/recent/'\nIf localized URLs get reversed in templates they always use the current\nlanguage. To link to a URL in another language use the language\ntemplate tag. It enables the given language in the enclosed template section:
{% load i18n %}\n\n{% get_available_languages as languages %}\n\n{% translate "View this category in:" %}\n{% for lang_code, lang_name in languages %}\n {% language lang_code %}\n <a href="{% url 'category' slug=category.slug %}">{{ lang_name }}</a>\n {% endlanguage %}\n{% endfor %}\nThe language tag expects the language code as the only argument.
Once the string literals of an application have been tagged for later\ntranslation, the translation themselves need to be written (or obtained).\nHere’s how that works.
\nThe first step is to create a message file for a new language. A\nmessage file is a plain-text file, representing a single language, that\ncontains all available translation strings and how they should be represented\nin the given language. Message files have a .po file extension.
Django comes with a tool, django-admin makemessages, that automates the creation and upkeep of these files.
To create or update a message file, run this command:
\ndjango-admin makemessages -l de\n…where de is the locale name for the message file you want to\ncreate. For example, pt_BR for Brazilian Portuguese, de_AT for Austrian\nGerman or id for Indonesian.
The script should be run from one of two places:
\nThe root directory of your Django project (the one that contains\nmanage.py).
The root directory of one of your Django apps.
The script runs over your project source tree or your application source tree\nand pulls out all strings marked for translation (see\nHow Django discovers translations and be sure LOCALE_PATHS\nis configured correctly). It creates (or updates) a message file in the\ndirectory locale/LANG/LC_MESSAGES. In the de example, the file will be\nlocale/de/LC_MESSAGES/django.po.
When you run makemessages from the root directory of your project, the\nextracted strings will be automatically distributed to the proper message\nfiles. That is, a string extracted from a file of an app containing a\nlocale directory will go in a message file under that directory. A string\nextracted from a file of an app without any locale directory will either go\nin a message file under the directory listed first in LOCALE_PATHS\nor will generate an error if LOCALE_PATHS is empty.
By default django-admin makemessages examines every\nfile that has the .html, .txt or .py file extension. If you want to\noverride that default, use the --extension\nor -e option to specify the file extensions to examine:
django-admin makemessages -l de -e txt\nSeparate multiple extensions with commas and/or use -e or --extension\nmultiple times:
django-admin makemessages -l de -e html,txt -e xml\nEach .po file contains a small bit of metadata, such as the translation\nmaintainer’s contact information, but the bulk of the file is a list of\nmessages – mappings between translation strings and the actual translated\ntext for the particular language.
For example, if your Django app contained a translation string for the text\n"Welcome to my site.", like so:
_("Welcome to my site.")\n…then django-admin makemessages will have created\na .po file containing the following snippet – a message:
#: path/to/python/module.py:23\nmsgid "Welcome to my site."\nmsgstr ""\nA quick explanation:
\nmsgid is the translation string, which appears in the source. Don’t\nchange it.
msgstr is where you put the language-specific translation. It starts\nout empty, so it’s your responsibility to change it. Make sure you keep\nthe quotes around your translation.
As a convenience, each message includes, in the form of a comment line\nprefixed with # and located above the msgid line, the filename and\nline number from which the translation string was gleaned.
Long messages are a special case. There, the first string directly after the\nmsgstr (or msgid) is an empty string. Then the content itself will be\nwritten over the next few lines as one string per line. Those strings are\ndirectly concatenated. Don’t forget trailing spaces within the strings;\notherwise, they’ll be tacked together without whitespace!
To reexamine all source code and templates for new translation strings and\nupdate all message files for all languages, run this:
\ndjango-admin makemessages -a\nAfter you create your message file – and each time you make changes to it –\nyou’ll need to compile it into a more efficient form, for use by gettext.\nDo this with the django-admin compilemessages\nutility.
This tool runs over all available .po files and creates .mo files,\nwhich are binary files optimized for use by gettext. In the same directory\nfrom which you ran django-admin makemessages, run\ndjango-admin compilemessages like this:
django-admin compilemessages\nThat’s it. Your translations are ready for use.
\n\n\ngettext() incorrectly detects python-format in strings with percent signsLink to this heading#In some cases, such as strings with a percent sign followed by a space and a\nstring conversion type (e.g.\n_("10% interest")), gettext() incorrectly\nflags strings with python-format.
If you try to compile message files with incorrectly flagged strings, you’ll\nget an error message like number of format specifications in 'msgid' and\n'msgstr' does not match or 'msgstr' is not a valid Python format string,\nunlike 'msgid'.
To workaround this, you can escape percent signs by adding a second percent\nsign:
\nfrom django.utils.translation import gettext as _\n\noutput = _("10%% interest")\nOr you can use no-python-format so that all percent signs are treated as\nliterals:
# xgettext:no-python-format\noutput = _("10% interest")\nYou create and update the message files the same way as the other Django\nmessage files – with the django-admin makemessages\ntool. The only difference is you need to explicitly specify what in gettext\nparlance is known as a domain in this case the djangojs domain, by\nproviding a -d djangojs parameter, like this:
django-admin makemessages -d djangojs -l de\nThis would create or update the message file for JavaScript for German. After\nupdating message files, run django-admin compilemessages the same way as you do with normal Django message files.
gettext on WindowsLink to this heading#This is only needed for people who either want to extract message IDs or\ncompile message files (.po). Translation work itself involves editing\nexisting files of this type, but if you want to create your own message files,\nor want to test or compile a changed message file, download a precompiled\nbinary installer.
You may also use gettext binaries you have obtained elsewhere, so long as\nthe xgettext --version command works properly. Do not attempt to use Django\ntranslation utilities with a gettext package if the command xgettext\n--version entered at a Windows command prompt causes a popup window saying\n“xgettext.exe has generated errors and will be closed by Windows”.
makemessages commandLink to this heading#If you want to pass additional parameters to xgettext, you need to create a\ncustom makemessages command and override its xgettext_options\nattribute:
from django.core.management.commands import makemessages\n\n\nclass Command(makemessages.Command):\n xgettext_options = makemessages.Command.xgettext_options + ["--keyword=mytrans"]\nIf you need more flexibility, you could also add a new argument to your custom\nmakemessages command:
from django.core.management.commands import makemessages\n\n\nclass Command(makemessages.Command):\n def add_arguments(self, parser):\n super().add_arguments(parser)\n parser.add_argument(\n "--extra-keyword",\n dest="xgettext_keywords",\n action="append",\n )\n\n def handle(self, *args, **options):\n xgettext_keywords = options.pop("xgettext_keywords")\n if xgettext_keywords:\n self.xgettext_options = makemessages.Command.xgettext_options[:] + [\n "--keyword=%s" % kwd for kwd in xgettext_keywords\n ]\n super().handle(*args, **options)\nset_language redirect viewLink to this heading#As a convenience, Django comes with a view,\ndjango.views.i18n.set_language(), that sets a user’s language preference\nand redirects to a given URL or, by default, back to the previous page.
Activate this view by adding the following line to your URLconf:
\npath("i18n/", include("django.conf.urls.i18n")),\n(Note that this example makes the view available at /i18n/setlang/.)
The view expects to be called via the POST method, with a language\nparameter set in request. The view saves the language choice in a cookie that\nis named django_language by default. (The name can be changed through the\nLANGUAGE_COOKIE_NAME setting.)
After setting the language choice, Django looks for a next parameter in the\nPOST or GET data. If that is found and Django considers it to be a safe\nURL (i.e. it doesn’t point to a different host and uses a safe scheme), a\nredirect to that URL will be performed. Otherwise, Django may fall back to\nredirecting the user to the URL from the Referer header or, if it is not\nset, to /, depending on the nature of the request:
If the request accepts HTML content (based on its Accept HTTP header),\nthe fallback will always be performed.
If the request doesn’t accept HTML, the fallback will be performed only if\nthe next parameter was set. Otherwise a 204 status code (No Content) will\nbe returned.
Here’s example HTML template code:
\n{% load i18n %}\n\n<form action="{% url 'set_language' %}" method="post">{% csrf_token %}\n <input name="next" type="hidden" value="{{ redirect_to }}">\n <select name="language">\n {% get_current_language as LANGUAGE_CODE %}\n {% get_available_languages as LANGUAGES %}\n {% get_language_info_list for LANGUAGES as languages %}\n {% for language in languages %}\n <option value="{{ language.code }}"{% if language.code == LANGUAGE_CODE %} selected{% endif %}>\n {{ language.name_local }} ({{ language.code }})\n </option>\n {% endfor %}\n </select>\n <input type="submit" value="Go">\n</form>\nIn this example, Django looks up the URL of the page to which the user will be\nredirected in the redirect_to context variable.
You may want to set the active language for the current session explicitly.\nPerhaps a user’s language preference is retrieved from another system, for\nexample. You’ve already been introduced to\ndjango.utils.translation.activate(). That applies to the current thread\nonly. To persist the language for the entire session in a cookie, set the\nLANGUAGE_COOKIE_NAME cookie on the response:
from django.conf import settings\nfrom django.http import HttpResponse\nfrom django.utils import translation\n\nuser_language = "fr"\ntranslation.activate(user_language)\nresponse = HttpResponse(...)\nresponse.set_cookie(settings.LANGUAGE_COOKIE_NAME, user_language)\nYou would typically want to use both: django.utils.translation.activate()\nchanges the language for this thread, and setting the cookie makes this\npreference persist in future requests.
While Django provides a rich set of i18n tools for use in views and templates,\nit does not restrict the usage to Django-specific code. The Django translation\nmechanisms can be used to translate arbitrary texts to any language that is\nsupported by Django (as long as an appropriate translation catalog exists, of\ncourse). You can load a translation catalog, activate it and translate text to\nlanguage of your choice, but remember to switch back to original language, as\nactivating a translation catalog is done on per-thread basis and such change\nwill affect code running in the same thread.
\nFor example:
\nfrom django.utils import translation\n\n\ndef welcome_translated(language):\n cur_language = translation.get_language()\n try:\n translation.activate(language)\n text = translation.gettext("welcome")\n finally:\n translation.activate(cur_language)\n return text\nCalling this function with the value 'de' will give you "Willkommen",\nregardless of LANGUAGE_CODE and language set by middleware.
Functions of particular interest are\ndjango.utils.translation.get_language() which returns the language used\nin the current thread, django.utils.translation.activate() which\nactivates a translation catalog for the current thread, and\ndjango.utils.translation.check_for_language()\nwhich checks if the given language is supported by Django.
To help write more concise code, there is also a context manager\ndjango.utils.translation.override() that stores the current language on\nenter and restores it on exit. With it, the above example becomes:
from django.utils import translation\n\n\ndef welcome_translated(language):\n with translation.override(language):\n return translation.gettext("welcome")\nDjango’s translation machinery uses the standard gettext module that comes\nwith Python. If you know gettext, you might note these specialties in the\nway Django does translation:
The string domain is django or djangojs. This string domain is\nused to differentiate between different programs that store their data\nin a common message-file library (usually /usr/share/locale/). The\ndjango domain is used for Python and template translation strings\nand is loaded into the global translation catalogs. The djangojs\ndomain is only used for JavaScript translation catalogs to make sure\nthat those are as small as possible.
Django doesn’t use xgettext alone. It uses Python wrappers around\nxgettext and msgfmt. This is mostly for convenience.
Once you’ve prepared your translations – or, if you want to use the\ntranslations that come with Django – you’ll need to activate translation for\nyour app.
\nBehind the scenes, Django has a very flexible model of deciding which language\nshould be used – installation-wide, for a particular user, or both.
\nTo set an installation-wide language preference, set LANGUAGE_CODE.\nDjango uses this language as the default translation – the final attempt if no\nbetter matching translation is found through one of the methods employed by the\nlocale middleware (see below).
If all you want is to run Django with your native language all you need to do\nis set LANGUAGE_CODE and make sure the corresponding message\nfiles and their compiled versions (.mo) exist.
If you want to let each individual user specify which language they\nprefer, then you also need to use the LocaleMiddleware.\nLocaleMiddleware enables language selection based on data from the request.\nIt customizes content for each user.
To use LocaleMiddleware, add\n'django.middleware.locale.LocaleMiddleware' to your MIDDLEWARE\nsetting. Because middleware order matters, follow these guidelines:
Make sure it’s one of the first middleware installed.
It should come after SessionMiddleware, because LocaleMiddleware\nmakes use of session data. And it should come before CommonMiddleware\nbecause CommonMiddleware needs an activated language in order\nto resolve the requested URL.
If you use CacheMiddleware, put LocaleMiddleware after it.
For example, your MIDDLEWARE might look like this:
MIDDLEWARE = [\n "django.contrib.sessions.middleware.SessionMiddleware",\n "django.middleware.locale.LocaleMiddleware",\n "django.middleware.common.CommonMiddleware",\n]\n(For more on middleware, see the middleware documentation.)
\nLocaleMiddleware tries to determine the user’s language preference by\nfollowing this algorithm:
First, it looks for the language prefix in the requested URL. This is\nonly performed when you are using the i18n_patterns function in your\nroot URLconf. See Internationalization: in URL patterns for more information\nabout the language prefix and how to internationalize URL patterns.
Failing that, it looks for a cookie.
\nThe name of the cookie used is set by the LANGUAGE_COOKIE_NAME\nsetting. (The default name is django_language.)
Failing that, it looks at the Accept-Language HTTP header. This\nheader is sent by your browser and tells the server which language(s) you\nprefer, in order by priority. Django tries each language in the header\nuntil it finds one with available translations.
Failing that, it uses the global LANGUAGE_CODE setting.
Notes:
\nIn each of these places, the language preference is expected to be in the\nstandard language format, as a string. For example,\nBrazilian Portuguese is pt-br.
If a base language is available but the sublanguage specified is not,\nDjango uses the base language. For example, if a user specifies de-at\n(Austrian German) but Django only has de available, Django uses\nde.
Only languages listed in the LANGUAGES setting can be selected.\nIf you want to restrict the language selection to a subset of provided\nlanguages (because your application doesn’t provide all those languages),\nset LANGUAGES to a list of languages. For example:
LANGUAGES = [\n ("de", _("German")),\n ("en", _("English")),\n]\nThis example restricts languages that are available for automatic\nselection to German and English (and any sublanguage, like de-ch or\nen-us).
If you define a custom LANGUAGES setting, as explained in the\nprevious bullet, you can mark the language names as translation strings\n– but use gettext_lazy() instead of\ngettext() to avoid a circular import.
Here’s a sample settings file:
\nfrom django.utils.translation import gettext_lazy as _\n\nLANGUAGES = [\n ("de", _("German")),\n ("en", _("English")),\n]\nOnce LocaleMiddleware determines the user’s preference, it makes this\npreference available as request.LANGUAGE_CODE for each\nHttpRequest. Feel free to read this value in your view\ncode. Here’s an example:
from django.http import HttpResponse\n\n\ndef hello_world(request, count):\n if request.LANGUAGE_CODE == "de-at":\n return HttpResponse("You prefer to read Austrian German.")\n else:\n return HttpResponse("You prefer to read another language.")\nNote that, with static (middleware-less) translation, the language is in\nsettings.LANGUAGE_CODE, while with dynamic (middleware) translation, it’s\nin request.LANGUAGE_CODE.
At runtime, Django builds an in-memory unified catalog of\nliterals-translations. To achieve this it looks for translations by following\nthis algorithm regarding the order in which it examines the different file\npaths to load the compiled message files (.mo) and\nthe precedence of multiple translations for the same literal:
The directories listed in LOCALE_PATHS have the highest\nprecedence, with the ones appearing first having higher precedence than\nthe ones appearing later.
Then, it looks for and uses if it exists a locale directory in each\nof the installed apps listed in INSTALLED_APPS. The ones\nappearing first have higher precedence than the ones appearing later.
Finally, the Django-provided base translation in\ndjango/conf/locale is used as a fallback.
In all cases the name of the directory containing the translation is expected\nto be named using locale name notation. E.g. de, pt_BR,\nes_AR, etc. Untranslated strings for territorial language variants use the\ntranslations of the generic language. For example, untranslated pt_BR\nstrings use pt translations.
This way, you can write applications that include their own translations, and\nyou can override base translations in your project. Or, you can build a big\nproject out of several apps and put all translations into one big common\nmessage file specific to the project you are composing. The choice is yours.
\nAll message file repositories are structured the same way. They are:
\nAll paths listed in LOCALE_PATHS in your settings file are\nsearched for <language>/LC_MESSAGES/django.(po|mo)
$APPPATH/locale/<language>/LC_MESSAGES/django.(po|mo)
$PYTHONPATH/django/conf/locale/<language>/LC_MESSAGES/django.(po|mo)
To create message files, you use the\ndjango-admin makemessages tool. And you use\ndjango-admin compilemessages to produce the binary\n.mo files that are used by gettext.
You can also run django-admin compilemessages\n--settings=path.to.settings to make the compiler process all\nthe directories in your LOCALE_PATHS setting.
Django makes the general assumption that the original strings in a translatable\nproject are written in English. You can choose another language, but you must\nbe aware of certain limitations:
\ngettext only provides two plural forms for the original messages, so you\nwill also need to provide a translation for the base language to include all\nplural forms if the plural rules for the base language are different from\nEnglish.
When an English variant is activated and English strings are missing, the\nfallback language will not be the LANGUAGE_CODE of the project,\nbut the original strings. For example, an English user visiting a site with\nLANGUAGE_CODE set to Spanish and original strings written in\nRussian will see Russian text rather than Spanish.