LocaleRouting
LocaleRouting makes using I18N locale from an url parameter or hostname seamless.
It taps into the route recognition and generation methods and checks or adds the locale when nessecary.
The plugin loads its available locales from Rails default I18N class.
For every request, it check the configured part the URL match any of the locale definitions exposed by I18n.available_locales.
If a locale string is found, the application I18n.locale is changed and the locale is passed via params[:locale].
Access to mapped URLs is wrapped also, the current I18n.locale is always prepended to the generated URLs parameters.
Additionally you can pass a => "en option to your link helpers, which will inject the given locale into the output URL.
This parameter defaults to I18n.locale.
No routes have to be changed to use this functionality.
Installation
There are several different ways to install this plugin.
Installing as Rails gem dependency
To add locale-routing as a gem dependecy, add this to your 'config/environment.rb' Rails::Initializer.run do |config| block: config.gem 'perfectline-locale-routing', :lib => 'locale-routing', :source => 'http://gems.github.com'
To install this gem (and other missing gem dependencies) run 'rake gems:install'.
Installing the gem manually
This requires you to have at least RubyGems version 1.2 (run 'gem -v' to check your current version).
As the 'locale-routing' gem is built by GitHub, you have to add GitHub as a gem source on your environment (if you havent done it already):
sudo gem sources -a http://gems.github.com
Install the plugin library: sudo gem install perfectline-locale-routing
To include them gem in your application, add this to the bottom of your 'environment.rb' or in an initializer: require 'locale_routing'
Install as a plugin via Git
Alternatively you can use 'script/plugin' to export the code into your applications 'vendor/plugins' directory.
'script/plugin install git://github.com/perfectline/locale-routing.git'
Configuration
To enable or disable the locale routing set Perfectline::LocaleRouting::Config.enabled = true/false # defaults to true To specifiy which part of the URL should be matched for the locale identifier, set Perfectline::LocaleRouting::Config.match_from = option
Available options for match_from are:
:params
Searches for a 2 letter locale string in the parameters, specifically in the first query stirng token.
Found token is matched against I18n.available_locales and if no such locale exists, it will fall back to the default locale.Example: www.myapp.com resolves to root controller with the default locale www.myapp.com/en resolves to root controller with locale => "en" www.myapp.com/foo/bar resolves to "foo" controller, "bar" action with default locale www.myapp.com/fr/foo/bar resolves to "foo" controller, "bar" action with locale => "fr"
:host
Searches for configured matches in the domain name. If a match is found, the configured locale is then checked against I18n.available_locales.
If the configured locale does not exist in available locales, it will fall back to the default locale.Configuring host to locale mappings is done via Perfectline::LocaleRouting::Config.mapping do |block|. Hash key must be the hostname pattern to be matched and value is the locale string.
Hostname patterns are like simplified regexp patterns with * wildcard support.
Mappings matching is similar to route config - first match found is used, rest is ignored.Example: Perfectline::LocaleRouting::Config.mapping do |map| map.match "en.dev.", "en", # matches en.dev.yoursite.com and en.dev.mysite.co.uk map.match ".dev.", "en", # matches foo.dev.yoursite.com and www.dev.yoursite.com but not en.dev.mysite.com as its defined AFTER that mapping map.match "en.", "en", # matches en.yoursite.com but not en.dev.yoursite.com or en.foo.dev.yoursite.com as its defined AFTER that mapping map.match "*.com", "en", # matches anything with a .com TLD end
Warning
This plugin has not been fully tested with all possible cases except perhaps the params locale matching.
As you can see there are no tests yet either, although they will be created as soon as possible.
So if you do run into issues or have any improvement ideas, feel free to contact the authors.
Honorable mentions
This plugin is heavily inspired by the "routing-filter" plugin by Sven Fuchs.
Authors:
Tanel Suurhans - tanel.suurhans_at_perfectline_d0t_ee
Tarmo Lehtpuu - tarmo.lehtpuu_at_perfectline_d0t_ee
License
Copyright 2009 by PerfectLine LLC (http://www.perfectline.co.uk) and is released under the MIT license.