Обычный перевод¶

Укажите переводимую строку с помощью функции ugettext(). Удобно импортировать её с помощью краткого псевдонима, _ (символ подчеркивания), чтобы сократить затраты на ввод.

В данном примере, текст "Welcome to my site." помечается как переводимая строка:

from django.http import HttpResponse
from django.utils.translation import gettext as _

def my_view(request):
    output = _("Welcome to my site.")
    return HttpResponse(output)

Очевидно, что вы можете делать тоже самое без использования псевдонима. Этот пример идентичен предыдущему:

from django.http import HttpResponse
from django.utils.translation import gettext

def my_view(request):
    output = gettext("Welcome to my site.")
    return HttpResponse(output)

Перевод работает с вычисляемыми значениями. Этот пример идентичен предыдущим двум:

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

Перевод работает с переменными. И снова, аналогичный пример:

def my_view(request):
    sentence = 'Welcome to my site.'
    output = _(sentence)
    return HttpResponse(output)

(Проблема при использовании переменных или вычисляемых значений, как в предыдущих двух примерах, в том, что утилита для поиска переводимых строк, django-admin makemessages, не сможет найти эти строки. Далее мы подробно рассмотрим makemessages.)

Строка, передаваемая в _() или ugettext(), может принимать заполнители (placeholders), определённые стандартом языка Python для строк. Пример:

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

Этот метод позволяет переводам для конкретного языка изменить порядок текста-заполнителя. Например, английский перевод может быть «Сегодня 26 ноября», а испанский перевод может быть «Hoy es 26 de noviembre». С заменой заполнителей месяца и дня.

По этой причине, вы должны использовать именованные заполнители (т.е., %(day)s) вместо позиционных (т.е., %s или %d), в случае, если в строку подставляется больше одного параметра. При использовании позиционных заполнителей переводчики не будут иметь возможность изменять оригинальный порядок слов.

Поскольку извлечение строк выполняется командой xgettext, Django поддерживает только синтаксисы, поддерживаемые gettext. В частности, Python f-strings пока не поддерживается xgettext, а для строк шаблона JavaScript требуется gettext 0.21+.

Комментарии для переводчиков¶

Если необходимо дать переводчикам подсказку по переводимой строке, вы можете добавить комментарий с префиксом Translators в строке предшествующей переводимой, например:

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

Комментарий появится в результирующем .po файле, который связан с переводимой конструкцией расположенной далее, и должен быть отображён большинством средств перевода.

#. Translators: This message appears on the home page only
# path/to/python/file.py:123
msgid "Welcome to my site."
msgstr ""

Этот подход также работает в шаблонах. Обратитесь к Комментарии для переводчиков шаблонов для подробностей.

Пометка строк как no-op¶

Используйте функцию django.utils.translation.ugettext_noop() для пометки строки как переводимой, но не переводя её. Такая строка будет переведена позже с помощью переменной.

Используйте этот подход в случае, когда у вас есть строковые константы, которые должны быть сохранены в исходном коде по причине того, что они изменяются системой или пользователями Примером могут служить строки из базы данных, которые следует переводить в самый последний момент, перед непосредственным их отображением пользователю.

Множественное число¶

Используйте функцию django.utils.translation.ungettext() для указания сообщений во множественном числе.

Функция ungettext принимает три аргумента: строка в единственном числе, строка во множественном числе и количество объектов.

Эта функция очень полезна, когда требуется локализовать Django приложение на языки, в которых количество и сложность множественных форм превышает два варианта как в английском языке („object“ для единственного числа и „objects“ для всех остальных случаем, когда count отличается от единицы, независимо от своего значения.)

Например:

from django.http import HttpResponse
from django.utils.translation import ngettext

def hello_world(request, count):
    page = ngettext(
        'there is %(count)d object',
        'there are %(count)d objects',
        count,
    ) % {
        'count': count,
    }
    return HttpResponse(page)

В этом примере количество объектов передаётся в перевод в переменной count.

Следует отметить, что приведение существительного к множественному числу является непростой задачей и работает по-разному в каждом языке. Сравнение count с 1 не всегда будет корректным правилом. Следующий код выглядит разумно, но будет выдавать неверный результат для некоторых языков:

from django.utils.translation import ngettext
from myapp.models import Report

count = Report.objects.count()
if count == 1:
    name = Report._meta.verbose_name
else:
    name = Report._meta.verbose_name_plural

text = ngettext(
    'There is %(count)d %(name)s available.',
    'There are %(count)d %(name)s available.',
    count,
) % {
    'count': count,
    'name': name
}

Не стоит пытаться реализовать собственную логику для создания множественного числа, она не будет работать корректно. В этом случае, рассмотрите использование следующего подхода:

text = ngettext(
    'There is %(count)d %(name)s object available.',
    'There are %(count)d %(name)s objects available.',
    count,
) % {
    'count': count,
    'name': Report._meta.verbose_name,
}

text = ngettext(
    'There is %(count)d %(name)s available.',
    'There are %(count)d %(plural_name)s available.',
    count,
) % {
    'count': Report.objects.count(),
    'name': Report._meta.verbose_name,
    'plural_name': Report._meta.verbose_name_plural,
}

a format specification for argument 'name', as in 'msgstr[0]', doesn't exist in 'msgid'

Контекстные маркеры¶

Некоторые слова имеют множество значений, такие как "May" в английском языке, которое может означать название месяца или глагол. Для упрощения жизни переводчиков вы можете использовать функцию django.utils.translation.pgettext() или функцию django.utils.translation.npgettext(), для множественного числа. Обе функции принимают описание контекста в качестве первого аргумента.

В результате, в файле .po, переводимая строка появится столько раз, сколько есть различных контекстов для неё (контекстная информация будет указана в строке msgctxt), позволяя перевести каждую из них в соответствии со смыслом.

Например:

from django.utils.translation import pgettext

month = pgettext("month name", "May")

или:

from django.db import models
from django.utils.translation import pgettext_lazy

class MyThing(models.Model):
    name = models.CharField(help_text=pgettext_lazy(
        'help text for MyThing model', 'This is the help text'))

появится в файле .po в виде:

msgctxt "month name"
msgid "May"
msgstr ""

Контекстные маркеры также поддерживаются тегами шаблонов translate и blocktranslate.

Ленивый перевод¶

Используйте ленивые версии функций перевода из django.utils.translation (их легко опознать по суффиксу lazy в их именах) для отложенного перевода строк – перевод производится во время обращения к строке, а не когда вызывается функция.

Эти функции хранят ленивую ссылку на строку, не на её перевод. Сам перевод будет выполнен во время использования строки в строковом контексте, например, во время обработки шаблона.

Это полезно, когда функция перевода вызывается при загрузке модуля.

Такое может легко произойти во время определения моделей, форм или модельных форм, так как в Django их поля реализованы в виде атрибутов класса. По этой причине, надо использовать ленивый перевод в следующих случаях:

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

class MyThing(models.Model):
    name = models.CharField(help_text=_('This is the help text'))

class MyThing(models.Model):
    kind = models.ForeignKey(
        ThingKind,
        on_delete=models.CASCADE,
        related_name='kinds',
        verbose_name=_('kind'),
    )

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

class MyThing(models.Model):
    name = models.CharField(_('name'), help_text=_('This is the help text'))

    class Meta:
        verbose_name = _('my thing')
        verbose_name_plural = _('my things')

from django.contrib import admin
from django.db import models
from django.utils.translation import gettext_lazy as _

class MyThing(models.Model):
    kind = models.ForeignKey(
        ThingKind,
        on_delete=models.CASCADE,
        related_name='kinds',
        verbose_name=_('kind'),
    )

    @admin.display(description=_('Is it a mouse?'))
    def is_mouse(self):
        return self.kind.type == MOUSE_TYPE

Работа с ленивыми объектами перевода¶

The result of a gettext_lazy() call can be used wherever you would use a string (a str object) in other Django code, but it may not work with arbitrary Python code. For example, the following won’t work because the requests library doesn’t handle gettext_lazy objects:

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

Вы можете избежать таких проблем, приведя объекты gettext_lazy() к текстовым строкам перед передачей их в код, отличный от Django:

requests.post('https://example.com/send', data={'body': str(body)})

Если вам не нравится писать такое длинное имя, как ugettext_lazy, в можете создать для него псевдоним _ (символ подчеркивания), вот так:

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

class MyThing(models.Model):
    name = models.CharField(help_text=_('This is the help text'))

Использование ugettext_lazy() и ungettext_lazy() для пометки строк в моделях и в прикладных функциях является обычной операцией. Работая с этими объектами в вашем коде, вы должны быть уверены, что вы не преобразовываете их случайно в строки, так как это преобразование должно происходить как можно позже (и будет приниматься во внимание правильная локаль). Это потребует использования вспомогательной функции, описанной далее.

from django import forms
from django.core.exceptions import ValidationError
from django.utils.translation import ngettext_lazy

class MyForm(forms.Form):
    error_message = ngettext_lazy("You only provided %(num)d argument",
        "You only provided %(num)d arguments", 'num')

    def clean(self):
        # ...
        if error:
            raise ValidationError(self.error_message % {'num': number})

class MyForm(forms.Form):
    error_message = ngettext_lazy(
        "You provided %d argument",
        "You provided %d arguments",
    )

    def clean(self):
        # ...
        if error:
            raise ValidationError(self.error_message % number)

from django.utils.text import format_lazy
from django.utils.translation import gettext_lazy
...
name = gettext_lazy('John Lennon')
instrument = gettext_lazy('guitar')
result = format_lazy('{name}: {instrument}', name=name, instrument=instrument)

from django.utils.functional import lazy
from django.utils.safestring import mark_safe
from django.utils.translation import gettext_lazy as _

mark_safe_lazy = lazy(mark_safe, str)

lazy_string = mark_safe_lazy(_("<p>My <strong>string!</strong></p>"))

Локализованные названия языков¶

get_language_info()¶

The get_language_info() function provides detailed information about languages:

>>> from django.utils.translation import activate, get_language_info
>>> activate('fr')
>>> li = get_language_info('de')
>>> print(li['name'], li['name_local'], li['name_translated'], li['bidi'])
German Deutsch Allemand False

Атрибуты name и name_local содержат название языка на английском и на этом самом языке соответственно. Атрибут bidi установлен в True только для двунаправленных языков.

Источником информации о языках является модуль django.conf.locale. Аналогичный доступ к информации о языках есть и на уровне шаблонов. См. далее.

Тег шаблона translate¶

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

<title>{% translate "This is the title." %}</title>
<title>{% translate myvar %}</title>

If the noop option is present, variable lookup still takes place but the translation is skipped. This is useful when «stubbing out» content that will require translation in the future:

<title>{% translate "myvar" noop %}</title>

Internally, inline translations use an gettext() call.

В случае передачи шаблонной переменой (см. выше myvar) в тег, тег сначала преобразовывает её в строку, а затем ищет для неё перевод в каталогах сообщений.

Невозможно смешивать переменную шаблона внутри строки внутри {%translate %}. Если для ваших переводов требуются строки с переменными (заполнителями), используйте вместо них {%blocktranslate %}.

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

{% translate "This is the title" as the_title %}

<title>{{ the_title }}</title>
<meta name="description" content="{{ the_title }}">

In practice you’ll use this to get a string you can use in multiple places in a template or so you can use the output as an argument for other template tags or filters:

{% translate "starting point" as start %}
{% translate "end point" as end %}
{% translate "La Grande Boucle" as race %}

<h1>
  <a href="/" title="{% blocktranslate %}Back to '{{ race }}' homepage{% endblocktranslate %}">{{ race }}</a>
</h1>
<p>
{% for stage in tour_stages %}
    {% cycle start end %}: {{ stage }}{% if forloop.counter|divisibleby:2 %}<br>{% else %}, {% endif %}
{% endfor %}
</p>

{%translate %} также поддерживает контекстные маркеры с использованием ключевого слова context:

{% translate "May" context "month name" %}

Тег шаблона blocktranslate¶

Contrarily to the translate tag, the blocktranslate tag allows you to mark complex sentences consisting of literals and variable content for translation by making use of placeholders:

{% blocktranslate %}This string will have {{ value }} inside.{% endblocktranslate %}

To translate a template expression – say, accessing object attributes or using template filters – you need to bind the expression to a local variable for use within the translation block. Examples:

{% blocktranslate with amount=article.price %}
That will cost $ {{ amount }}.
{% endblocktranslate %}

{% blocktranslate with myvar=value|filter %}
This will have {{ myvar }} inside.
{% endblocktranslate %}

You can use multiple expressions inside a single blocktranslate tag:

{% blocktranslate with book_t=book|title author_t=author|title %}
This is {{ book_t }} by {{ author_t }}
{% endblocktranslate %}

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

Если разрешение одного из аргументов блока не удалось, blocktranslate вернется к языку по умолчанию, временно деактивируя текущий активный язык с помощью функции deactivate_all().

Этот тег также поддерживает склонение, например:

• Определите переменную count и свяжите с ней значение счётчика. По этому значению будет выбираться форма склонения.

• Укажите форму единственного и множественного числа, разделив их тегом {% Multiple %} внутри тегов {%blocktranslate %} и {% endblocktranslate %}.

Например:

{% blocktranslate count counter=list|length %}
There is only one {{ name }} object.
{% plural %}
There are {{ counter }} {{ name }} objects.
{% endblocktranslate %}

A more complex example:

{% blocktranslate with amount=article.price count years=i.length %}
That will cost $ {{ amount }} per year.
{% plural %}
That will cost $ {{ amount }} per {{ years }} years.
{% endblocktranslate %}

Когда вы используете функцию множественного числа и привязываете значения к локальным переменным в дополнение к значению счетчика, имейте в виду, что конструкция blocktranslate внутренне преобразуется в вызов ngettext. Это означает, что применяются те же примечания относительно переменных ngettext.

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

{% url 'path.to.view' arg arg2 as the_url %}
{% blocktranslate %}
This is a URL: {{ the_url }}
{% endblocktranslate %}

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

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

На практике вы будете применять это для получения строк, которые используются во множестве мест шаблона или должны быть использованы в качестве аргументов для других шаблонных тегов или фильтров:

{%blocktranslate %} также поддерживает контекстные маркеры с использованием ключевого слова context:

{% blocktranslate with name=user.username context "greeting" %}Hi {{ name }}{% endblocktranslate %}

Another feature {% blocktranslate %} supports is the trimmed option. This option will remove newline characters from the beginning and the end of the content of the {% blocktranslate %} tag, replace any whitespace at the beginning and end of a line and merge all lines into one using a space character to separate them. This is quite useful for indenting the content of a {% blocktranslate %} tag without having the indentation characters end up in the corresponding entry in the PO file, which makes the translation process easier.

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

{% blocktranslate trimmed %}
  First sentence.
  Second paragraph.
{% endblocktranslate %}

will result in the entry "First sentence. Second paragraph." in the PO file, compared to "\n  First sentence.\n  Second paragraph.\n", if the trimmed option had not been specified.

Строки передаваемые в шаблонные теги и фильтры¶

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

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

В этом случае, и тег, и фильтр увидят заранее переведённую строку, т.е. им не надо будет беспокоиться о переводе.

Комментарии для переводчиков шаблонов¶

Аналогично случаю с кодом на языке Python, такие пометки для переводчиков могут быть сделаны с помощью комментариев, например с помощью тега comment:

{% comment %}Translators: View verb{% endcomment %}
{% translate "View" %}

{% comment %}Translators: Short intro blurb{% endcomment %}
<p>{% blocktranslate %}A multiline translatable
literal.{% endblocktranslate %}</p>

или с помощью {# … #} однострочного комментария:

{# Translators: Label of a button that triggers search #}
<button type="submit">{% translate "Go" %}</button>

{# Translators: This is a text of the base template #}
{% blocktranslate %}Ambiguous translatable block of text{% endblocktranslate %}

#. Translators: View verb
# path/to/template/file.html:10
msgid "View"
msgstr ""

#. Translators: Short intro blurb
# path/to/template/file.html:13
msgid ""
"A multiline translatable"
"literal."
msgstr ""

# ...

#. Translators: Label of a button that triggers search
# path/to/template/file.html:100
msgid "Go"
msgstr ""

#. Translators: This is a text of the base template
# path/to/template/file.html:103
msgid "Ambiguous translatable block of text"
msgstr ""

Переключения языка в шаблоне¶

Если вы хотите выбрать язык в шаблоне, используйте тег language:

{% load i18n %}

{% get_current_language as LANGUAGE_CODE %}
<!-- Current language: {{ LANGUAGE_CODE }} -->
<p>{% translate "Welcome to our page" %}</p>

{% language 'en' %}
    {% get_current_language as LANGUAGE_CODE %}
    <!-- Current language: {{ LANGUAGE_CODE }} -->
    <p>{% translate "Welcome to our page" %}</p>
{% endlanguage %}

Первая фраза «Welcome to our page» будет использовать текущий язык, в то время как вторая будет на Английском.

Другие теги¶

Эти теги также требуют наличия {% load i18n %} в шаблоне.

{% get_language_info for LANGUAGE_CODE as lang %}
{% get_language_info for "pl" as lang %}

Language code: {{ lang.code }}<br>
Name of language: {{ lang.name_local }}<br>
Name in English: {{ lang.name }}<br>
Bi-directional: {{ lang.bidi }}
Name in the active language: {{ lang.name_translated }}

context = {'available_languages': ['en', 'es', 'fr']}
return render(request, 'mytemplate.html', context)

{% get_language_info_list for available_languages as langs %}
{% for lang in langs %} ... {% endfor %}

Представление javascript_catalog¶

class JavaScriptCatalog¶

Представление, создающее библиотеку кода JavaScript с функциями, имитирующими интерфейс gettext, а также массив строк перевода.

Атрибуты

domain¶

Домен перевода, содержащий строки для добавления в выходные данные представления. По умолчанию используется 'djangojs'.

packages¶

Список имен приложений среди установленных приложений. Эти приложения должны содержать каталог «locale». Все эти каталоги, а также все каталоги, найденные в LOCALE_PATHS (которые всегда включены) объединяются в один каталог. По умолчанию установлено значение «Нет», что означает, что все доступные переводы из всех INSTALLED_APPS предоставляются в выходных данных JavaScript.

Пример со значениями по умолчанию:

from django.views.i18n import JavaScriptCatalog

urlpatterns = [
    path('jsi18n/', JavaScriptCatalog.as_view(), name='javascript-catalog'),
]

Пример с пользовательскими пакетами:

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

Если ваш корневой URLconf использует i18n_patterns(), JavaScriptCatalog также должен быть обернут i18n_patterns() для корректной генерации каталога.

Перевод шаблонов URL

from django.conf.urls.i18n import i18n_patterns

urlpatterns = i18n_patterns(
    path('jsi18n/', JavaScriptCatalog.as_view(), name='javascript-catalog'),
)

Приоритет переводов таков, что пакеты, определённые позже, имеют более высокий приоритет, чем определённые ранее. Это важно, если переводы совпадают в разных приложениях.

Если вы используете несколько javascript_catalog, и они содержат одинаковые строки, будет использоваться перевод из последнего каталога.

Использование каталога переводов JavaScript¶

Для использования этого каталога, просто запросите динамически генерируемый скрипт, как показано ниже:

<script src="{% url 'javascript-catalog' %}"></script>

Здесь используется запрос на поиск URL для представления, генерирующего JavaScript-каталог. После загрузки каталога, ваш JavaScript код может использовать следующие методы:

• gettext

• ngettext

• interpolate

• get_format

• gettext_noop

• pgettext

• npgettext

• pluralidx

document.write(gettext('this is to be translated'));

const objectCount = 1 // or 0, or 2, or 3, ...
const string = ngettext(
    'literal for the singular case',
    'literal for the plural case',
    objectCount
);

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

document.write(gettext_noop('this will not be translated'));

document.write(pgettext('month name', 'May'));

document.write(npgettext('group', 'party', 1));
// party
document.write(npgettext('group', 'party', 2));
// parties

document.write(pluralidx(0));
// true
document.write(pluralidx(1));
// false
document.write(pluralidx(2));
// true

Представление json_catalog¶

class JSONCatalog¶

Если вы используете другие клиентские библиотеки для перевода, вам может пригодится представление json_catalog(). Оно работает аналогично javascript_catalog(), но возвращает JSON.

См. документацию по JavaScriptCatalog, чтобы узнать о возможных значениях и использовании атрибутов domain и packages.

Формат ответа следующий:

{
    "catalog": {
        # Translations catalog
    },
    "formats": {
        # Language formats for date, time, etc.
    },
    "plural": "..."  # Expression for plural forms, or null.
}

Комментарий о производительности¶

Представление javascript_catalog() создаёт каталог из .mo файлов при каждом запросе. И раз вывод предоставления неизменен, как минимум для текущей версии сайта, его следует закэшировать.

Кэширование на стороне сервера снизит нагрузку на ЦПУ. С помощью декоратора cache_page() организовать кэширование несложно. Для сброса кэша при изменении переведённых ресурсов следует предоставлять префикс, зависящий от номера версии, как это показано на следующем примере, или подключить представление к URL, содержащему номер версии.

from django.views.decorators.cache import cache_page
from django.views.i18n import JavaScriptCatalog

# The value returned by get_version() must change when translations change.
urlpatterns = [
    path('jsi18n/',
         cache_page(86400, key_prefix='js18n-%s' % get_version())(JavaScriptCatalog.as_view()),
         name='javascript-catalog'),
]

Кэширование на стороне клиента экономит пропускную способность и ускоряет отклик сайта. Если вы используете ETags (USE_ETAGS = True), у вас уже всё включено. С другой стороны, вы можете использовать условные декораторы. В следующем примере, кэш сбрасывается при перезапуске сервера приложений.

from django.utils import timezone
from django.views.decorators.http import last_modified
from django.views.i18n import JavaScriptCatalog

last_modified_date = timezone.now()

urlpatterns = [
    path('jsi18n/',
         last_modified(lambda req, **kw: last_modified_date)(JavaScriptCatalog.as_view()),
         name='javascript-catalog'),
]

You can even pre-generate the JavaScript catalog as part of your deployment procedure and serve it as a static file. This radical technique is implemented in django-statici18n.

Языковой префикс в шаблонах URL¶

i18n_patterns(*urls, prefix_default_language=True)¶

Данная функция может быть использована в корневой схеме URL и Django будет автоматически предварять все шаблоны URL, определённые через i18n_patterns(), кодом текущего языка. Пример шаблонов URL:

Установка для prefix_default_language значения False удаляет префикс из языка по умолчанию (LANGUAGE_CODE). Это может быть полезно при добавлении переводов на существующий сайт, чтобы текущие URL-адреса не менялись.

Перевод шаблонов URL

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

from about import views as about_views
from news import views as news_views
from sitemap.views import sitemap

urlpatterns = [
    path('sitemap.xml', sitemap, name='sitemap-xml'),
]

news_patterns = ([
    path('', news_views.index, name='index'),
    path('category/<slug:slug>/', news_views.category, name='category'),
    path('<slug:slug>/', news_views.details, name='detail'),
], 'news')

urlpatterns += i18n_patterns(
    path('about/', about_views.main, name='about'),
    path('news/', include(news_patterns, namespace='news')),
)

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

>>> from django.urls import reverse
>>> from django.utils.translation import activate

>>> activate('en')
>>> reverse('sitemap-xml')
'/sitemap.xml'
>>> reverse('news:index')
'/en/news/'

>>> activate('nl')
>>> reverse('news:detail', kwargs={'slug': 'news-slug'})
'/nl/news/news-slug/'

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

>>> activate('en')
>>> reverse('news:index')
'/news/'

>>> activate('nl')
>>> reverse('news:index')
'/nl/news/'

Перевод шаблонов URL¶

Шаблоны URL могут быть помечены как подлежащие переводу с помощью функции ugettext_lazy(). Например:

from django.conf.urls.i18n import i18n_patterns
from django.urls import include, path
from django.utils.translation import gettext_lazy as _

from about import views as about_views
from news import views as news_views
from sitemaps.views import sitemap

urlpatterns = [
    path('sitemap.xml', sitemap, name='sitemap-xml'),
]

news_patterns = ([
    path('', news_views.index, name='index'),
    path(_('category/<slug:slug>/'), news_views.category, name='category'),
    path('<slug:slug>/', news_views.details, name='detail'),
], 'news')

urlpatterns += i18n_patterns(
    path(_('about/'), about_views.main, name='about'),
    path(_('news/'), include(news_patterns, namespace='news')),
)

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

>>> from django.urls import reverse
>>> from django.utils.translation import activate

>>> activate('en')
>>> reverse('news:category', kwargs={'slug': 'recent'})
'/en/news/category/recent/'

>>> activate('nl')
>>> reverse('news:category', kwargs={'slug': 'recent'})
'/nl/nieuws/categorie/recent/'

Генерация URL в шаблонах¶

Если локализованные URL генерируются в шаблонах, они всегда используют текущий язык. Для получения URL для другого языка следует использовать шаблонный тег language. Этот тег включает выбранный язык внутри своего блока:

{% load i18n %}

{% get_available_languages as languages %}

{% translate "View this category in:" %}
{% for lang_code, lang_name in languages %}
    {% language lang_code %}
    <a href="{% url 'category' slug=category.slug %}">{{ lang_name }}</a>
    {% endlanguage %}
{% endfor %}

Шаблонный тег language принимает в качестве аргумента код языка.

Файлы сообщений¶

Первым шагом будет создание файла сообщений для нового языка. Файл сообщений является простым текстовым файлом, предоставляющим один язык, который содержит все переводимые строки и правила их представления на этом языке. Файлы сообщений имеют расширение .po.

Django поставляется с утилитой, django-admin makemessages, которая автоматизирует создание и обновление этих файлов.

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

django-admin makemessages -l de

… где de является названием локали для создаваемого файла сообщений. Например, это pt_BR для бразильского варианта португальского языка и de_AT для австрийского варианта немецкого языка или id для индонезийского.

Этот скрипт должен быть запущен из одного из двух мест:

• Корневой каталог вашего Django проекта (который содержит manage.py)

• Корневой каталог одного из приложений Django.

Скрипт просматривает дерево исходного кода вашего проекта или приложения и извлекает все строки, помеченные для перевода(смотрите Как Django находит переводы и убедитесь что LOCALE_PATHS настроен правильно). Затем скрипт создаёт (или обновляет) файл сообщений в каталоге locale/LANG/LC_MESSAGES. В случае примера с de, файл будет создан в locale/de/LC_MESSAGES/django.po.

При запуске makemessages из корневого каталога вашего проекта, извлечённые строки будут автоматически размещены в соответствующих файлах сообщений. Таким образом, строка, полученная из файла приложения, которое обладает каталогом locale, будет размещена в файле сообщений в этом каталоге. А строка, полученная из файла приложения, у которого нет каталога locale, будет размещена в файле сообщений в каталоге, который первым упомянут в LOCALE_PATHS или будет выведена ошибка если LOCALE_PATHS пуст.

By default django-admin makemessages examines every file that has the .html, .txt or .py file extension. If you want to override that default, use the --extension or -e option to specify the file extensions to examine:

django-admin makemessages -l de -e txt

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

django-admin makemessages -l de -e html,txt -e xml

# Extraction from Python source files
[python: **.py]

# Extraction from Jinja2 templates
[jinja2: **.jinja]
extensions = jinja2.ext.with_

Формат .po файлов несложен. Каждый .po файл содержит небольшой заголовок, например, контактную информацию ответственного. Но основная часть файла является списком сообщений – простое сопоставление переводимых строк с переводами на конкретный язык.

Например, если ваше Django приложение содержит переводимую строку "Welcome to my site.", так:

_("Welcome to my site.")

…тогда django-admin makemessages создаст .po файл, содержащий следующие данные – сообщение:

#: path/to/python/module.py:23
msgid "Welcome to my site."
msgstr ""

Краткое объяснение:

• msgid является переводимой строкой, которая определена в исходном коде. Не изменяйте её.

• msgstr является местом, где вы пишите свой перевод. Обычно оно пустое, именно вы отвечаете за его наполнение. Удостоверьтесь, что вы сохранили кавычки вокруг перевода.

• Для удобства, каждое сообщение включает, в виде закомментированной строки, размещенной выше строки msgid, имя файла и номер строки из которой была получена переводимая строка.

Длинные сообщения являются особым случаем. Так, первая строка сразу после msgstr (или msgid) всегда пустая. Затем идёт длинный перевод, разбитый на несколько строк. Эти строки будут собраны в одну. Не забывайте вставлять завершающие пробелы, иначе итоговая строка будет собрана без них!

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

django-admin makemessages -a

Компиляция файлов с сообщениями¶

После того, как вы создали файл с сообщениями, а также после каждого его обновления, вам следует скомпилировать этот файл, чтобы позволить gettext его использовать. Сделайте это с помощью утилиты django-admin compilemessages.

This tool runs over all available .po files and creates .mo files, which are binary files optimized for use by gettext. In the same directory from which you ran django-admin makemessages, run django-admin compilemessages like this:

django-admin compilemessages

Вот и всё. Ваш перевод готов к использованию.

Устранение неполадок: gettext() неправильно определяет python-format в строках со знаками процента.¶

В некоторых случаях, например, строки со знаком процента, за которым следует пробел и тип преобразования string (например, _("10% Interest")), gettext() неправильно помечает строки с python-format.

Если вы попытаетесь скомпилировать файлы сообщений с неправильно помеченными строками, вы получите сообщение об ошибке, например: «Количество спецификаций формата в «msgid» и «msgstr» не совпадает» или «msgstr» не является допустимой строкой формата Python, в отличие от «msgid».

Чтобы обойти эту проблему, вы можете избежать знаков процента, добавив второй знак процента:

from django.utils.translation import gettext as _
output = _("10%% interest")

Или вы можете использовать no-python-format, чтобы все знаки процента воспринимались как литералы:

# xgettext:no-python-format
output = _("10% interest")

Создание файлов сообщений из JavaScript кода¶

You create and update the message files the same way as the other Django message files – with the django-admin makemessages tool. The only difference is you need to explicitly specify what in gettext parlance is known as a domain in this case the djangojs domain, by providing a -d djangojs parameter, like this:

django-admin makemessages -d djangojs -l de

Этот пример создаёт или обновляет файл сообщений для JavaScript для немецкого языка. После обновления файлов сообщений просто выполните django-admin compilemessages, как вы это делаете для обычных файлов сообщений.

gettext на Windows¶

Эта информация нужна только тем, кому надо создавать/обновлять файлы сообщений или компилировать их (.po). Сам процесс перевода заключается в редактировании существующих файлов данного типа. Однако, если вам надо создавать свои собственные файлы сообщений, надо проверить или скомпилировать изменённый файл сообщений, тогда вам потребуются утилиты gettext:

You may also use gettext binaries you have obtained elsewhere, so long as the xgettext --version command works properly. Do not attempt to use Django translation utilities with a gettext package if the command xgettext --version entered at a Windows command prompt causes a popup window saying «xgettext.exe has generated errors and will be closed by Windows».

Настройка команды makemessages¶

Если вам требуется передать дополнительные параметры в xgettext, вам следует создать свою команду makemessages и переопределить её атрибут xgettext_options:

from django.core.management.commands import makemessages

class Command(makemessages.Command):
    xgettext_options = makemessages.Command.xgettext_options + ['--keyword=mytrans']

Если вам необходим больший контроль, вы также можете добавить новый аргумент в вашу реализацию команды makemessages:

from django.core.management.commands import makemessages

class Command(makemessages.Command):

    def add_arguments(self, parser):
        super().add_arguments(parser)
        parser.add_argument(
            '--extra-keyword',
            dest='xgettext_keywords',
            action='append',
        )

    def handle(self, *args, **options):
        xgettext_keywords = options.pop('xgettext_keywords')
        if xgettext_keywords:
            self.xgettext_options = (
                makemessages.Command.xgettext_options[:] +
                ['--keyword=%s' % kwd for kwd in xgettext_keywords]
            )
        super().handle(*args, **options)

Перенаправляющее представление set_language¶

set_language(request)¶

Для удобства Django поставляется с представлением django.views.i18n.set_language(), которое устанавливает язык для пользователя и перенаправляет его на указанный URL или, по умолчанию, обратно на ту же страницу.

Активируйте это представление, добавив следующую строку в конфигурацию URL:

path('i18n/', include('django.conf.urls.i18n')),

(Следует отметить, что данный пример привязывает представление к /i18n/setlang/.)

Представление должно вызываться через метод POST, в запросе должен быть установлен параметр language. При активированной поддержке сессий, представление сохраняет выбор пользователя в его сессии. Иначе выбранный язык сохраняется в cookie с именем по умолчанию django_language. (Имя может быть изменено через параметр конфигурации LANGUAGE_COOKIE_NAME.)

После установки выбора языка Django ищет параметр next в данных POST или GET. Если он найден и Django считает его безопасным URL-адресом (т. е. он не указывает на другой хост и использует безопасную схему), будет выполнено перенаправление на этот URL-адрес. В противном случае Django может вернуться к перенаправлению пользователя на URL-адрес из заголовка «Referer» или, если он не установлен, на «/», в зависимости от характера запроса:

• Если запрос принимает HTML-контент (на основе HTTP-заголовка Accept), всегда будет выполняться откат.

• Если запрос не принимает HTML, возврат будет выполнен только в том случае, если был установлен параметр next. В противном случае будет возвращен код состояния 204 (Нет контента).

Приведём пример HTML кода шаблона:

{% load i18n %}

<form action="{% url 'set_language' %}" method="post">{% csrf_token %}
    <input name="next" type="hidden" value="{{ redirect_to }}">
    <select name="language">
        {% get_current_language as LANGUAGE_CODE %}
        {% get_available_languages as LANGUAGES %}
        {% get_language_info_list for LANGUAGES as languages %}
        {% for language in languages %}
            <option value="{{ language.code }}"{% if language.code == LANGUAGE_CODE %} selected{% endif %}>
                {{ language.name_local }} ({{ language.code }})
            </option>
        {% endfor %}
    </select>
    <input type="submit" value="Go">
</form>

В этом примере Django ищет URL страницы, на которую будет перенаправлен пользователь, в контекстной переменной redirect_to.

Явное указание активного языка¶

Вам может потребоваться явно указать активный язык для текущей сессии. Например, возможно, что информация об языке, предпочитаемым пользователем, будет извлекаться из другой системы. Вы уже встречались с функцией django.utils.translation.activate(). Она влияет только на текущий поток. Для указания языка для всей сессии надо модифицировать LANGUAGE_SESSION_KEY:

from django.conf import settings
from django.http import HttpResponse
from django.utils import translation
user_language = 'fr'
translation.activate(user_language)
response = HttpResponse(...)
response.set_cookie(settings.LANGUAGE_COOKIE_NAME, user_language)

Вам обычно потребуется использовать оба подхода: вызывать django.utils.translation.activate() для изменения языка внутри потока и изменять сессию для влияния на последующие запросы.

Использование перевода вне представлений и шаблонов¶

Несмотря на то, что Django предоставляет богатый набор инструментов интернационализации представлений и шаблонов, она не ограничивает их использование в другом коде. Механизмы перевода Django могут быть использованы для перевода отдельных текстов на любой из языков, поддерживаемых Django (т.е. соответствующий каталог с переводами есть в наличии). Вы можете загрузить каталог переводов, активировать его и переводить текст на нужный язык, но не забудьте вернуться на оригинальный язык, так как активация каталога переводов выполняется на уровне потока и такое изменение будет влиять на код, работающий в том же потоке.

Например:

from django.utils import translation

def welcome_translated(language):
    cur_language = translation.get_language()
    try:
        translation.activate(language)
        text = translation.gettext('welcome')
    finally:
        translation.activate(cur_language)
    return text

Вызов этой функции с параметром „de“ вернёт "Willkommen", независимо от значения параметра конфигурации LANGUAGE_CODE и языка, установленного через мидлварь.

Вас могут заинтересовать функции django.utils.translation.get_language(), которая возвращает язык, используемый в текущем потоке, django.utils.translation.activate(), которая активирует каталог переводов для текущего потока, и django.utils.translation.check_for_language(), которая проверяет, поддерживается ли данный язык Django.

Для удобства вы можете также использовать контекстный менеджер django.utils.translation.override(), который сохраняет текущий язык при входе и восстанавливает его при выходе из блока. Код выше будет выглядеть следующим образом:

from django.utils import translation

def welcome_translated(language):
    with translation.override(language):
        return translation.gettext('welcome')

Кука для языка¶

Ряд настроек может быть использован для управления опциями куки языка:

• LANGUAGE_COOKIE_NAME

• LANGUAGE_COOKIE_AGE

• LANGUAGE_COOKIE_DOMAIN

• LANGUAGE_COOKIE_DOMAIN

• LANGUAGE_COOKIE_PATH

• LANGUAGE_COOKIE_NAME

• LANGUAGE_COOKIE_AGE

Особенности перевода Django¶

Механизм перевода Django использует стандартный модуль gettext, идущей в поставке Python. Если вы знакомы с gettext, вам может быть интересен подход Django к его использованию:

• Строковый домен может быть django или djangojs. Он используется для идентификации ресурсов множества приложений, которые хранятся в общей библиотеке(обычно /usr/share/locale/). Домен django используется для перевода текстовых ресурсов Python кода и шаблонов, загружается в общие каталоги перевода. Домен djangojs используется только для каталогов с текстовыми ресурсами для JavaScript, чтобы сделать их мелкими, насколько это возможно.

• Django не использует только xgettext. Она использует Python-обёртки для xgettext и msgfmt. Так сделано для удобства.

Как Django определяет языковую настройку¶

После подготовки своего перевода, или если вы желаете использовать перевод, поставляемый с Django, надо просто активировать перевод для своего приложения.

Django обладает очень гибкой моделью принятия решения о том, какой язык следует использовать: на уровне проекта, для отдельного пользователя или в обоих случаях.

Глобально язык определяется через параметр конфигурации LANGUAGE_CODE. Django использует указанный язык в качестве основного и обращается к нему, если больше никакой не найден мидлваром локализации(смотрите ниже).

Если вам просто нужно запустить проект на определенном языке, укажите его в LANGUAGE_CODE и убедитесь, что существует необходимый файл перевода и его скомпилированная версия (.mo).

Если вам надо позволить отдельным пользователям указывать предпочитаемый язык, используйте LocaleMiddleware. LocaleMiddleware обеспечивает выбор языка по данным из запроса. Эта мидлварь настраивает контент под каждого пользователя.

Чтобы использовать LocaleMiddleware, добавьте 'django.middleware.locale.LocaleMiddleware' в настройку MIDDLEWARE_CLASSES. Так как порядок middleware важен, используйте следующую инструкцию:

• Удостоверьтесь, что она указана одной из первых мидлварей.

• Она должна идти после SessionMiddleware, так как LocaleMiddleware использует сессию. И она должна идти до CommonMiddleware, так как CommonMiddleware нуждается в активном языке для определения запрошенного URL.

• Если вы используете CacheMiddleware, поместите LocaleMiddleware после неё.

Например, ваш MIDDLEWARE_CLASSES может выглядеть так:

MIDDLEWARE = [
   'django.contrib.sessions.middleware.SessionMiddleware',
   'django.middleware.locale.LocaleMiddleware',
   'django.middleware.common.CommonMiddleware',
]

(Для получения подробностей по мидлварям обратитесь к соответствующей документации.)

LocaleMiddleware пытается определить язык пользователя, используя следующий алгоритм:

• Сначала, проверяется наличие префикса в запрошенном URL. Эта проверка выполняется только если вы используете функцию i18n_patterns в корневом URLconf. Обратитесь к Интернационализация: в шаблонах URL для получения подробностей по языковым префиксам и интернационализации шаблонов URL.

• Если и с сессией не сложилось, то принимается за cookie.

  Имя cookie определяется параметром конфигурации LANGUAGE_COOKIE_NAME. (Название про умолчанию django_language.)

• Если опять не повезло, то заглядывает в HTTP заголовок Accept-Language. Этот заголовок отправляется браузером, чтобы указать серверу, какой язык вы предпочитаете, в порядке приоритета. Django проверяет наличие поддержки каждого языка из заголовка.

• Если совсем всё плохо, тогда используется значение параметра конфигурации LANGUAGE_CODE.

Заметим:

• Везде подразумевается, что значение языка указано в стандартном формате, в виде строки. Например, для бразильского варианта португальского языка это будет pt-br.

• Если базовый язык доступен, а вариант нет, то Django будет использовать базовый язык. Например, если пользователь указал de-at (австрийский вариант немецкого), но у Django есть только de, то именно он и будет использоваться.

• Выбор может производиться только из списка, определенного параметром конфигурации LANGUAGES. Если вам надо ограничить диапазон имеющихся языков (потому что ваше приложение не имеет столько переводов), укажите в LANGUAGES список поддерживаемых языков. Например:

  LANGUAGES = [
      ('de', _('German')),
      ('en', _('English')),
  ]
  

  Данный пример ограничивает число доступных для автоматического выбора языков немецким и английским языками (и любыми диалектами, например, de-ch или en-us).

• Если вы определяете параметр конфигурации LANGUAGES, как было показано выше, вы можете помечать имена языков как переводимые. Но следует использовать ugettext_lazy() вместо ugettext(), чтобы исключить циклический импорт.

  Приведёт пример файла настроек:

  from django.utils.translation import gettext_lazy as _
  
  LANGUAGES = [
      ('de', _('German')),
      ('en', _('English')),
  ]
  

После того, как LocaleMiddleware определяет предпочитаемый язык, она делает его доступным через request.LANGUAGE_CODE для каждого запроса HttpRequest. Вы можете спокойно его использовать в коде своих представлений. Вот простой пример:

from django.http import HttpResponse

def hello_world(request, count):
    if request.LANGUAGE_CODE == 'de-at':
        return HttpResponse("You prefer to read Austrian German.")
    else:
        return HttpResponse("You prefer to read another language.")

Следует отметить, что для статичного перевода (без мидлвари) язык надо брать из settings.LANGUAGE_CODE, а для динамичного перевода (с мидлварью) — из request.LANGUAGE_CODE.

Как Django находит переводы¶

Во время своей работы Django создаёт в памяти унифицированный каталог с переводами. Для этого он использует следующий алгоритм, учитывая порядок нахождения путей для загрузки файлов сообщений (.mo) и приоритет множества перевода для одного слова:

1. Каталоги, указанные в LOCALE_PATHS, имеют повышенный приоритет, список представлен по убыванию приоритета.

2. Затем происходит поиск каталога locale в каждом установленном приложении, указанном в INSTALLED_APPS. Тут тоже приоритет идёт по убыванию.

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

Имя каталога, содержащего перевод, должно быть названо в соответствии соглашению по наименованию локалей. Т.е. de, pt_BR, es_AR и так далее.

Таким образом, вы можете создавать приложения, которые содержат свои собственные переводы и вы можете изменять базовые переводы в вашем проекте. Или вы можете создать большой проект из нескольких приложений, объединив всё их переводы в единый ресурс. Выбор за вами.

Все репозитории с файлами сообщений имеют одинаковую структуру:

• Во всех указанных путях в параметре конфигурации LOCALE_PATHS происходит поиск <language>/LC_MESSAGES/django.(po|mo)

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

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

Для создания файлов сообщений надо использовать django-admin makemessages. Для компиляции файлов перевода надо использовать django-admin compilemessages, это приведёт к созданию бинарных .mo файлов, которые нужны для работы gettext.

Перечислив в параметре конфигурации LOCALE_PATHS список обрабатываемых каталогов, его можно передать компилятору: django-admin compilemessages --settings=path.to.settings.

Использование базового языка, отличного от английского¶

Django исходит из общего предположения, что исходные строки в переводимом проекте написаны на английском языке. Вы можете выбрать другой язык, но необходимо учитывать определенные ограничения:

• gettext предоставляет только две формы множественного числа для исходных сообщений, поэтому вам также необходимо будет предоставить перевод на базовый язык, чтобы включить все формы множественного числа, если правила множественного числа для базового языка отличаются от английского.

• Если активирован английский вариант и отсутствуют английские строки, резервным языком будет не LANGUAGE_CODE` проекта, а исходные строки. Например, англоязычный пользователь, посещающий сайт с параметром LANGUAGE_CODE, установленным на испанский, и исходными строками, написанными на русском языке, увидит русский текст, а не испанский.