i18n guide: warn about default_url_options caching and locale selectors [ci skip]

1 files changed, 6 insertions, 4 deletions

diff --git a/guides/source/i18n.md b/guides/source/i18n.md
index 9f0ed1a85b..31682464ee 100644
--- a/guides/source/i18n.md
+++ b/guides/source/i18n.md
@@ -216,8 +216,8 @@ We can include something like this in our `ApplicationController` then:
 
 ```ruby
 # app/controllers/application_controller.rb
-def default_url_options(options = {})
-  { locale: I18n.locale }.merge options
+def default_url_options
+  { locale: I18n.locale }
 end
 ```
 
@@ -225,7 +225,7 @@ Every helper method dependent on `url_for` (e.g. helpers for named routes like `
 
 You may be satisfied with this. It does impact the readability of URLs, though, when the locale "hangs" at the end of every URL in your application. Moreover, from the architectural standpoint, locale is usually hierarchically above the other parts of the application domain: and URLs should reflect this.
 
-You probably want URLs to look like this: `www.example.com/en/books` (which loads the English locale) and `www.example.com/nl/books` (which loads the Dutch locale). This is achievable with the "over-riding `default_url_options`" strategy from above: you just have to set up your routes with [`scoping`](http://api.rubyonrails.org/classes/ActionDispatch/Routing/Mapper/Scoping.html) option in this way:
+You probably want URLs to look like this: `http://www.example.com/en/books` (which loads the English locale) and `http://www.example.com/nl/books` (which loads the Dutch locale). This is achievable with the "over-riding `default_url_options`" strategy from above: you just have to set up your routes with [`scope`](http://api.rubyonrails.org/classes/ActionDispatch/Routing/Mapper/Scoping.html):
 
 ```ruby
 # config/routes.rb
@@ -234,7 +234,9 @@ scope "/:locale" do
 end
 ```
 
-Now, when you call the `books_path` method you should get `"/en/books"` (for the default locale). An URL like `http://localhost:3001/nl/books` should load the Dutch locale, then, and following calls to `books_path` should return `"/nl/books"` (because the locale changed).
+Now, when you call the `books_path` method you should get `"/en/books"` (for the default locale). A URL like `http://localhost:3001/nl/books` should load the Dutch locale, then, and following calls to `books_path` should return `"/nl/books"` (because the locale changed).
+
+WARNING. Since the return value of `default_url_options` is cached per request, the URLs in a locale selector cannot be generated invoking helpers in a loop that sets the corresponding `I18n.locale` in each iteration. Instead, leave `I18n.locale` untouched, and pass an explicit `:locale` option to the helper, or edit `request.original_fullpath`.
 
 If you don't want to force the use of a locale in your routes you can use an optional path scope (denoted by the parentheses) like so: