diff options
| -rw-r--r-- | docs/index.md | 1 | ||||
| -rw-r--r-- | docs/topics/internationalisation.md | 95 | ||||
| -rw-r--r-- | docs/topics/internationalization.md | 72 | ||||
| -rw-r--r-- | mkdocs.yml | 1 |
4 files changed, 74 insertions, 95 deletions
diff --git a/docs/index.md b/docs/index.md index 544204c6..16376985 100644 --- a/docs/index.md +++ b/docs/index.md @@ -305,6 +305,7 @@ OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. [settings]: api-guide/settings.md [documenting-your-api]: topics/documenting-your-api.md +[internationalization]: topics/documenting-your-api.md [ajax-csrf-cors]: topics/ajax-csrf-cors.md [browser-enhancements]: topics/browser-enhancements.md [browsableapi]: topics/browsable-api.md diff --git a/docs/topics/internationalisation.md b/docs/topics/internationalisation.md deleted file mode 100644 index 2a476c86..00000000 --- a/docs/topics/internationalisation.md +++ /dev/null @@ -1,95 +0,0 @@ -# Internationalisation -REST framework ships with translatable error messages. You can make these appear in your language enabling [Django's standard translation mechanisms][django-translation] and by translating the messages into your language. - -## How to translate REST Framework errors - -REST framework translations are managed online using [Transifex.com][transifex]. To get started, checkout the guide in the [CONTRIBUTING.md guide][contributing]. - -Sometimes you may want to use REST Framework in a language which has not been translated yet on Transifex. If that is the case then you should translate the error messages locally. - -#### How to translate REST Framework error messages locally: - -This guide assumes you are already familiar with how to translate a Django app. If you're not, start by reading [Django's translation docs][django-translation]. - -1. Make a new folder where you want to store the translated errors. Add this -path to your [`LOCALE_PATHS`][django-locale-paths] setting. - - --- - - **Note:** For the rest of -this document we will assume the path you created was -`/home/www/project/conf/locale/`, and that you have updated your `settings.py` to include the setting: - - ``` - LOCALE_PATHS = ( - '/home/www/project/conf/locale/', - ) - ``` - - --- - -2. Now create a subfolder for the language you want to translate. The folder should be named using [locale -name][django-locale-name] notation. E.g. `de`, `pt_BR`, `es_AR`, etc. - - ``` - mkdir /home/www/project/conf/locale/pt_BR/LC_MESSAGES - ``` - -3. Now copy the base translations file from the REST framework source code -into your translations folder - - ``` - cp /home/user/.virtualenvs/myproject/lib/python2.7/site-packages/rest_framework/locale/en_US/LC_MESSAGES/django.po - /home/www/project/conf/locale/pt_BR/LC_MESSAGES - ``` - - This should create the file - `/home/www/project/conf/locale/pt_BR/LC_MESSAGES/django.po` - - --- - - **Note:** To find out where `rest_framework` is installed, run - - ``` - python -c "from distutils.sysconfig import get_python_lib; print(get_python_lib())" - ``` - - --- - - -4. Edit `/home/www/project/conf/locale/pt_BR/LC_MESSAGES/django.po` and -translate all the error messages. - -5. Run `manage.py compilemessages -l pt_BR` to make the translations -available for Django to use. You should see a message - - ``` - processing file django.po in /home/www/project/conf/locale/pt_BR/LC_MESSAGES - ``` - -6. Restart your server. - - - -## How Django chooses which language to use -REST framework will use the same preferences to select which language to -display as Django does. You can find more info in the [Django docs on discovering language preferences][django-language-preference]. For reference, these are - -1. First, it looks for the language prefix in the requested URL -2. Failing that, it looks for the `LANGUAGE_SESSION_KEY` key in the current user’s session. -3. Failing that, it looks for a cookie -4. Failing that, it looks at the `Accept-Language` HTTP header. -5. Failing that, it uses the global `LANGUAGE_CODE` setting. - ---- - -**Note:** You'll need to include the `django.middleware.locale.LocaleMiddleware` to enable any of the per-request language preferences. - ---- - - -[django-translation]: https://docs.djangoproject.com/en/1.7/topics/i18n/translation -[django-language-preference]: https://docs.djangoproject.com/en/1.7/topics/i18n/translation/#how-django-discovers-language-preference -[django-locale-paths]: https://docs.djangoproject.com/en/1.7/ref/settings/#std:setting-LOCALE_PATHS -[django-locale-name]: https://docs.djangoproject.com/en/1.7/topics/i18n/#term-locale-name -[contributing]: ../../CONTRIBUTING.md diff --git a/docs/topics/internationalization.md b/docs/topics/internationalization.md new file mode 100644 index 00000000..fdde6c43 --- /dev/null +++ b/docs/topics/internationalization.md @@ -0,0 +1,72 @@ +# Internationalization + +> Supporting internationalization is not optional. It must be a core feature. +> +> — [Jannis Leidel, speaking at Django Under the Hood, 2015][cite]. + +REST framework ships with translatable error messages. You can make these appear in your language enabling [Django's standard translation mechanisms][django-translation]. + +Doing so will allow you to: + +* Select a language other than English as the default, using the standard `LANGUAGE_CODE` Django setting. +* Allow clients to choose a language themselves, using the `LocaleMiddleware` included with Django. A typical usage for API clients would be to include an `Accept-Language` request header. + +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 `400 Bad Request` response body might look like this: + + {"detail": {"username": ["Esse campo deve ser unico."]}} + +If you want to use different string for parts of the response such as `detail` and `non_field_errors` then you can modify this behavior by using a [custom exception handler][custom-exception-handler]. + +## Adding new translations + +REST framework translations are managed online using [Transifex][transifex-project]. 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. + +Sometimes you may need to add translation strings to your project locally. You may need to do this if: + +* You want to use REST Framework in a language which has not been translated yet on Transifex. +* Your project includes custom error messages, which are not part of REST framework's default translation strings. + +#### Translating a new language locally + +This guide assumes you are already familiar with how to translate a Django app. If you're not, start by reading [Django's translation docs][django-translation]. + +If you're translating a new language you'll need to translate the existing REST framework error messages: + +1. Make a new folder where you want to store the internationalization resources. Add this path to your [`LOCALE_PATHS`][django-locale-paths] setting. + +2. Now create a subfolder for the language you want to translate. The folder should be named using [locale name][django-locale-name] notation. For example: `de`, `pt_BR`, `es_AR`. + +3. Now copy the [base translations file][django-po-source] from the REST framework source code into your translations folder. + +4. Edit the `django.po` file you've just copied, translating all the error messages. + +5. Run `manage.py compilemessages -l pt_BR` to make the translations +available for Django to use. You should see a message like `processing file django.po in <...>/locale/pt_BR/LC_MESSAGES`. + +6. Restart your development server to see the changes take effect. + +If you're only translating custom error messages that exist inside your project codebase you don't need to copy the REST framework source `django.po` file into a `LOCALE_PATHS` folder, and can instead simply run Django's standard `makemessages` process. + +## How the language is determined + +If you want to allow per-request language preferences you'll need to include `django.middleware.locale.LocaleMiddleware` in your `MIDDLEWARE_CLASSES` setting. + +You can find more information on how the language preference is determined in the [Django documentation][django-language-preference]. For reference, the method is: + +1. First, it looks for the language prefix in the requested URL. +2. Failing that, it looks for the `LANGUAGE_SESSION_KEY` key in the current user’s session. +3. Failing that, it looks for a cookie. +4. Failing that, it looks at the `Accept-Language` HTTP header. +5. Failing that, it uses the global `LANGUAGE_CODE` setting. + +For API clients the most appropriate of these will typically be to use the `Accept-Language` header; Sessions and cookies will not be available unless using session authentication, and generally better practice to prefer an `Accept-Language` header for API clients rather than using language URL prefixes. + +[cite]: http://youtu.be/Wa0VfS2q94Y +[django-translation]: https://docs.djangoproject.com/en/1.7/topics/i18n/translation +[custom-exception-handler]: ../api-guide/exceptions.md#custom-exception-handling
+[transifex-project]: https://www.transifex.com/projects/p/django-rest-framework/ +[django-po-source]: https://raw.githubusercontent.com/tomchristie/django-rest-framework/master/rest_framework/locale/en_US/LC_MESSAGES/django.po +[django-language-preference]: https://docs.djangoproject.com/en/1.7/topics/i18n/translation/#how-django-discovers-language-preference +[django-locale-paths]: https://docs.djangoproject.com/en/1.7/ref/settings/#std:setting-LOCALE_PATHS +[django-locale-name]: https://docs.djangoproject.com/en/1.7/topics/i18n/#term-locale-name +[contributing]: ../../CONTRIBUTING.md @@ -42,6 +42,7 @@ pages: - ['api-guide/testing.md', 'API Guide', 'Testing'] - ['api-guide/settings.md', 'API Guide', 'Settings'] - ['topics/documenting-your-api.md', 'Topics', 'Documenting your API'] + - ['topics/internationalization.md', 'Topics', 'Internationalization'] - ['topics/ajax-csrf-cors.md', 'Topics', 'AJAX, CSRF & CORS'] - ['topics/browser-enhancements.md', 'Topics',] - ['topics/browsable-api.md', 'Topics', 'The Browsable API'] |