Internationalization docs

1 files changed, 72 insertions, 5 deletions

diff --git a/docs/topics/3.1-announcement.md b/docs/topics/3.1-announcement.md
index d0975f5b..080ef1d8 100644
--- a/docs/topics/3.1-announcement.md
+++ b/docs/topics/3.1-announcement.md
@@ -10,7 +10,7 @@ The pagination API has been improved, making it both easier to use, and more pow
 
 Until now, there has only been a single built-in pagination style in REST framework. We now have page, limit/offset and cursor based schemes included by default.
 
-The cursor based pagination scheme is particularly smart, and is a better approach for clients iterating through large or frequently changing result sets. The scheme supports paging against non-unique indexes, by using both cursor and limit/offset information. Credit to David Cramer for [this blog post](http://cramer.io/2011/03/08/building-cursors-for-the-disqus-api/) on the subject.
+The cursor based pagination scheme is particularly smart, and is a better approach for clients iterating through large or frequently changing result sets. The scheme supports paging against non-unique indexes, by using both cursor and limit/offset information. It also allows for both forward and reverse cursor pagination. Much credit goes to David Cramer for [this blog post](http://cramer.io/2011/03/08/building-cursors-for-the-disqus-api/) on the subject.
 
 #### Pagination controls in the browsable API.
 
@@ -34,15 +34,74 @@ We've made it easier to build versioned APIs. Built-in schemes for versioning in
 
 When using a URL based scheme, hyperlinked serializers will resolve relationships to the same API version as used on the incoming request.
 
-**TODO**: Example.
+For example, when using `NamespaceVersioning`, and the following hyperlinked serializer:
+
+    class AccountsSerializer(serializer.HyperlinkedModelSerializer):
+        class Meta:
+            model = Accounts
+            fields = ('account_name', 'users')
+
+The output representation would match the version used on the incoming request. Like so:
+
+    GET http://example.org/v2/accounts/10  # Version 'v2'
+
+    {
+        "account_name": "europa",
+        "users": [
+            "http://example.org/v2/users/12",  # Version 'v2'
+            "http://example.org/v2/users/54",
+            "http://example.org/v2/users/87"
+        ]
+    }
 
 ## Internationalization
 
 REST framework now includes a built-in set of translations, and supports internationalized error responses. This allows you to either change the default language, or to allow clients to specify the language via the `Accept-Language` header.
 
-**TODO**: Example.
+You can change the default language by using the standard Django `LANGUAGE_CODE` setting:
+
+    LANGUAGE_CODE = "es-es"
+
+You can turn on per-request language requests by adding `LocalMiddleware` to your `MIDDLEWARE_CLASSES` setting:
+
+    MIDDLEWARE_CLASSES = [
+        ...
+        'django.middleware.locale.LocaleMiddleware'
+    ]
+
+When per-request internationalization is enabled, client requests will respect the `Accept-Language` header where possible. For example, let's make a request for an unsupported media type:
+
+**Request**
+
+    GET /api/users HTTP/1.1
+    Accept: application/xml
+    Accept-Language: es-es
+    Host: example.org
+
+**Response**
 
-**TODO**: Credit.
+    HTTP/1.0 406 NOT ACCEPTABLE
+
+    {
+        "detail": "No se ha podido satisfacer la solicitud de cabecera de Accept."
+    }
+
+Note that the structure of the error responses is still the same. We still have a `details` key in the response. If needed you can modify this behavior too, by using a [custom exception handler][custom-exception-handler].
+
+We include built-in translations both for standard exception cases, and for serializer validation errors.
+
+The full list of supported languages can be found on our [Transifex project page](https://www.transifex.com/projects/p/django-rest-framework/).
+
+If you only wish to support a subset of the supported languages, use Django's standard `LANGUAGES` setting:
+
+    LANGUAGES = [
+        ('de', _('German')),
+        ('en', _('English')),
+    ]
+
+For more details, see the [internationalization documentation](internationalization.md).
+
+Many thanks to [Craig Blaszczyk](https://github.com/jakul) for helping push this through.
 
 ## New field types
 
@@ -50,6 +109,10 @@ Django 1.8's new `ArrayField`, `HStoreField` and `UUIDField` are now all fully s
 
 This work also means that we now have both `serializers.DictField()`, and `serializers.ListField()` types, allowing you to express and validate a wider set of representations.
 
+If you're building a new 1.8 project, then you should probably consider using `UUIDField` as the primary keys for all your models. This style will work automatically with hyperlinked serializers, returning URLs in the following style:
+
+    http://example.org/api/purchases/9b1a433f-e90d-4948-848b-300fdc26365d
+
 ## ModelSerializer API
 
 The serializer redesign in 3.0 did not include any public API for modifying how ModelSerializer classes automatically generate a set of fields from a given mode class. We've now re-introduced an API for this, allowing you to create new ModelSerializer base classes that behave differently, such as using a different default style for relationships.
@@ -85,6 +148,8 @@ And modify your settings, like so:
         ]
     }
 
+Thanks go to the latest member of our maintenance team, [José Padilla](https://github.com/jpadilla/), for handling this work and taking on ownership of these packages.
+
 # What's next?
 
 The next focus will be on HTML renderings of API output and will include:
@@ -93,4 +158,6 @@ The next focus will be on HTML renderings of API output and will include:
 * Filtering controls built-in to the browsable API.
 * An alternative admin-style interface.
 
-This will either be made as a single 3.2 release, or split across two separate releases, with the HTML forms and filter controls coming in 3.2, and the admin-style interface coming in a 3.3 release.
\ No newline at end of file
+This will either be made as a single 3.2 release, or split across two separate releases, with the HTML forms and filter controls coming in 3.2, and the admin-style interface coming in a 3.3 release.
+
+[custom-exception-handler]: ../api-guide/exceptions.md#custom-exception-handling