Skip to content
This repository

Rails plugin to translate your URLs and routing helpers on an clean way.

tree: e298e5f8a3
README
=TranslateRoutes

This Rails plugin provides a simple way to translate your URLs to any number of languages, even on a fully working application.

It works fine with all kind of routing definitions, including RESTful and named routes.
<strong>Your code will remain untouched</strong>: your current routing code, helpers and links will be translated transparently.
(Un)installing it is a very clean and simple process, so why don't you give it a chance? ;)

==Quick start

Let's start with a tiny example. Of course you need to define your routes first, e.g:
<code>
	ActionController::Routing::Routes.draw do |map| 
	  map.contact 'contact', :controller => 'contact', :action => 'index'
	end
</code>

1. Download the plugin to your app's <tt>/vendor/plugins</tt> directory.

2. Write your translations on a standard YAML file (e.g: i18n-routes.yml), including the locales and it translations pairs:
<code>
es-ES:
  contact: contacto
</code>

3. Append a line to your routes.rb file to activate the translations. If you loaded the translations file with
your other I18n translations files, the line will be:
<code>ActionController::Routing::Translator.i18n('es-ES')</code>
and if you want to keep the file separated (e.g: config/i18n-routes.yml), the line to append is:
<code>ActionController::Routing::Translator.translate_from_file('config','i18n-routes.yml')</code>

You can see it working by executing <code>rake routes</code> on the shell:

<code>
contact_es_es_path /es-ES/contacto {:locale=>"es-ES", :controller=>"contact", :action=>"index"}
contact_en_us_path /contact        {:locale=>"en-US", :controller=>"contact", :action=>"index"}
</code>

As we can see, a new spanish route has been setted up and a <tt>locale</tt> parameter has been added to the routes.

4. Include this filter in your ApplicationController:

<code>before_filter :set_locale_from_url</code>

Now your application recognizes the different routes and sets the <tt>I18n.locale</tt> value on your controllers, 
but what about the routes generation? As you can see on the previous <tt>rake routes</tt> execution, the 
<tt>contact_es_es_path</tt> and <tt>contact_en_us_path</tt> routing helpers have been generated and are 
available in your controllers and views. Additionally, a <tt>contact_path</tt> helper has been generated, which 
generates the routes according to the current I18n.locale value. 

This way <strong>you don't need to modify your application links</strong> because they <strong>adapt automatically to the current locale</strong>.

5. Hey, but what about my tests?

Of course, your functional and integration testing involves some requests. 
The plugin includes some code to add a default locale parameter so they can remain untouched.
Append it to your <tt>test_helper</tt> and it will be applied.

== Documentation

You can find additional options and documentation on the translate_routes wiki, and a sample application that you 
can use as reference.

== Suggestions, bug reports, questions
Feedback and comments will be always welcome at raul@murciano.net

== Credits
- Raul Murciano [http://raul.murciano.net] - code
- Domestika INTERNET S.L [http://domestika.org] - incredible support, really nice people to work with!


== Rails routing resources
- David Black's 'Rails Routing' ebook rocks! - 'Ruby for Rails' too, BTW.
- Obie Fernandez's 'The Rails Way' - the definitive RoR reference, great work Obie!

== License
Copyright (c) 2007
Raul Murciano [http://raul.murciano.net]
Domestika INTERNET S.L. [http://domestika.org], released under the MIT license (see MIT-LICENSE)
Something went wrong with that request. Please try again.