{"title":"번역","version":"6.0","locale":"ko","docname":"topics/i18n/translation","url":"/ko/6.0/topics/i18n/translation/","canonical":"https://djangodocs.dev/ko/6.0/topics/i18n/translation/","summary":"개요 Link to this heading # Django 프로젝트를 번역가능하게 하기 위해, 사용자는 파이선 코드와 템플릿에 최소한의 훅(hook)을 추가해야 한다. 이 훅은 :term: ` 번역 문자열 `이라고 한다. 이 문자열은 Django에 다음과…","html":"

번역Link to this heading#

\n
\n

개요Link to this heading#

\n

Django 프로젝트를 번역가능하게 하기 위해, 사용자는 파이선 코드와 템플릿에 최소한의 훅(hook)을 추가해야 한다. 이 훅은 :term:`번역 문자열 <translation string>`이라고 한다. 이 문자열은 Django에 다음과 같은 메시지를 전달한다: “이 텍스트는 가능하다면 최종 사용자의 언어로 번역되어야 한다.” 번역 가능한 문자열을 표시하는 것은 사용자의 책임이다. 시스템은 오직 알고 있는 문자열만을 번역할 수 있기 때문이다.

\n

이때 Django는 번역 문자열을 :term:`메시지 파일`로 추출하는 유틸리티를 제공한다. 이 파일은 번역기가 대상 언어로 된 번역 문자열을 쉽게 제공할 수 있게 한다. 번역기가 메시지 파일을 기입하면, 그것은 컴파일되어야 한다. 이 과정은 GNU gettext 툴세트를 통해 이루어진다.

\n

Once this is done, Django takes care of translating web apps on the fly in each\navailable language, according to users’ language preferences.

\n

Django의 국제화 훅은 켜져 있는 것이 디폴트이며, 이는 프레임워크의 특정 장소에 i18n과 관련된 오버헤드가 있음을 의미한다. 만일 국제화 기능을 사용하지 않는다면, 2초 정도를 할애하여 설정 파일에서 :setting:`USE_I18N = False <USE_I18N>`로 세팅하면 된다. 그러면 Django는 국제화 기능을 로드하지 않도록 몇 가지 최적화 작업을 수행한다.

\n\n
\n
\n

Internationalization: in Python codeLink to this heading#

\n
\n

Standard translationLink to this heading#

\n

Specify a translation string by using the function\ngettext(). It’s convention to import this\nas a shorter alias, _, to save typing.

\n\n\n

In this example, the text "Welcome to my site." is marked as a translation\nstring:

\n
Code
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)\n
\n

You could code this without using the alias. This example is identical to the\nprevious one:

\n
Code
from 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)\n
\n

Translation works on computed values. This example is identical to the previous\ntwo:

\n
Code
def my_view(request):\n    words = ["Welcome", "to", "my", "site."]\n    output = _(" ".join(words))\n    return HttpResponse(output)\n
\n

Translation works on variables. Again, here’s an identical example:

\n
Code
def my_view(request):\n    sentence = "Welcome to my site."\n    output = _(sentence)\n    return HttpResponse(output)\n
\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.)

\n

The strings you pass to _() or gettext() can take placeholders,\nspecified with Python’s standard named-string interpolation syntax. Example:

\n
Code
def my_view(request, m, d):\n    output = _("Today is %(month)s %(day)s.") % {"month": m, "day": d}\n    return HttpResponse(output)\n
\n

This 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.

\n

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.

\n

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:

\n
Code
# 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.\n
\n

JavaScript template strings need gettext 0.21+.

\n
\n
\n

Comments for translatorsLink to this heading#

\n

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.:

\n
Code
def my_view(request):\n    # Translators: This message appears on the home page only\n    output = gettext("Welcome to my site.")\n
\n

The 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.

\n\n

This also works in templates. See Comments for translators in templates for\nmore details.

\n
\n
\n

Marking strings as no-opLink to this heading#

\n

Use 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.

\n

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.

\n
\n
\n

PluralizationLink to this heading#

\n

Use the function django.utils.translation.ngettext() to specify\npluralized messages.

\n

ngettext() takes three arguments: the singular translation string, the\nplural translation string and the number of objects.

\n

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.)

\n

예시:

\n
Code
from 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)\n
\n

In this example the number of objects is passed to the translation\nlanguages as the count variable.

\n

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:

\n
Code
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}\n
\n

Don’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:

\n
Code
text = 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}\n
\n\n
\n
\n

Contextual markersLink to this heading#

\n

Sometimes 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.

\n

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.

\n

예시:

\n
Code
from django.utils.translation import pgettext\n\nmonth = pgettext("month name", "May")\n
\n

or:

\n
Code
from 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    )\n
\n

will appear in the .po file as:

\n
Po
msgctxt "month name"\nmsgid "May"\nmsgstr ""\n
\n

Contextual markers are also supported by the translate and\nblocktranslate template tags.

\n
\n
\n

Lazy translationLink to this heading#

\n

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.

\n

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.

\n

This is essential when calls to these functions are located in code paths that\nare executed at module load time.

\n

This 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:

\n
\n

Model fields and relationships verbose_name and help_text option valuesLink to this heading#

\n

For example, to translate the help text of the name field in the following\nmodel, do the following:

\n
Code
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"))\n
\n

You can mark names of ForeignKey,\nManyToManyField or\nOneToOneField relationship as translatable by using\ntheir verbose_name options:

\n
Code
class 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

Just 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.

\n
\n
\n

Model verbose names valuesLink to this heading#

\n

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:

\n
Code
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")\n
\n
\n
\n

Model methods description argument to the @display decoratorLink to this heading#

\n

For model methods, you can provide translations to Django and the admin site\nwith the description argument to the display()\ndecorator:

\n
Code
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\n
\n
\n
\n
\n

Working with lazy translation objectsLink to this heading#

\n

The 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:

\n
Code
body = gettext_lazy("I \\u2764 Django")  # (Unicode :heart:)\nrequests.post("https://example.com/send", data={"body": body})\n
\n

You can avoid such problems by casting gettext_lazy() objects to text\nstrings before passing them to non-Django code:

\n
Code
requests.post("https://example.com/send", data={"body": str(body)})\n
\n

If you don’t like the long gettext_lazy name, you can alias it as _\n(underscore), like so:

\n
Code
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"))\n
\n

Using 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.

\n
\n

Lazy translations and pluralLink to this heading#

\n

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:

\n
Code
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})\n
\n

If the string contains exactly one unnamed placeholder, you can interpolate\ndirectly with the number argument:

\n
Code
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)\n
\n
\n
\n

Formatting strings: format_lazy()Link to this heading#

\n

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:

\n
Code
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)\n
\n

In 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).

\n
\n
\n

Other uses of lazy in delayed translationsLink to this heading#

\n

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:

\n
Code
from 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)\n
\n

And then later:

\n
Code
lazy_string = to_lower_lazy(_("My STRING!"))\n
\n
\n
\n
\n

Localized names of languagesLink to this heading#

\n
\n
\nget_language_info(lang_code)Link to this definition#
\n
\n\n

The get_language_info() function provides detailed information about\nlanguages:

\n
Python console
>>> 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\n
\n

The 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.

\n

The source of the language information is the django.conf.locale module.\nSimilar access to this information is available for template code. See below.

\n
\n
\n
\n

Internationalization: in template codeLink to this heading#

\n

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.

\n\n
\n

translate template tagLink to this heading#

\n

The {% translate %} template tag translates either a constant string\n(enclosed in single or double quotes) or variable content:

\n
Django template
<title>{% translate "This is the title." %}</title>\n<title>{% translate myvar %}</title>\n
\n

If 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:

\n
Django template
<title>{% translate "myvar" noop %}</title>\n
\n

Internally, inline translations use a\ngettext() call.

\n

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.

\n

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.

\n

If you’d like to retrieve a translated string without displaying it, you can\nuse the following syntax:

\n
Django template
{% translate "This is the title" as the_title %}\n\n<title>{{ the_title }}</title>\n<meta name="description" content="{{ the_title }}">\n
\n

In 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
Django template
{% 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
\n

{% translate %} also supports contextual markers\nusing the context keyword:

\n
Django template
{% translate "May" context "month name" %}\n
\n
\n
\n

blocktranslate template tagLink to this heading#

\n

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:

\n
Django template
{% blocktranslate %}This string will have {{ value }} inside.{% endblocktranslate %}\n
\n

To 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
Django template
{% 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 %}\n
\n

You can use multiple expressions inside a single blocktranslate tag:

\n
Django template
{% blocktranslate with book_t=book|title author_t=author|title %}\nThis is {{ book_t }} by {{ author_t }}\n{% endblocktranslate %}\n
\n\n

Other block tags (for example {% for %} or {% if %})\nare not allowed inside a blocktranslate tag.

\n

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.

\n

This tag also provides for pluralization. To use it:

\n
    \n

  • Designate and bind a counter value with the name count. This value will\nbe the one used to select the right plural form.

    • \n

  • Specify both the singular and plural forms separating them with the\n{% plural %} tag within the {% blocktranslate %} and\n{% endblocktranslate %} tags.

    • \n
\n

An example:

\n
Django template
{% blocktranslate count counter=list|length %}\nThere is {{ counter }} {{ name }} object.\n{% plural %}\nThere are {{ counter }} {{ name }} objects.\n{% endblocktranslate %}\n
\n

A more complex example:

\n
Django template
{% 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 %}\n
\n

When 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.

\n

Reverse URL lookups cannot be carried out within the blocktranslate and\nshould be retrieved (and stored) beforehand:

\n
Django template
{% url 'path.to.view' arg arg2 as the_url %}\n{% blocktranslate %}\nThis is a URL: {{ the_url }}\n{% endblocktranslate %}\n
\n

If you’d like to retrieve a translated string without displaying it, you can\nuse the following syntax:

\n
Django template
{% blocktranslate asvar the_title %}The title is {{ title }}.{% endblocktranslate %}\n<title>{{ the_title }}</title>\n<meta name="description" content="{{ the_title }}">\n
\n

In 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:

\n
Django template
{% blocktranslate with name=user.username context "greeting" %}Hi {{ name }}{% endblocktranslate %}\n
\n

Another 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.

\n

For instance, the following {% blocktranslate %} tag:

\n
Django template
{% blocktranslate trimmed %}\n  First sentence.\n  Second paragraph.\n{% endblocktranslate %}\n
\n

will 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.

\n
\n
\n

String literals passed to tags and filtersLink to this heading#

\n

You can translate string literals passed as arguments to tags and filters\nby using the familiar _() syntax:

\n
Django template
{% some_tag _("Page not found") value|yesno:_("yes,no") %}\n
\n

In this case, both the tag and the filter will see the translated string,\nso they don’t need to be aware of translations.

\n\n
\n
\n

Comments for translators in templatesLink to this heading#

\n

Just like with Python code, these notes for\ntranslators can be specified using comments, either with the comment\ntag:

\n
Django template
{% 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>\n
\n

or with the {# … #}\none-line comment constructs:

\n
Django template
{# 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 %}\n
\n\n
\n
\n

Switching language in templatesLink to this heading#

\n

If you want to select a language within a template, you can use the\nlanguage template tag:

\n
Django template
{% 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 %}\n
\n

While the first occurrence of “Welcome to our page” uses the current language,\nthe second will always be in English.

\n
\n
\n

Other tagsLink to this heading#

\n

These tags also require a {% load i18n %}.

\n
\n

get_available_languagesLink to this heading#

\n

{% get_available_languages as LANGUAGES %} returns a list of tuples in\nwhich the first element is the language code and the second is the\nlanguage name (translated into the currently active locale).

\n
\n
\n

get_current_languageLink to this heading#

\n

{% get_current_language as LANGUAGE_CODE %} returns the current user’s\npreferred language as a string. Example: en-us. See\nHow Django discovers language preference.

\n
\n
\n

get_current_language_bidiLink to this heading#

\n

{% get_current_language_bidi as LANGUAGE_BIDI %} returns the current\nlocale’s direction. If True, it’s a right-to-left language, e.g. Hebrew,\nArabic. If False it’s a left-to-right language, e.g. English, French,\nGerman, etc.

\n
\n
\n

i18n context processorLink to this heading#

\n

If you enable the django.template.context_processors.i18n context\nprocessor, then each RequestContext will have access to LANGUAGES,\nLANGUAGE_CODE, and LANGUAGE_BIDI as defined above.

\n
\n
\n

get_language_infoLink to this heading#

\n

You can also retrieve information about any of the available languages using\nprovided template tags and filters. To get information about a single language,\nuse the {% get_language_info %} tag:

\n
Django template
{% get_language_info for LANGUAGE_CODE as lang %}\n{% get_language_info for "pl" as lang %}\n
\n

You can then access the information:

\n
Django template
Language code: {{ lang.code }}<br>\nName of language: {{ lang.name_local }}<br>\nName in English: {{ lang.name }}<br>\nBi-directional: {{ lang.bidi }}\nName in the active language: {{ lang.name_translated }}\n
\n
\n
\n

get_language_info_listLink to this heading#

\n

You can also use the {% get_language_info_list %} template tag to retrieve\ninformation for a list of languages (e.g. active languages as specified in\nLANGUAGES). See the section about the set_language redirect\nview for an example of how to display a language\nselector using {% get_language_info_list %}.

\n

In addition to LANGUAGES style list of tuples,\n{% get_language_info_list %} supports lists of language codes.\nIf you do this in your view:

\n
Python
context = {"available_languages": ["en", "es", "fr"]}\nreturn render(request, "mytemplate.html", context)\n
\n

you can iterate over those languages in the template:

\n
Django template
{% get_language_info_list for available_languages as langs %}\n{% for lang in langs %} ... {% endfor %}\n
\n
\n
\n

템플릿 필터Link to this heading#

\n

There are also some filters available for convenience:

\n
    \n

  • {{ LANGUAGE_CODE|language_name }} (“German”)

    • \n

  • {{ LANGUAGE_CODE|language_name_local }} (“Deutsch”)

    • \n

  • {{ LANGUAGE_CODE|language_bidi }} (False)

    • \n

  • {{ LANGUAGE_CODE|language_name_translated }} (“německy”, when active\nlanguage is Czech)

    • \n
\n
\n
\n
\n
\n

Internationalization: in JavaScript codeLink to this heading#

\n

Adding translations to JavaScript poses some problems:

\n\n

Django provides an integrated solution for these problems: It passes the\ntranslations into JavaScript, so you can call gettext, etc., from within\nJavaScript.

\n

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.

\n
\n

The JavaScriptCatalog viewLink to this heading#

\n
\n
\nclass JavaScriptCatalogLink to this definition#
\n

A view that produces a JavaScript code library with functions that mimic\nthe gettext interface, plus an array of translation strings.

\n

Attributes

\n
\n
\ndomainLink to this definition#
\n

Translation domain containing strings to add in the view output.\nDefaults to 'djangojs'.

\n
\n\n
\n
\npackagesLink to this definition#
\n

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.

\n
\n\n

Example with default values:

\n
Code
from django.views.i18n import JavaScriptCatalog\n\nurlpatterns = [\n    path("jsi18n/", JavaScriptCatalog.as_view(), name="javascript-catalog"),\n]\n
\n

Example with custom packages:

\n
Code
urlpatterns = [\n    path(\n        "jsi18n/myapp/",\n        JavaScriptCatalog.as_view(packages=["your.app.label"]),\n        name="javascript-catalog",\n    ),\n]\n
\n

If your root URLconf uses i18n_patterns(),\nJavaScriptCatalog must also be wrapped by i18n_patterns() for the\ncatalog to be correctly generated.

\n

Example with i18n_patterns():

\n
Code
from django.conf.urls.i18n import i18n_patterns\n\nurlpatterns = i18n_patterns(\n    path("jsi18n/", JavaScriptCatalog.as_view(), name="javascript-catalog"),\n)\n
\n
\n\n

The 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.

\n

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.

\n
\n
\n

Using the JavaScript translation catalogLink to this heading#

\n

To use the catalog, pull in the dynamically generated script like this:

\n
Django template
<script src="{% url 'javascript-catalog' %}"></script>\n
\n

This 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:

\n
    \n

  • gettext

    • \n

  • ngettext

    • \n

  • interpolate

    • \n

  • get_format

    • \n

  • gettext_noop

    • \n

  • pgettext

    • \n

  • npgettext

    • \n

  • pluralidx

    • \n
\n
\n

gettextLink to this heading#

\n

The gettext function behaves similarly to the standard gettext\ninterface within your Python code:

\n
Code
document.write(gettext("this is to be translated"))\n
\n
\n
\n

ngettextLink to this heading#

\n

The ngettext function provides an interface to pluralize words and\nphrases:

\n
JavaScript
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);\n
\n
\n
\n

interpolateLink to this heading#

\n

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:

\n
    \n

  • 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:

    \n
    JavaScript
    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'\n
    \n
    • \n

  • Named interpolation: This mode is selected by passing the optional\nboolean named parameter as true. obj contains a JavaScript\nobject or associative array. For example:

    \n
    JavaScript
    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);\n
    \n
    • \n
\n

You 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).

\n
\n
\n

get_formatLink to this heading#

\n

The get_format function has access to the configured i18n formatting\nsettings and can retrieve the format string for a given setting name:

\n
JavaScript
document.write(get_format('DATE_FORMAT'));\n// 'N j, Y'\n
\n

It has access to the following settings:

\n\n

This is useful for maintaining formatting consistency with the Python-rendered\nvalues.

\n
\n
\n

gettext_noopLink to this heading#

\n

This emulates the gettext function but does nothing, returning whatever\nis passed to it:

\n
Code
document.write(gettext_noop("this will not be translated"))\n
\n

This is useful for stubbing out portions of the code that will need translation\nin the future.

\n
\n
\n

pgettextLink to this heading#

\n

The pgettext function behaves like the Python variant\n(pgettext()), providing a contextually\ntranslated word:

\n
Code
document.write(pgettext("month name", "May"))\n
\n
\n
\n

npgettextLink to this heading#

\n

The npgettext function also behaves like the Python variant\n(npgettext()), providing a pluralized\ncontextually translated word:

\n
JavaScript
document.write(npgettext('group', 'party', 1));\n// party\ndocument.write(npgettext('group', 'party', 2));\n// parties\n
\n
\n
\n

pluralidxLink to this heading#

\n

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:

\n
JavaScript
document.write(pluralidx(0));\n// true\ndocument.write(pluralidx(1));\n// false\ndocument.write(pluralidx(2));\n// true\n
\n

In the simplest case, if no custom pluralization is needed, this returns\nfalse for the integer 1 and true for all other numbers.

\n

However, pluralization is not this simple in all languages. If the language\ndoes not support pluralization, an empty value is provided.

\n

Additionally, 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.

\n
\n
\n
\n

The JSONCatalog viewLink to this heading#

\n
\n
\nclass JSONCatalogLink to this definition#
\n

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.

\n

See the documentation for JavaScriptCatalog\nto learn about possible values and use of the domain and packages\nattributes.

\n

The response format is as follows:

\n
Text
{\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}\n
\n
\n\n
\n
\n

Note on performanceLink to this heading#

\n

The 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.

\n

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:

\n
Code
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]\n
\n

Client-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:

\n
Code
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]\n
\n

You 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.

\n
\n
\n
\n

Internationalization: in URL patternsLink to this heading#

\n

Django provides two mechanisms to internationalize URL patterns:

\n\n\n
\n

Language prefix in URL patternsLink to this heading#

\n
\n
\ni18n_patterns(*urls, prefix_default_language=True)Link to this definition#
\n
\n\n

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().

\n

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.

\n

Example URL patterns:

\n
Code
from 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)\n
\n

After defining these URL patterns, Django will automatically add the\nlanguage prefix to the URL patterns that were added by the i18n_patterns\nfunction. Example:

\n
Python console
>>> 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/'\n
\n

With prefix_default_language=False and LANGUAGE_CODE='en', the URLs\nwill be:

\n
Python console
>>> activate("en")\n>>> reverse("news:index")\n'/news/'\n\n>>> activate("nl")\n>>> reverse("news:index")\n'/nl/news/'\n
\n\n\n
\n
\n

Translating URL patternsLink to this heading#

\n

URL patterns can also be marked translatable using the\ngettext_lazy() function. Example:

\n
Code
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)\n
\n

After you’ve created the translations, the reverse()\nfunction will return the URL in the active language. Example:

\n
Python console
>>> 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/'\n
\n\n
\n
\n

Reversing in templatesLink to this heading#

\n

If 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:

\n
Django template
{% 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 %}\n
\n

The language tag expects the language code as the only argument.

\n
\n
\n
\n

Localization: how to create language filesLink to this heading#

\n

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.

\n
\n

Message filesLink to this heading#

\n

The 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.

\n

Django comes with a tool, django-admin makemessages, that automates the creation and upkeep of these files.

\n\n

To create or update a message file, run this command:

\n
Shell
django-admin makemessages -l de\n
\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.

\n

The script should be run from one of two places:

\n
    \n

  • The root directory of your Django project (the one that contains\nmanage.py).

    • \n

  • The root directory of one of your Django apps.

    • \n
\n

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.

\n

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.

\n

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:

\n
Shell
django-admin makemessages -l de -e txt\n
\n

Separate multiple extensions with commas and/or use -e or --extension\nmultiple times:

\n
Shell
django-admin makemessages -l de -e html,txt -e xml\n
\n\n\n\n\n

Each .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.

\n

For example, if your Django app contained a translation string for the text\n"Welcome to my site.", like so:

\n
Code
_("Welcome to my site.")\n
\n

…then django-admin makemessages will have created\na .po file containing the following snippet – a message:

\n
Po
#: path/to/python/module.py:23\nmsgid "Welcome to my site."\nmsgstr ""\n
\n

A quick explanation:

\n
    \n

  • msgid is the translation string, which appears in the source. Don’t\nchange it.

    • \n

  • 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.

    • \n

  • 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.

    • \n
\n

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!

\n\n\n

To reexamine all source code and templates for new translation strings and\nupdate all message files for all languages, run this:

\n
Shell
django-admin makemessages -a\n
\n
\n
\n

Compiling message filesLink to this heading#

\n

After 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.

\n

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:

\n
Shell
django-admin compilemessages\n
\n

That’s it. Your translations are ready for use.

\n\n\n
\n
\n

Troubleshooting: gettext() incorrectly detects python-format in strings with percent signsLink to this heading#

\n

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.

\n

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'.

\n

To workaround this, you can escape percent signs by adding a second percent\nsign:

\n
Code
from django.utils.translation import gettext as _\n\noutput = _("10%% interest")\n
\n

Or you can use no-python-format so that all percent signs are treated as\nliterals:

\n
Code
# xgettext:no-python-format\noutput = _("10% interest")\n
\n
\n
\n

Creating message files from JavaScript source codeLink to this heading#

\n

You 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:

\n
Shell
django-admin makemessages -d djangojs -l de\n
\n

This 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.

\n
\n
\n

gettext on WindowsLink to this heading#

\n

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.

\n

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”.

\n
\n
\n

Customizing the makemessages commandLink to this heading#

\n

If you want to pass additional parameters to xgettext, you need to create a\ncustom makemessages command and override its xgettext_options\nattribute:

\n
Code
from django.core.management.commands import makemessages\n\n\nclass Command(makemessages.Command):\n    xgettext_options = makemessages.Command.xgettext_options + ["--keyword=mytrans"]\n
\n

If you need more flexibility, you could also add a new argument to your custom\nmakemessages command:

\n
Code
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)\n
\n
\n
\n
\n

기타Link to this heading#

\n
\n

The set_language redirect viewLink to this heading#

\n
\n
\nset_language(request)Link to this definition#
\n
\n\n

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.

\n

Activate this view by adding the following line to your URLconf:

\n
Code
path("i18n/", include("django.conf.urls.i18n")),\n
\n

(Note that this example makes the view available at /i18n/setlang/.)

\n\n

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.)

\n

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:

\n
    \n

  • If the request accepts HTML content (based on its Accept HTTP header),\nthe fallback will always be performed.

    • \n

  • 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.

    • \n
\n

Here’s example HTML template code:

\n
Django template
{% 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>\n
\n

In this example, Django looks up the URL of the page to which the user will be\nredirected in the redirect_to context variable.

\n
\n
\n

Explicitly setting the active languageLink to this heading#

\n

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:

\n
Code
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)\n
\n

You 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.

\n
\n
\n

Using translations outside views and templatesLink to this heading#

\n

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.

\n

예시:

\n
Code
from 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\n
\n

Calling this function with the value 'de' will give you "Willkommen",\nregardless of LANGUAGE_CODE and language set by middleware.

\n

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.

\n

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:

\n
Code
from django.utils import translation\n\n\ndef welcome_translated(language):\n    with translation.override(language):\n        return translation.gettext("welcome")\n
\n
\n
\n

Language cookieLink to this heading#

\n

A number of settings can be used to adjust language cookie options:

\n\n
\n
\n
\n

Implementation notesLink to this heading#

\n
\n

Specialties of Django translationLink to this heading#

\n

Django’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:

\n
    \n

  • 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.

    • \n

  • Django doesn’t use xgettext alone. It uses Python wrappers around\nxgettext and msgfmt. This is mostly for convenience.

    • \n
\n
\n
\n

How Django discovers language preferenceLink to this heading#

\n

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.

\n

Behind the scenes, Django has a very flexible model of deciding which language\nshould be used – installation-wide, for a particular user, or both.

\n

To 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).

\n

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.

\n

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.

\n

To use LocaleMiddleware, add\n'django.middleware.locale.LocaleMiddleware' to your MIDDLEWARE\nsetting. Because middleware order matters, follow these guidelines:

\n
    \n

  • Make sure it’s one of the first middleware installed.

    • \n

  • 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.

    • \n

  • If you use CacheMiddleware, put LocaleMiddleware after it.

    • \n
\n

For example, your MIDDLEWARE might look like this:

\n
Code
MIDDLEWARE = [\n    "django.contrib.sessions.middleware.SessionMiddleware",\n    "django.middleware.locale.LocaleMiddleware",\n    "django.middleware.common.CommonMiddleware",\n]\n
\n

(For more on middleware, see the middleware documentation.)

\n

LocaleMiddleware tries to determine the user’s language preference by\nfollowing this algorithm:

\n
    \n

  • 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.

    • \n

  • Failing that, it looks for a cookie.

    \n

    The name of the cookie used is set by the LANGUAGE_COOKIE_NAME\nsetting. (The default name is django_language.)

    \n
    • \n

  • 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.

    • \n

  • Failing that, it uses the global LANGUAGE_CODE setting.

    • \n
\n

각주:

\n
    \n

  • In 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.

    • \n

  • 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.

    • \n

  • 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:

    \n
    Code
    LANGUAGES = [\n    ("de", _("German")),\n    ("en", _("English")),\n]\n
    \n

    This example restricts languages that are available for automatic\nselection to German and English (and any sublanguage, like de-ch or\nen-us).

    \n
    • \n

  • 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.

    \n

    샘플 설정 파일이 있습니다:

    \n
    Code
    from django.utils.translation import gettext_lazy as _\n\nLANGUAGES = [\n    ("de", _("German")),\n    ("en", _("English")),\n]\n
    \n
    • \n
\n

Once 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:

\n
Code
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.")\n
\n

Note that, with static (middleware-less) translation, the language is in\nsettings.LANGUAGE_CODE, while with dynamic (middleware) translation, it’s\nin request.LANGUAGE_CODE.

\n
\n
\n

How Django discovers translationsLink to this heading#

\n

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:

\n
    \n

  1. The directories listed in LOCALE_PATHS have the highest\nprecedence, with the ones appearing first having higher precedence than\nthe ones appearing later.

    2. \n

  2. 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.

    3. \n

  3. Finally, the Django-provided base translation in\ndjango/conf/locale is used as a fallback.

    4. \n
\n\n

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.

\n

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.

\n

All message file repositories are structured the same way. They are:

\n
    \n

  • All paths listed in LOCALE_PATHS in your settings file are\nsearched for <language>/LC_MESSAGES/django.(po|mo)

    • \n

  • $APPPATH/locale/<language>/LC_MESSAGES/django.(po|mo)

    • \n

  • $PYTHONPATH/django/conf/locale/<language>/LC_MESSAGES/django.(po|mo)

    • \n
\n

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.

\n

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.

\n
\n
\n

Using a non-English base languageLink to this heading#

\n

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:

\n
    \n

  • gettext 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.

    • \n

  • 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.

    • \n
\n
\n
","rootId":"translation","toc":[{"title":"개요","anchor":"overview","children":[]},{"title":"Internationalization: in Python code","anchor":"internationalization-in-python-code","children":[{"title":"Standard translation","anchor":"standard-translation","children":[]},{"title":"Comments for translators","anchor":"comments-for-translators","children":[]},{"title":"Marking strings as no-op","anchor":"marking-strings-as-no-op","children":[]},{"title":"Pluralization","anchor":"pluralization","children":[]},{"title":"Contextual markers","anchor":"contextual-markers","children":[]},{"title":"Lazy translation","anchor":"lazy-translation","children":[{"title":"Model fields and relationships verbose_name and help_text option values","anchor":"model-fields-and-relationships-verbose-name-and-help-text-option-values","children":[]},{"title":"Model verbose names values","anchor":"model-verbose-names-values","children":[]},{"title":"Model methods description argument to the @display decorator","anchor":"model-methods-description-argument-to-the-display-decorator","children":[]}]},{"title":"Working with lazy translation objects","anchor":"working-with-lazy-translation-objects","children":[{"title":"Lazy translations and plural","anchor":"lazy-translations-and-plural","children":[]},{"title":"Formatting strings: format_lazy()","anchor":"formatting-strings-format-lazy","children":[]},{"title":"Other uses of lazy in delayed translations","anchor":"other-uses-of-lazy-in-delayed-translations","children":[]}]},{"title":"Localized names of languages","anchor":"localized-names-of-languages","children":[]}]},{"title":"Internationalization: in template code","anchor":"internationalization-in-template-code","children":[{"title":"translate template tag","anchor":"translate-template-tag","children":[]},{"title":"blocktranslate template tag","anchor":"blocktranslate-template-tag","children":[]},{"title":"String literals passed to tags and filters","anchor":"string-literals-passed-to-tags-and-filters","children":[]},{"title":"Comments for translators in templates","anchor":"comments-for-translators-in-templates","children":[]},{"title":"Switching language in templates","anchor":"switching-language-in-templates","children":[]},{"title":"Other tags","anchor":"other-tags","children":[{"title":"get_available_languages","anchor":"get-available-languages","children":[]},{"title":"get_current_language","anchor":"get-current-language","children":[]},{"title":"get_current_language_bidi","anchor":"get-current-language-bidi","children":[]},{"title":"i18n context processor","anchor":"i18n-context-processor","children":[]},{"title":"get_language_info","anchor":"get-language-info","children":[]},{"title":"get_language_info_list","anchor":"get-language-info-list","children":[]},{"title":"템플릿 필터","anchor":"template-filters","children":[]}]}]},{"title":"Internationalization: in JavaScript code","anchor":"internationalization-in-javascript-code","children":[{"title":"The JavaScriptCatalog view","anchor":"module-django.views.i18n","children":[]},{"title":"Using the JavaScript translation catalog","anchor":"using-the-javascript-translation-catalog","children":[{"title":"gettext","anchor":"gettext","children":[]},{"title":"ngettext","anchor":"ngettext","children":[]},{"title":"interpolate","anchor":"interpolate","children":[]},{"title":"get_format","anchor":"get-format","children":[]},{"title":"gettext_noop","anchor":"gettext-noop","children":[]},{"title":"pgettext","anchor":"pgettext","children":[]},{"title":"npgettext","anchor":"npgettext","children":[]},{"title":"pluralidx","anchor":"pluralidx","children":[]}]},{"title":"The JSONCatalog view","anchor":"the-jsoncatalog-view","children":[]},{"title":"Note on performance","anchor":"note-on-performance","children":[]}]},{"title":"Internationalization: in URL patterns","anchor":"module-django.conf.urls.i18n","children":[{"title":"Language prefix in URL patterns","anchor":"language-prefix-in-url-patterns","children":[]},{"title":"Translating URL patterns","anchor":"translating-url-patterns","children":[]},{"title":"Reversing in templates","anchor":"reversing-in-templates","children":[]}]},{"title":"Localization: how to create language files","anchor":"localization-how-to-create-language-files","children":[{"title":"Message files","anchor":"message-files","children":[]},{"title":"Compiling message files","anchor":"compiling-message-files","children":[]},{"title":"Troubleshooting: gettext() incorrectly detects python-format in strings with percent signs","anchor":"troubleshooting-gettext-incorrectly-detects-python-format-in-strings-with-percent-signs","children":[]},{"title":"Creating message files from JavaScript source code","anchor":"creating-message-files-from-javascript-source-code","children":[]},{"title":"gettext on Windows","anchor":"gettext-on-windows","children":[]},{"title":"Customizing the makemessages command","anchor":"customizing-the-makemessages-command","children":[]}]},{"title":"기타","anchor":"miscellaneous","children":[{"title":"The set_language redirect view","anchor":"the-set-language-redirect-view","children":[]},{"title":"Explicitly setting the active language","anchor":"explicitly-setting-the-active-language","children":[]},{"title":"Using translations outside views and templates","anchor":"using-translations-outside-views-and-templates","children":[]},{"title":"Language cookie","anchor":"language-cookie","children":[]}]},{"title":"Implementation notes","anchor":"implementation-notes","children":[{"title":"Specialties of Django translation","anchor":"specialties-of-django-translation","children":[]},{"title":"How Django discovers language preference","anchor":"how-django-discovers-language-preference","children":[]},{"title":"How Django discovers translations","anchor":"how-django-discovers-translations","children":[]},{"title":"Using a non-English base language","anchor":"using-a-non-english-base-language","children":[]}]}],"breadcrumbs":[{"docname":"topics/index","title":"Django 사용하기","url":"/ko/6.0/topics/"},{"docname":"topics/i18n/index","title":"국제화와 현지화","url":"/ko/6.0/topics/i18n/"}],"prev":{"docname":"topics/i18n/index","title":"국제화와 현지화","url":"/ko/6.0/topics/i18n/"},"next":{"docname":"topics/i18n/formatting","title":"Format localization","url":"/ko/6.0/topics/i18n/formatting/"},"formats":{"html":"/ko/6.0/topics/i18n/translation/","markdown":"/ko/6.0/topics/i18n/translation.md","json":"/ko/6.0/topics/i18n/translation.json"},"source":"https://github.com/django/django/blob/stable/6.0.x/docs/topics/i18n/translation.txt","official":"https://docs.djangoproject.com/ko/6.0/topics/i18n/translation/","inVersions":["6.1","6.0","5.2","5.1","5.0","4.2","4.1","4.0","3.2","3.1","3.0","2.2","2.1","2.0","1.11"],"inLocales":["en","sv","zh-hans","ga","fr","ja","id","it","pt-br","ko","es","el","pl"]}