rack-i18n_locale_switcher 0.5.0 → 0.5.1

data/README.md

@@ -1,49 +1,86 @@
-# Rack::I18nLocaleSwitcher
+# Rack I18n Locale Switcher
 
 [![alt text][2]][1]
 
   [1]: http://travis-ci.org/#!/christoph-buente/rack-i18n_locale_switcher
   [2]: https://secure.travis-ci.org/christoph-buente/rack-i18n_locale_switcher.png
 
-This Rack middleware determines the I18n language from various sources.
+This Rack middleware sets the I18n locale from the requested URL.
 
+The locale can be determined from four different sources: host name, path prefix, query parameter and the Accept-Language header.
 
+Each of the following URLs will set the locale to 'es' (Spanish):
 
-A language or locale, can be encode within an HTTP requests in various ways. Let's have a look at the following request url:
+    http://es.example.org
+    http://example.org/es
+    http://example.org?locale=es
+    
+as will the following request:
 
-    http://es.example.it/tr/?locale=de
+    GET / HTTP/1.1
+    Host: example.org
+    Accept-Language: es
+    
 
-To extract the correct language from such a request, you probably don't want to hardcode it into you application. This middleware extracts the desired locale from this request in the following order:
-
-* request parameter (de, german)
-* url path (tr, turkish)
-* subdomain (es, spanish)
-* top level domain (it, italian)
-* HTTP Accept-language header (not visible in the url, but could be something completely different)
-
-Sound's good, gimme the code!
-
-## Rails
+### Using it with Rails
 
     # file application.rb
 
     require  'rack/i18n_locale_switcher'
-    config.middleware.use(Rack::I18nLocaleSwitcher)
+    config.middleware.use Rack::I18nLocaleSwitcher
 
-## Sinatra
+### Using it with Sinatra
 
     require 'rack/i18n_locale_switcher'
-    use Rack::I18nLocaleSwitcher, :i18n_locale_switcher
+    use Rack::I18nLocaleSwitcher
+
+
+## Configuration options
+
+
+### Source
+
+The sources from which the locale is determined and the order in which they are probed can be specified with the `source` option. By default this is `[ :param, :path, :host, :header ]`. In case ambiguous locales are provided such as in `en.example.org/de`, the path (de) will have precedence over the host (en), due to its higher order.
+
+If you want to support only one source, which is strongly encouraged, you can configure the middleware using the `source` option:
+
+    use Rack::I18nLocaleSwitcher, :source => [ :path, :header ]
+    
+You might always want to include `header` as the last option. In case no locale was specified in the URL (i.e. `http://example.org`) and you would otherwise fall back to the default locale, the user preferred locale as indicated in the Accept-Language header will always be the better choice.
+
+
+### Redirect
+
+If you allow more than one source (because you have to support a legacy URL scheme, for example) you can choose to redirect requests to the preferred scheme. Redirect is not enabled by default. 
+
+    use Rack::I18nLocaleSwitcher, :source => [ :path, :param, :header ], :redirect => :path
+    
+With this setup, a request to `https://example.org?locale=es` would be permanently redirected to `https://example.org/es`.
+
+
+### Canonical URLs
+
+Many sites have a default locale which is not part of the URL. Only if a different locale is requested, it will be indicated in the URL. For example, `www.apple.com` uses English by default while other languages have a prefix to the path such as `www.apple.com/jp/` for Japanese.
+
+If no locale can be determined from the URL, the locale switcher falls back to the `I18n.default_locale`. However, depending on your application, this might result in the default locale to be available under two different URLs, such as `http://example.org` and `http://example.org/en`. The problem with this is mainly that search engines will see both URLs and consider it duplicate content resulting in your page rank taking a penalty.
+
+To avoid this, you can set the `canonical` option resulting in requests to be redirected to the canonical URL (without the locale):
+
+    use Rack::I18nLocaleSwitcher, :source => [ :host, :header ], :redirect => :path, :canonical => true
+
+In this configuration, requests to `http://en.example.org` will be redirected to `http://example.org` (provided you have set `I18n.default_locale` to `:en`).
 
 
-Q: Ok, but where does the locale go?
+## Configuring I18n
 
-A: The middleware uses the ruby internationalization gem [i18n](http://rubygems.org/gems/i18n), which stores the locale in a variable. You can use this variable in your app as
+You have to define which locales are actually supported by your application. In Rails this happens automagically, in other application you have to set the available locales explicitely:
 
-    I18n.locale
+    I18n.available_locales = [:de, :en, :es, :it, :tr ]
+    
+You should also set the default locale to which Locale Switcher will fall back in case the locale can't be determined. This setting is also important if you use canonical URLs (see above).
 
-Q: How can I define, which locales are available?
+    I18n.default_locale = :de
 
-A: You can set the available locales before using instantiation the middleware.
+## Feedback and Contributions
 
-    I18n.available_locales = [:de, :en, :es, :it, :tr ]
+We appreciate your feedback and contributions. If you find a bug, feel free to to open a GitHub issue. Better yet, add a test that exposes the bug, fix it and send us a pull request.

data/Rakefile

@@ -2,7 +2,7 @@
 require 'rake'
 require 'echoe'
 
-Echoe.new('rack-i18n_locale_switcher', '0.5.0') do |p|
+Echoe.new('rack-i18n_locale_switcher', '0.5.1') do |p|
 
  p.description = "Detects the current locale from query parameter, path prefix, host or accept header."
  p.url         = "http://github.com/christoph-buente/rack-i18n_locale_switcher"

data/lib/rack/i18n_locale_switcher.rb

@@ -3,7 +3,7 @@ require 'i18n'
 module Rack
   class I18nLocaleSwitcher
     
-    LOCALE_PATTERN = '([a-z]{1,8})(-[a-zA-Z]{1,8})?'.freeze
+    LOCALE_PATTERN = '([a-zA-Z]{2,3})(-[a-zA-Z]{2,3})?'.freeze
     
     SOURCES   = [ :param, :path, :host, :header ].freeze
     REDIRECTS = [ :param, :path, :host ].freeze
@@ -125,14 +125,12 @@ module Rack
     end
 
     def set_locale_in_path(env)
-      env['PATH_INFO'] = "/#{ I18n.locale }#{ env['PATH_INFO'] }"
-      env['PATH_INFO'].gsub!(/\/$/, '')
+      env['PATH_INFO'] = "/#{ I18n.locale }#{ env['PATH_INFO'] }".gsub(/\/$/, '')
     end
 
     def set_locale_in_host(env)
-      ['HTTP_HOST', 'SERVER_NAME'].each do |key|
-        env[ key ] = "#{ I18n.locale }.#{ env[ key ] }"
-      end
+      env['HTTP_HOST']   = "#{ I18n.locale }.#{ env['HTTP_HOST'] }"
+      env['SERVER_NAME'] = "#{ I18n.locale }.#{ env['SERVER_NAME'] }"
     end
     
     def available_locale(language, region)

data/rack-i18n_locale_switcher.gemspec

@@ -2,7 +2,7 @@
 
 Gem::Specification.new do |s|
   s.name = %q{rack-i18n_locale_switcher}
-  s.version = "0.5.0"
+  s.version = "0.5.1"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 1.2") if s.respond_to? :required_rubygems_version=
   s.authors = ["Christoph B\303\274nte, Andreas Korth"]

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: rack-i18n_locale_switcher
 version: !ruby/object:Gem::Version 
-  hash: 11
+  hash: 9
   prerelease: 
   segments: 
   - 0
   - 5
-  - 0
-  version: 0.5.0
+  - 1
+  version: 0.5.1
 platform: ruby
 authors: 
 - "Christoph B\xC3\xBCnte, Andreas Korth"