Rack I18n Locale Switcher
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):
http://es.example.org
http://example.org/es
http://example.org?locale=es
as will the following request:
GET / HTTP/1.1
Host: example.org
Accept-Language: es
Using it with Rails
# file application.rb
require 'rack/i18n_locale_switcher'
config.middleware.use Rack::I18nLocaleSwitcher
If you use Rails 3.1 with the asset pipeline, make sure you exclude the path to assets:
config.middleware.use Rack::I18nLocaleSwitcher, :except => /^\/assets/
Using it with Sinatra
require 'rack/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
).
Exceptions
If you would like to exclude certain paths from locale switcher, just pass a regex matching these paths in the except
option.
use Rack::I18nLocaleSwitcher, :redirect => :path, :except => /^\/(assets|static)\b/
Configuring I18n
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.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).
I18n.default_locale = :de
Feedback and Contributions
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.