<p>REST framework ships with translatable error messages. You can make these appear in your language enabling <ahref="https://docs.djangoproject.com/en/1.7/topics/i18n/translation">Django's standard translation mechanisms</a>.</p>
<p>Doing so will allow you to:</p>
<ul>
<li>Select a language other than English as the default, using the standard <code>LANGUAGE_CODE</code> Django setting.</li>
<li>Allow clients to choose a language themselves, using the <code>LocaleMiddleware</code> included with Django. A typical usage for API clients would be to include an <code>Accept-Language</code> request header.</li>
<p>You can change the default language by using the standard Django <code>LANGUAGE_CODE</code> setting:</p>
<pre><code>LANGUAGE_CODE = "es-es"
</code></pre>
<p>You can turn on per-request language requests by adding <code>LocalMiddleware</code> to your <code>MIDDLEWARE_CLASSES</code> setting:</p>
<pre><code>MIDDLEWARE_CLASSES = [
...
'django.middleware.locale.LocaleMiddleware'
]
</code></pre>
<p>When per-request internationalization is enabled, client requests will respect the <code>Accept-Language</code> header where possible. For example, let's make a request for an unsupported media type:</p>
<p><strong>Request</strong></p>
<pre><code>GET /api/users HTTP/1.1
Accept: application/xml
Accept-Language: es-es
Host: example.org
</code></pre>
<p><strong>Response</strong></p>
<pre><code>HTTP/1.0 406 NOT ACCEPTABLE
{"detail": "No se ha podido satisfacer la solicitud de cabecera de Accept."}
</code></pre>
<p>REST framework includes these built-in translations both for standard exception cases, and for serializer validation errors.</p>
<p>Note that the translations only apply to the error strings themselves. The format of error messages, and the keys of field names will remain the same. An example <code>400 Bad Request</code> response body might look like this:</p>
<pre><code>{"detail": {"username": ["Esse campo deve ser unico."]}}
</code></pre>
<p>If you want to use different string for parts of the response such as <code>detail</code> and <code>non_field_errors</code> then you can modify this behavior by using a <ahref="../../api-guide/exceptions#custom-exception-handling">custom exception handler</a>.</p>
<h4id="specifying-the-set-of-supported-languages">Specifying the set of supported languages.</h4>
<p>By default all available languages will be supported.</p>
<p>If you only wish to support a subset of the available languages, use Django's standard <code>LANGUAGES</code> setting:</p>
<pre><code>LANGUAGES = [
('de', _('German')),
('en', _('English')),
]
</code></pre>
<h2id="adding-new-translations">Adding new translations</h2>
<p>REST framework translations are managed online using <ahref="https://www.transifex.com/projects/p/django-rest-framework/">Transifex</a>. You can use the Transifex service to add new translation languages. The maintenance team will then ensure that these translation strings are included in the REST framework package.</p>
<p>Sometimes you may need to add translation strings to your project locally. You may need to do this if:</p>
<h4id="translating-a-new-language-locally">Translating a new language locally</h4>
<p>This guide assumes you are already familiar with how to translate a Django app. If you're not, start by reading <ahref="https://docs.djangoproject.com/en/1.7/topics/i18n/translation">Django's translation docs</a>.</p>
<p>If you're translating a new language you'll need to translate the existing REST framework error messages:</p>
<ol>
<li>
<p>Make a new folder where you want to store the internationalization resources. Add this path to your <ahref="https://docs.djangoproject.com/en/1.7/ref/settings/#std:setting-LOCALE_PATHS"><code>LOCALE_PATHS</code></a> setting.</p>
</li>
<li>
<p>Now create a subfolder for the language you want to translate. The folder should be named using <ahref="https://docs.djangoproject.com/en/1.7/topics/i18n/#term-locale-name">locale name</a> notation. For example: <code>de</code>, <code>pt_BR</code>, <code>es_AR</code>.</p>
</li>
<li>
<p>Now copy the <ahref="https://raw.githubusercontent.com/tomchristie/django-rest-framework/master/rest_framework/locale/en_US/LC_MESSAGES/django.po">base translations file</a> from the REST framework source code into your translations folder.</p>
</li>
<li>
<p>Edit the <code>django.po</code> file you've just copied, translating all the error messages.</p>
</li>
<li>
<p>Run <code>manage.py compilemessages -l pt_BR</code> to make the translations
available for Django to use. You should see a message like <code>processing file django.po in <...>/locale/pt_BR/LC_MESSAGES</code>.</p>
</li>
<li>
<p>Restart your development server to see the changes take effect.</p>
</li>
</ol>
<p>If you're only translating custom error messages that exist inside your project codebase you don't need to copy the REST framework source <code>django.po</code> file into a <code>LOCALE_PATHS</code> folder, and can instead simply run Django's standard <code>makemessages</code> process.</p>
<h2id="how-the-language-is-determined">How the language is determined</h2>
<p>If you want to allow per-request language preferences you'll need to include <code>django.middleware.locale.LocaleMiddleware</code> in your <code>MIDDLEWARE_CLASSES</code> setting.</p>
<p>You can find more information on how the language preference is determined in the <ahref="https://docs.djangoproject.com/en/1.7/topics/i18n/translation/#how-django-discovers-language-preference">Django documentation</a>. For reference, the method is:</p>
<ol>
<li>First, it looks for the language prefix in the requested URL.</li>
<li>Failing that, it looks for the <code>LANGUAGE_SESSION_KEY</code> key in the current user’s session.</li>
<li>Failing that, it looks for a cookie.</li>
<li>Failing that, it looks at the <code>Accept-Language</code> HTTP header.</li>
<li>Failing that, it uses the global <code>LANGUAGE_CODE</code> setting.</li>
</ol>
<p>For API clients the most appropriate of these will typically be to use the <code>Accept-Language</code> header; Sessions and cookies will not be available unless using session authentication, and generally better practice to prefer an <code>Accept-Language</code> header for API clients rather than using language URL prefixes.</p>
