Поддержка интернационализации не является необязательной. Она должна быть основной функцией.
DRF поставляется с переводимыми сообщениями об ошибках. Вы можете сделать так, чтобы они отображались на вашем языке, используя стандартные механизмы перевода Django.
Это позволит вам:
-
Выбрать язык по умолчанию, отличный от английского, используя стандартную настройку Django
LANGUAGE_CODE
. -
Позволить клиентам самим выбирать язык, используя
LocaleMiddleware
, включенный в Django. Типичное использование для клиентов API - включение заголовка запросаAccept-Language
.
Вы можете изменить язык по умолчанию с помощью стандартной настройки 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:
- Создайте новую папку, в которой вы хотите хранить ресурсы интернационализации. Добавьте этот путь в настройку
LOCALE_PATHS
. - Теперь создайте подпапку для языка, на который вы хотите перевести. Папка должна быть названа с использованием нотации имя локали. Например:
de
,pt_BR
,es_AR
. - Теперь скопируйте файл base translations file из исходного кода DRF в папку translations.
- Отредактируйте только что скопированный файл
django.po
, переведя все сообщения об ошибках. - Запустите
manage.py compilemessages -l pt_BR
, чтобы сделать переводы доступными для использования Django. Вы должны увидеть сообщение типаprocessing file django.po in <...>/locale/pt_BR/LC_MESSAGES
. - Перезапустите ваш сервер разработки, чтобы увидеть, что изменения вступили в силу.
Если вы переводите только пользовательские сообщения об ошибках, которые существуют в кодовой базе вашего проекта, вам не нужно копировать исходный файл DRF django.po
в папку LOCALE_PATHS
, а можно просто запустить стандартный процесс Django makemessages
.
Если вы хотите разрешить языковые предпочтения для каждого запроса, вам нужно включить django.middleware.locale.LocaleMiddleware
в настройку MIDDLEWARE
.
Более подробную информацию о том, как определяется предпочтение языка, вы можете найти в документации Django. Для справки, метод следующий:
- Во-первых, он ищет префикс языка в запрашиваемом URL.
- Если это не удается, он ищет ключ
LANGUAGE_SESSION_KEY
в текущей сессии пользователя. - Если это не удается, выполняется поиск cookie.
- Если это не удается, просматривается HTTP-заголовок
Accept-Language
. - Если это не удается, используется глобальная настройка
LANGUAGE_CODE
.
Для клиентов API наиболее подходящим из них обычно является использование заголовка Accept-Language
; сеансы и cookies будут недоступны, если не используется аутентификация сеанса, и вообще лучше предпочесть заголовок Accept-Language
для клиентов API, а не использовать языковые префиксы URL.