Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 157 lines (106 sloc) 7.032 kB
ba1fb1d @raul first commit
authored
1 =TranslateRoutes
2 This Rails plugin provides a simple way to translate your URLs to any number of languages.
3 All routes automatically add a <tt>:lang</tt> parameter to the request so your controllers can setup an internationalized user experience.
4
5 The plugin has been designed to be easy to use and customize.
6 As it works after routing processing, it plays nice with all kind of routing definitions, including RESTful and named routes.
7 It also takes care of your current routing helpers by translating them transparently.
8
9 ==Installation
bd29769 @raul README updated with the Rails required version
authored
10 This version works only with Rails 2.1.x. You can find all available versions in the wiki: [http://wiki.github.com/raul/translate_routes]
ba1fb1d @raul first commit
authored
11 Just check it out on your app's <tt>/vendor/plugins</tt> and see the examples below.
12
13 ==Usage
14 Let's start with a tiny example. Of course you need to define your routes first, e.g:
15
16 ActionController::Routing::Routes.draw do |map|
17 map.connect 'contact', :controller => 'contact', :action => 'index'
18 end
19
20 After that, on the same routes.rb file, you can translate the generated route by doing:
21
22 ActionController::Routing::Translator.translate do |t|
23 t['es'] = {
24 'contact' => 'contacto'
25 }
26 end
27
28 This will give you the next routes (check it out by doing 'rake routes'):
29
30 /es/contacto {:lang=>"es", :controller=>"contact", :action=>"index"}
31 /contact {:lang=>"en", :controller=>"contact", :action=>"index"}
32
33 As you can see:
34 - a +lang+ param has been added to your routes, with the value of the used language (*)
35 - +en+ is the default language (*)
36 - the URLs associated with a language are always prefixed with the language code that you provided on the translation.
37 - the default language URLs have no language prefix (*)
38 (*) You can customize this behaviour, see "Configuration" below.
39
40 Let's add some routes and translations to our example:
41
42 ActionController::Routing::Routes.draw do |map|
43 map.connect 'contact', :controller => 'contact', :action => 'index'
44 map.home '', :controller => 'main', :action => 'index'
45 map.resources :people
46 end
47
48 ActionController::Routing::Translator.translate do |t|
49
50 t['es'] = {
51 'contact' => 'contacto',
52 'people' => 'gente',
53 'new' => 'crear',
54 'edit' =>'editar'
55 }
56
57 t['fr'] = {
58 'people' => 'personne',
59 'new' => 'neuf'
60 }
61 end
62
63 Again, you can use <tt>rake routes</tt> to see the generated URLs. I'll only talk about some of them:
64
65 We didn't give any french translation for +contact+, so the french associated URLs use the untranslated text:
66
67 /fr/contact {:lang=>"fr", :controller=>"contact", :action=>"index"}
68 /es/contacto {:lang=>"es", :controller=>"contact", :action=>"index"}
69 /contact {:lang=>"en", :controller=>"contact", :action=>"index"}
70
71 The named routes have generated not only translated URLs but also a helper for each language:
72
73 home_fr /fr {:lang=>"fr", :controller=>"main", :action=>"index"}
74 home_es /es {:lang=>"es", :controller=>"main", :action=>"index"}
75 home_en / {:lang=>"en", :controller=>"main", :action=>"index"}
76
77 This means that you can use +home_es_path+ and +home_es_url+ on your controllers and views.
78
79 No +home+ named route is shown on the list so it looks like you can't use a simple +home_path+ helper, but relax: you have a +home_path+ helper available for your controllers and views. It looks for the current +lang+ value and redirects to the appropiate helper. This means that if you're rendering the <tt>contact/index</tt> view when visiting <tt>/es/contacto</tt>, the +home_path+ helper will call to +home_es_path+ and return its result. The same applies to +home_url+, obviously.
80
81 We can see that resource controllers and actions are translated as well:
82
83 new_person_fr GET /fr/personne/neuf {:lang=>"fr", :controller=>"people", :action=>"new"}
84 new_person_es GET /es/gente/crear {:lang=>"es", :controller=>"people", :action=>"new"}
85 new_person GET /people/new {:lang=>"en", :controller=>"people", :action=>"new"}
86
1b62e9a @raul Added update_yaml task to create/update yaml files, suggested by Fran…
authored
87 We can get rid of that verbose translation hashes by using yaml files, which can be generated/updated with the <tt>translate_routes:update_yaml</tt> rake task.
88 Let's create a spanish and french translation files with <tt>translate_routes:update_yaml["es fr"]</tt>
89
90 If it's the first time that we run the task, the files will contain a yaml skeleton with the strings to translate.
91 If we already have translated some strings they will remain on the file after executing the task, so you can run it after any <tt>routes.rb</tt> edition.
92
93 We can now translate the strings for any language
ba1fb1d @raul first commit
authored
94
95 # /config/routes_es.yml
96 person: persona
97
98 and replace all the
99
100 ActionController::Routing::Translator.translate do
101 ...
102 end
103
104 stuff on <tt>routes.rb</tt> with this simple line:
105
106 ActionController::Routing::Translator.translate_from_files
107
108 == Integration
109 You can find a sample Rails application on the translate_routes repository, designed to show how easy is to setup
110
111 == Configuration
112 You can customize some features by adding some lines before your translation code:
113
114 - You can change the language param key (<tt>:lang</tt> by default). To change this feature use:
115
116 ActionController::Routing::Translator.lang_param_key = :foo
117
118 This key should have the same name that the instance variable which keeps the language code on your controllers and views.
119
120 - You can change the default language of your application with:
121
122 ActionController::Routing::Translator.default_lang = 'es'
123
124 Of course, you can also translate your default language. If, as I do, all your controllers and actions have english names, you can have an english version on your site for free by doing:
125
126 ActionController::Routing::Translator.default_lang = 'es'
127 ActionController::Routing::Translator.translate do |t|
128 t['en'] = {}
129 t['es'] = { # spanish translation here }
130 end
131
132 or adding the equivalent <tt>/config/routes_es.yml</tt> and an empty <tt>/config/routes_en.yml</tt>
133
134 - You can add a prefix also on your default language routes by doing:
135
136 ActionController::Routing::Translator.prefix_on_default_lang = true
137
138 <b>WARNING!</b> this way you'll disable your root -empty- route: if english is your default language, your empty route will be translated to <tt>/en</tt> so you must manually take care of it.
139
140 == Suggestions, bug reports, questions
141 Feedback and comments will be always welcome at raul@murciano.net
142
143
144 == Credits
145 - Raul Murciano [http://raul.murciano.net] - code
146 - Domestika INTERNET S.L [http://domestika.org] - incredible support, really nice people to work with!
147
148
149 == Rails routing resources
150 - David Black's 'Rails Routing' ebook rocks! - 'Ruby for Rails' too, BTW.
151 - Obie Fernandez's 'The Rails Way' - the definitive RoR reference, great work Obie!
152
153 == License
154 Copyright (c) 2007
155 Raul Murciano [http://raul.murciano.net]
156 Domestika INTERNET S.L. [http://domestika.org], released under the MIT license (see MIT-LICENSE)
Something went wrong with that request. Please try again.