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

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

• Яннис Лейдель, выступая на Django Under the Hood, 2015.

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

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

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

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

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

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

LANGUAGE_CODE = "es-es"

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

MIDDLEWARE = [
    ...
    '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."}

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

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

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

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

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

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

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

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

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

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

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

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

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

Локальный перевод на новый язык

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

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

1. Создайте новую папку, в которой вы хотите хранить ресурсы интернационализации. Добавьте этот путь в настройку LOCALE_PATHS.
2. Теперь создайте подпапку для языка, на который вы хотите перевести. Папка должна быть названа с использованием нотации имя локали. Например: de, pt_BR, es_AR.
3. Теперь скопируйте файл base translations file из исходного кода DRF в папку translations.
4. Отредактируйте только что скопированный файл django.po, переведя все сообщения об ошибках.

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

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

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

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

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

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

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

2. Если это не удается, он ищет ключ LANGUAGE_SESSION_KEY в текущей сессии пользователя.

3. Если это не удается, выполняется поиск cookie.

4. Если это не удается, просматривается HTTP-заголовок Accept-Language.

5. Если это не удается, используется глобальная настройка LANGUAGE_CODE.

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