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

Поддержка интернационализации не является необязательной. Она должна быть основной функцией.

‒ Jannis Leidel, speaking at Django Under the Hood, 2015.

Фреймворк REST поставляется с переводимыми сообщениями об ошибках. Вы можете сделать так, чтобы они отображались на вашем языке, включив Django’s standard translation mechanisms.

Это позволит вам:

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

  • Позвольте клиентам самим выбирать язык, используя LocaleMiddleware, включенный в Django. Типичным использованием для клиентов API является включение заголовка запроса Accept-Language.

Включение интернационализированных API

Вы можете изменить язык по умолчанию с помощью стандартной настройки Django LANGUAGE_CODE:

LANGUAGE_CODE = "es-es"

Вы можете включить запрос языка на каждый запрос, добавив LocalMiddleware к настройке MIDDLEWARE_CLASSES:

MIDDLEWARE_CLASSES = [
    ...
    'django.middleware.locale.LocaleMiddleware'
]

Когда интернационализация по каждому запросу включена, клиентские запросы будут соблюдать заголовок Accept-Language, где это возможно. Например, давайте сделаем запрос на неподдерживаемый тип медиа:

Запрос

GET /api/users HTTP/1.1
Accept: application/xml
Accept-Language: es-es
Host: example.org

Ответ

HTTP/1.0 406 NOT ACCEPTABLE

{"detail": "No se ha podido satisfacer la solicitud de cabecera de Accept."}

REST framework включает эти встроенные переводы как для стандартных случаев исключений, так и для ошибок валидации сериализатора.

Обратите внимание, что переводы относятся только к самим строкам ошибок. Формат сообщений об ошибках и ключи имен полей останутся неизменными. Пример тела ответа 400 Bad Request может выглядеть следующим образом:

{"detail": {"username": ["Esse campo deve ser único."]}}

Если вы хотите использовать разные строки для частей ответа, таких как detail и non_field_errors, вы можете изменить это поведение, используя custom exception handler.

Указание набора поддерживаемых языков.

По умолчанию поддерживаются все доступные языки.

Если вы хотите поддерживать только подмножество доступных языков, используйте стандартную настройку Django LANGUAGES:

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

Добавление новых переводов

Управление переводами фреймворка REST осуществляется в режиме онлайн с помощью Transifex. Вы можете использовать сервис Transifex для добавления новых языков перевода. Команда технического обслуживания обеспечит включение этих строк перевода в пакет фреймворка REST.

Иногда вам может понадобиться добавить строки перевода в проект локально. Это может понадобиться, если:

  • Вы хотите использовать REST Framework на языке, который еще не переведен на Transifex.

  • Ваш проект включает пользовательские сообщения об ошибках, которые не входят в строки перевода REST framework по умолчанию.

Перевод нового языка на местный язык

Это руководство предполагает, что вы уже знакомы с тем, как переводить приложения Django. Если это не так, начните с чтения Django’s translation docs.

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

  1. Создайте новую папку, в которой вы хотите хранить ресурсы интернационализации. Добавьте этот путь к настройке ** ``LOCALE_PATHS:doc:` <https://docs.djangoproject.com/en/stable/ref/settings/#std:setting-LOCALE_PATHS>`.

  2. Теперь создайте вложенную папку для языка, который вы хотите перевести. Папка должна быть названа с использованием нотации locale name. Например: de , pt_BR , es_AR.

  3. Теперь скопируйте base translations file из исходного кода фреймворка REST в папку translations.

  4. Отредактируйте файл django.po, который вы только что скопировали, переведя все сообщения об ошибках.

  5. Выполните manage.py compilemessages -l pt_BR, чтобы сделать переводы доступными для использования Django. Вы должны увидеть сообщение типа processing file django.po in <...>/locale/pt_BR/LC_MESSAGES.

  6. Перезапустите сервер разработки, чтобы увидеть, как изменения вступают в силу.

Если вы переводите только пользовательские сообщения об ошибках, которые существуют в кодовой базе вашего проекта, вам не нужно копировать исходный файл django.po фреймворка REST в папку LOCALE_PATHS, а можно просто запустить стандартный процесс makemessages Django.

Как определяется язык

Если вы хотите разрешить языковые предпочтения для каждого запроса, вам нужно включить django.middleware.locale.LocaleMiddleware в настройку MIDDLEWARE_CLASSES.

Более подробную информацию о том, как определяется предпочтение языка, можно найти в разделе Django documentation. Для справки, метод следующий:

  1. Во-первых, он ищет префикс языка в запрашиваемом URL.

  2. В противном случае, он ищет ключ LANGUAGE_SESSION_KEY в сессии текущего пользователя.

  3. Если это не удается, он ищет печенье.

  4. В противном случае он просматривает HTTP-заголовок Accept-Language.

  5. В противном случае используется глобальная настройка LANGUAGE_CODE.

Для клиентов API наиболее подходящим из них обычно является использование заголовка Accept-Language; сеансы и куки будут недоступны, если не используется аутентификация сеанса, и вообще лучше предпочесть заголовок Accept-Language для клиентов API, а не использовать языковые префиксы URL.

Вернуться на верх