1 files changed, 47 insertions, 17 deletions
diff --git a/guides/source/i18n.md b/guides/source/i18n.md
index 78e5f27448..10b1a6de7e 100644
--- a/guides/source/i18n.md
+++ b/guides/source/i18n.md
@@ -116,7 +116,7 @@ NOTE: The backend lazy-loads these translations when a translation is looked up
 You can change the default locale as well as configure the translations load paths in `config/application.rb` as follows:
 
 ```ruby
-  config.i18n.load_path += Dir[Rails.root.join('my', 'locales', '*.{rb,yml}').to_s]
+  config.i18n.load_path += Dir[Rails.root.join('my', 'locales', '*.{rb,yml}')]
   config.i18n.default_locale = :de
 ```
 
@@ -135,19 +135,22 @@ I18n.available_locales = [:en, :pt]
 I18n.default_locale = :pt
 ```
 
+Note that appending directly to `I18n.load_paths` instead of to the application's configured i18n will _not_ override translations from external gems.
+
 ### Managing the Locale across Requests
 
 The default locale is used for all translations unless `I18n.locale` is explicitly set.
 
 A localized application will likely need to provide support for multiple locales. To accomplish this, the locale should be set at the beginning of each request so that all strings are translated using the desired locale during the lifetime of that request.
 
-The locale can be set in a `before_action` in the `ApplicationController`:
+The locale can be set in an `around_action` in the `ApplicationController`:
 
 ```ruby
-before_action :set_locale
+around_action :switch_locale
 
-def set_locale
-  I18n.locale = params[:locale] || I18n.default_locale
+def switch_locale(&action)
+  locale = params[:locale] || I18n.default_locale
+  I18n.with_locale(locale, &action)
 end
 ```
 
@@ -167,10 +170,11 @@ One option you have is to set the locale from the domain name where your applica
 You can implement it like this in your `ApplicationController`:
 
 ```ruby
-before_action :set_locale
+around_action :switch_locale
 
-def set_locale
-  I18n.locale = extract_locale_from_tld || I18n.default_locale
+def switch_locale(&action)
+  locale = extract_locale_from_tld || I18n.default_locale
+  I18n.with_locale(locale, &action)
 end
 
 # Get locale from top-level domain or return +nil+ if such locale is not available
@@ -210,7 +214,7 @@ This solution has aforementioned advantages, however, you may not be able or may
 
 #### Setting the Locale from URL Params
 
-The most usual way of setting (and passing) the locale would be to include it in URL params, as we did in the `I18n.locale = params[:locale]` _before_action_ in the first example. We would like to have URLs like `www.example.com/books?locale=ja` or `www.example.com/ja/books` in this case.
+The most usual way of setting (and passing) the locale would be to include it in URL params, as we did in the `I18n.with_locale(params[:locale], &action)` _around_action_ in the first example. We would like to have URLs like `www.example.com/books?locale=ja` or `www.example.com/ja/books` in this case.
 
 This approach has almost the same set of advantages as setting the locale from the domain name: namely that it's RESTful and in accord with the rest of the World Wide Web. It does require a little bit more work to implement, though.
 
@@ -273,8 +277,11 @@ NOTE: Have a look at various gems which simplify working with routes: [routing_f
 An application with authenticated users may allow users to set a locale preference through the application's interface. With this approach, a user's selected locale preference is persisted in the database and used to set the locale for authenticated requests by that user.
 
 ```ruby
-def set_locale
-  I18n.locale = current_user.try(:locale) || I18n.default_locale
+around_action :switch_locale
+
+def switch_locale(&action)
+  locale = current_user.try(:locale) || I18n.default_locale
+  I18n.with_locale(locale, &action)
 end
 ```
 
@@ -289,10 +296,11 @@ The `Accept-Language` HTTP header indicates the preferred language for request's
 A trivial implementation of using an `Accept-Language` header would be:
 
 ```ruby
-def set_locale
+def switch_locale(&action)
   logger.debug "* Accept-Language: #{request.env['HTTP_ACCEPT_LANGUAGE']}"
-  I18n.locale = extract_locale_from_accept_language_header
+  locale = extract_locale_from_accept_language_header
   logger.debug "* Locale set to '#{I18n.locale}'"
+  I18n.with_locale(locale, &action)
 end
 
 private
@@ -333,10 +341,12 @@ end
 ```ruby
 # app/controllers/application_controller.rb
 class ApplicationController < ActionController::Base
-  before_action :set_locale
 
-  def set_locale
-    I18n.locale = params[:locale] || I18n.default_locale
+  around_action :switch_locale
+
+  def switch_locale(&action)
+    locale = params[:locale] || I18n.default_locale
+    I18n.with_locale(locale, &action)
   end
 end
 ```
@@ -662,6 +672,26 @@ I18n.t 'activerecord.errors.messages'
 # => {:inclusion=>"is not included in the list", :exclusion=> ... }
 ```
 
+If you want to perform interpolation on a bulk hash of translations, you need to pass `deep_interpolation: true` as a parameter. When you have the following dictionary:
+
+```yaml
+en:
+  welcome:
+    title: "Welcome!"
+    content: "Welcome to the %{app_name}"
+```
+
+then the nested interpolation will be ignored without the setting:
+
+```ruby
+I18n.t 'welcome', app_name: 'book store'
+# => {:title=>"Welcome!", :content=>"Welcome to the %{app_name}"}
+
+I18n.t 'welcome', deep_interpolation: true, app_name: 'book store'
+# => {:title=>"Welcome!", :content=>"Welcome to the book store"}
+```
+
+
 #### "Lazy" Lookup
 
 Rails implements a convenient way to look up the locale inside _views_. When you have the following dictionary:
@@ -1103,7 +1133,7 @@ For several reasons the Simple backend shipped with Active Support only does the
 
 That does not mean you're stuck with these limitations, though. The Ruby I18n gem makes it very easy to exchange the Simple backend implementation with something else that fits better for your needs, by passing a backend instance to the `I18n.backend=` setter.
 
-For example, you can replace the Simple backend with the the Chain backend to chain multiple backends together. This is useful when you want to use standard translations with a Simple backend but store custom application translations in a database or other backends.
+For example, you can replace the Simple backend with the Chain backend to chain multiple backends together. This is useful when you want to use standard translations with a Simple backend but store custom application translations in a database or other backends.
 
 With the Chain backend, you could use the Active Record backend and fall back to the (default) Simple backend: