Django: краткое руководство по интернационализации

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

Часть того, о чём тут пойдёт речь, применимо к локализации любых Python-проектов. Разобрав основы, мы поговорим об ускорении работ по интернационализации. В частности — о применении платформы Phrase.



Предполагается, что у читателя этого материала имеется работающее Django-приложение, и то, что у него установлен пакет gettext (установить его можно, например, командой pip install gettext). Если вы раньше не пользовались Django (популярным веб-фреймворком, основанным на Python), то вам, возможно, будет полезно сначала взглянуть на это официальное руководство, а потом вернуться к данной статье.

Базовые настройки рабочей среды

Итак, представим, что у вас имеется Django-проект mysite, и приложение, называемое polls. Структура проекта должна выглядеть примерно так:

/
    manage.py
    mysite/
        __init__.py
        settings.py
        urls.py
        wsgi.py
    polls/
        migrations/
        __init__.py
        admin.py
        models.py
        tests.py
        views.py

Первый шаг нашей работы заключается в проверке того, активирована ли опция интернационализации в конфигурации проекта. Для того чтобы это сделать, нужно внести следующие изменения в mysite/settings.py:

# mysite/settings.py
LANGUAGE_CODE = 'en-us'
TIME_ZONE = 'UTC'
USE_I18N = True
USE_L10N = True
USE_TZ = True

Интернационализация шаблонов

Теперь нужно пометить все строки, которые должны быть переведены на разные языки. Представим, что у вас имеется следующий файл шаблона polls/templates/polls/index.html:

<!-- polls/templates/polls/index.html -->
<h1>Welcome to our site!</h1>
<p>Here you find polls.</p>

Этот файл нужно переработать следующим образом:

<!-- polls/templates/polls/index.html -->
{% load i18n %}
<h1>{% trans 'WelcomeHeading' %}</h1>
<p>{% trans 'WelcomeMessage' %}</p>

Здесь мы импортировали пакет для локализации и заменили весь текст на конструкции вида trans 'SomeTranslationKeyName'. Кроме того, в качестве альтернативы такому подходу, можно воспользоваться текстами перевода, применяемыми по умолчанию, в виде ключей перевода. При таком подходе у вас всегда будет хороший текст, задаваемый по умолчанию, в том случае, если для некоего ключа не будет доступного перевода.

Интернационализация в Python-коде

Если требуется локализовать строки, находящиеся внутри Python-кода (например, в файле polls/views.py), нужно импортировать в файл функцию ugettext. Ей, что вполне нормально, можно назначить псевдоним _. Вот как будет выглядеть локализованный вариант простой функции из файла views.py:

# polls/views.py
from django.http import HttpResponse
from django.utils.translation import ugettext as _
def index(request):
    output = _('StatusMsg')
    return HttpResponse(output)

Создание файлов перевода

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

django-admin makemessage -l de

Здесь de можно заменить на код локали для языка, который планируется добавить в приложение. В нашем примере выполнение этой команды приведёт к созданию gettext-файла polls/locale/de/LC_MESSAGES/django.po следующего содержания:

# polls/locale/de/LC_MESSAGES/django.po
...
#: templates/polls/index.html:3
msgid "WelcomeHeading"
msgstr ""
#: templates/polls/index.html:4
msgid "WelcomeMessage"
msgstr ""

Теперь в этот файл можно ввести переводы строк:

# polls/locale/de/LC_MESSAGES/django.po
...
#: templates/polls/index.html:3
msgid "WelcomeHeading"
msgstr "Willkommen auf unserer Seite!"
#: templates/polls/index.html:4
msgid "WelcomeMessage"
msgstr "Hier findet Ihr Umfragen."

Когда перевод будет готов — нужно всё скомпилировать, выполнив следующую команду:

$ django-admin compilemessages

Выполнять эту команду нужно, опять же, в директории polls.

Для того чтобы быстро проверить работоспособность перевода, нужно поменять код языка в файле mysite/settings.py. Например — так:

# mysite/settings.py
LANGUAGE_CODE = 'de'

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

Ускорение процесса локализации приложений с использованием Phrase

Если вы используете Phrase для организации работ по локализации приложений, то вам, на самом деле, не нужно вручную создавать и редактировать *.po-файлы! Вам достаточно создать и перевести ключи WelcomeHeading и WelcomeMessage в Phrase и использовать функцию экспорта для загрузки *.po-файлов.

Если у вас установлено наше средство командной строки Phrase Client, то ваша работа упрощается ещё сильнее. Достаточно создать в корневой директории проекта конфигурационный файл .phraseapp.yml со следующим содержимым:

# .phraseapp.yml
phraseapp:
  access_token: <your access token>
  project_id: <your project's id on PhraseApp>
  file_format: po
  pull:
    targets:
        file: "polls/locale/<locale_code>/LC_MESSAGES/django.po

Затем надо выполнить в корневой директории проекта следующую команду:

phraseapp pull && django-admin compilemessages

Благодаря этому будут обновлены все переводы проекта.

Кроме того, ещё больше упростить работу может использование в вашем Django-проекте нашего редактора In-Context Editor. Для этого достаточно установить django-phrase с помощью pip:

pip install django-phrase

Затем достаточно отредактировать шаблоны, при работе с которыми вы планируете использовать In-Context-Editor:

<!-- polls/templates/polls/index.html -->
{% load i18n %}
{% load phrase_i18n %}
{% phrase_javascript %}
<h1>{% trans 'WelcomeHeading' %}</h1>
<p>{% trans 'WelcomeMessage' %}</p>

Обратите внимание на то, что загрузка phrase_i18n должна выполняться после i18n.

И наконец, в конфигурационный файл нужно добавить следующее:

# mysite/settings.py
PHRASE_ENABLED = True
PHRASE_PROJECT_ID = 'YOUR_PROJECT_ID'
PHRASE_PREFIX = '{{__'
PHRASE_SUFFIX = '__}}'

После этого всё будет готово к работе.

Выбор локалей

Обычно разработчики приложений устанавливают локали, основываясь на параметрах браузера пользователя. Для того чтобы это сделать, нужно привести файл mysite/settings.py к следующему виду:

# mysite/settings.py
from django.utils.translation import ugettext_lazy as _
...
MIDDLEWARE_CLASSES = (
    ...,
    'django.middleware.locale.LocaleMiddleware',
    ...,
)
...
LANGUAGE_CODE = 'en-us'
LANGUAGES = (
    ('en-us', _('English')),
    ('de', _('German')),
)

При таком подходе, если у пользователя будет локаль German, он увидит вариант перевода de. В противном случае в качестве перевода по умолчанию будет использоваться en-us. Проверить правильность работы этого механизма можно с помощью curl:

curl http://localhost:8000/polls -H "Accept-Language: de"

Эта команда должна вернуть примерно следующее:

<h1>Willkommen auf unserer Seite!</h1>
<p>Hier findet Ihr Umfragen.</p>

Итоги

В этом материале мы рассмотрели основы интернационализации Django-приложений. Здесь же мы рассказали о сервисе Phrase, который способен ускорить и упростить работу. Надеемся, то, о чём вы узнали, вам пригодится.

Уважаемые читатели! Как вы подходите к интернационализации ваших Python-проектов?