Added section about Setting locale from URL to i18n guide

1 files changed, 79 insertions, 5 deletions

diff --git a/railties/doc/guides/source/i18n.txt b/railties/doc/guides/source/i18n.txt
index f0a7b93a58..6000ce8ec2 100644
--- a/railties/doc/guides/source/i18n.txt
+++ b/railties/doc/guides/source/i18n.txt
@@ -112,13 +112,13 @@ I18n.default_locale = :pt
 
 === Setting and passing the locale
 
-If you want to translate your Rails application to a *single language other than English* (the default locale), you can set I18n.default_locale to your locale in +environment.rb+ or an initializer as shown above, and it will persist.
+If you want to translate your Rails application to a *single language other than English* (the default locale), you can set I18n.default_locale to your locale in +environment.rb+ or an initializer as shown above, and it will persist through the requests.
 
-However, you would probably like to *provide support for more locales* in your applications. In such case, you need to set and pass the locale between requests.
+However, you would probably like to *provide support for more locales* in your application. In such case, you need to set and pass the locale between requests.
 
 WARNING: You may be tempted to store choosed locale in a _session_ or a _cookie_. *Do not do so*. The locale should be transparent and a part of the URL. This way you don't break people's basic assumptions about the web itself: if you send a URL of some page to a friend, she should see the same page, same content. A fancy word for this would be that you're being http://en.wikipedia.org/wiki/Representational_State_Transfer[_RESTful_]. There may be some exceptions to this rule, which are discussed below.
 
-You can simply set locale in a +before_filter+ in the ApplicationController like this:
+The _setting part_ is easy. You can set locale in a +before_filter+ in the ApplicationController like this:
 
 [source, ruby]
 -------------------------------------------------------
@@ -133,11 +133,85 @@ This requires you to pass the locale as a URL query parameter as in +http://exam
 
 Of course, you probably don't want to manually include locale in every URL all over your application, or want the URLs look differently, eg. the usual +http://example.com/pt/books+ versus +http://example.com/en/books+. Let's discuss the different options you have.
 
+IMPORTANT: Following examples rely on having locales loaded into your application available as an array of strings like +["en", "es", "gr"]+. This is not inclued in current version of Rails 2.2 -- forthcoming Rails version 2.3 will contain easy accesor +available_locales+. (See http://github.com/svenfuchs/i18n/commit/411f8fe7[this commit] and background at http://rails-i18n.org/wiki/pages/i18n-available_locales[Rails I18n Wiki].) 
+
+We have to include support for getting available locales manually in an initializer like this:
+
+[source, ruby]
+-------------------------------------------------------
+# config/initializers/available_locales.rb
+#
+# Get loaded locales conveniently
+# See http://rails-i18n.org/wiki/pages/i18n-available_locales
+module I18n
+  class << self
+    def available_locales; backend.available_locales; end
+  end
+  module Backend
+    class Simple
+      def available_locales; translations.keys.collect { |l| l.to_s }.sort; end
+    end
+  end
+end
+
+# You need to "force-initialize" loaded locales
+I18n.backend.send(:init_translations)
+
+AVAILABLE_LOCALES = I18n.backend.available_locales
+RAILS_DEFAULT_LOGGER.debug "* Loaded locales: #{AVAILABLE_LOCALES.inspect}"
+-------------------------------------------------------
+
+You can then wrap the constant for easy access in ApplicationController:
+
+[source, ruby]
+-------------------------------------------------------
+class ApplicationController < ActionController::Base
+  def available_locales; AVAILABLE_LOCALES; end
+end
+-------------------------------------------------------
+
 === Setting locale from the domain name
 
-* TODO : Based on http://github.com/karmi/rails_i18n_demo_app/blob/master/app/controllers/application.rb#L44-47
+One option you have is to set the locale from the domain name, where your application runs. For example, we want +www.example.com+ to load English (or default) locale, and +www.example.es+ to load Spanish locale. Thus the _top-level domain name_ is used for locale setting. This has several advantages:
+
+* Locale is an _obvious_ part of the URL
+* People intuitively grasp in which language the content will be displayed
+* It is very trivial to implement in Rails
+* Search engines seem to like that content in different languages lives at different, inter-linked domains
+
+You can implement it like this in your ApplicationController:
+
+[source, ruby]
+-------------------------------------------------------
+before_filter :set_locale
+def set_locale
+  I18n.locale = extract_locale_from_uri
+end
+# Get locale from top-level domain or return nil if such locale is not available
+# You have to put something like:
+#   127.0.0.1 application.com
+#   127.0.0.1 application.it
+#   127.0.0.1 application.pl
+# in your /etc/hosts file to try this out locally
+def extract_locale_from_tld
+  parsed_locale = request.host.split('.').last
+  (available_locales.include? parsed_locale) ? parsed_locale  : nil
+end
+-------------------------------------------------------
+
+We can also set the locale from the _subdomain_ in very similar way:
 
-* TODO : Setting locale from subdomain -- similar to above
+[source, ruby]
+-------------------------------------------------------
+# Get locale code from request subdomain (like http://it.application.local:3000)
+# You have to put something like:
+#   127.0.0.1 gr.application.local
+# in your /etc/hosts file to try this out locally
+def extract_locale_from_subdomain
+  parsed_locale = request.subdomains.first
+  (available_locales.include? parsed_locale) ? parsed_locale  : nil
+end
+-------------------------------------------------------
 
 === Setting locale from the URL params