Merge pull request #1 from tomchristie/master

Merge in from upstream

1 files changed, 25 insertions, 12 deletions

diff --git a/docs/api-guide/format-suffixes.md b/docs/api-guide/format-suffixes.md
index 529738e3..35dbcd39 100644
--- a/docs/api-guide/format-suffixes.md
+++ b/docs/api-guide/format-suffixes.md
@@ -1,4 +1,4 @@
-<a class="github" href="urlpatterns.py"></a>
+source: urlpatterns.py
 
 # Format suffixes
 
@@ -7,7 +7,7 @@ used all the time.
 >
 > &mdash; Roy Fielding, [REST discuss mailing list][cite]
 
-A common pattern for Web APIs is to use filename extensions on URLs to provide an endpoint for a given media type.  For example, 'http://example.com/api/users.json' to serve a JSON representation. 
+A common pattern for Web APIs is to use filename extensions on URLs to provide an endpoint for a given media type.  For example, 'http://example.com/api/users.json' to serve a JSON representation.
 
 Adding format-suffix patterns to each individual entry in the URLconf for your API is error-prone and non-DRY, so REST framework provides a shortcut to adding these patterns to your URLConf.
 
@@ -21,18 +21,19 @@ Arguments:
 
 * **urlpatterns**: Required.  A URL pattern list.
 * **suffix_required**:  Optional.  A boolean indicating if suffixes in the URLs should be optional or mandatory.  Defaults to `False`, meaning that suffixes are optional by default.
-* **allowed**:  Optional.  A list or tuple of valid format suffixes.  If not provided, a wildcard format suffix pattern will be used. 
+* **allowed**:  Optional.  A list or tuple of valid format suffixes.  If not provided, a wildcard format suffix pattern will be used.
 
 Example:
 
     from rest_framework.urlpatterns import format_suffix_patterns
-    
-    urlpatterns = patterns('blog.views',
-        url(r'^/$', 'api_root'),
-        url(r'^comments/$', 'comment_list'),
-        url(r'^comments/(?P<pk>[0-9]+)/$', 'comment_detail')
-    )
-    
+    from blog import views
+
+    urlpatterns = [
+        url(r'^/$', views.apt_root),
+        url(r'^comments/$', views.comment_list),
+        url(r'^comments/(?P<pk>[0-9]+)/$', views.comment_detail)
+    ]
+
     urlpatterns = format_suffix_patterns(urlpatterns, allowed=['json', 'html'])
 
 When using `format_suffix_patterns`, you must make sure to add the `'format'` keyword argument to the corresponding views.  For example:
@@ -54,13 +55,25 @@ The name of the kwarg used may be modified by using the `FORMAT_SUFFIX_KWARG` se
 
 Also note that `format_suffix_patterns` does not support descending into `include` URL patterns.
 
+### Using with `i18n_patterns`
+
+If using the `i18n_patterns` function provided by Django, as well as `format_suffix_patterns` you should make sure that the `i18n_patterns` function is applied as the final, or outermost function. For example:
+
+    url patterns = [
+        …
+    ]
+
+    urlpatterns = i18n_patterns(
+        format_suffix_patterns(urlpatterns, allowed=['json', 'html'])
+    )
+
 ---
-        
+
 ## Accept headers vs. format suffixes
 
 There seems to be a view among some of the Web community that filename extensions are not a RESTful pattern, and that `HTTP Accept` headers should always be used instead.
 
-It is actually a misconception.  For example, take the following quote from Roy Fielding discussing the relative merits of query parameter media-type indicators vs. file extension media-type indicators: 
+It is actually a misconception.  For example, take the following quote from Roy Fielding discussing the relative merits of query parameter media-type indicators vs. file extension media-type indicators:
 
 &ldquo;That's why I always prefer extensions.  Neither choice has anything to do with REST.&rdquo; &mdash; Roy Fielding, [REST discuss mailing list][cite2]