Skip to content
Newer
Older
100644 236 lines (173 sloc) 8.52 KB
66c0a72 @grosser readme: simplify, restructure headings, add rails3 instructions
authored
1 [FastGettext](http://github.com/grosser/fast_gettext) / Rails integration.
4569f39 @grosser initial
authored
2
66c0a72 @grosser readme: simplify, restructure headings, add rails3 instructions
authored
3 Translate via FastGettext, use any other I18n backend as extension/fallback.
4569f39 @grosser initial
authored
4
59cfa49 @grosser add Nikos Dimitrakopoulos to contributors
authored
5 Rails does: `I18n.t('syntax.with.lots.of.dots')` with nested yml files
6 We do: `_('Just translate my damn text!')` with simple, flat mo/po/yml files or directly from db
66c0a72 @grosser readme: simplify, restructure headings, add rails3 instructions
authored
7 To use I18n calls add a `syntax.with.lots.of.dots` translation.
4569f39 @grosser initial
authored
8
a5dfbf9 @grosser docs
authored
9 [See it working in the example application.](https://github.com/grosser/gettext_i18n_rails_example)
10
4569f39 @grosser initial
authored
11 Setup
12 =====
66c0a72 @grosser readme: simplify, restructure headings, add rails3 instructions
authored
13 ### Installation
2d1a11b @grosser updated docs
authored
14
66c0a72 @grosser readme: simplify, restructure headings, add rails3 instructions
authored
15 #### Rails 3
2d1a11b @grosser updated docs
authored
16
66c0a72 @grosser readme: simplify, restructure headings, add rails3 instructions
authored
17 ##### As plugin:
a5dfbf9 @grosser docs
authored
18
66c0a72 @grosser readme: simplify, restructure headings, add rails3 instructions
authored
19 rails plugin install git://github.com/grosser/gettext_i18n_rails.git
ce7afb1 @grosser hacky haml parser replaced through superior gettext ruby parser, that…
authored
20
66c0a72 @grosser readme: simplify, restructure headings, add rails3 instructions
authored
21 # Gemfile
22 gem 'fast_gettext', '>=0.4.8'
23
24 ##### As gem:
25
26 # Gemfile
27 gem 'gettext_i18n_rails'
28
29 ##### Optional:
0b50683 @grosser add docs for ruby_parser
authored
30 Add `gettext` if you want to find translations or build .mo files<br/>
b20658a @grosser Tell people that ruby_parser does not support 1.9 syntax
authored
31 Add `ruby_parser` if you want to find translations inside haml/slim/hamlet files (does not support ruby 1.9 syntax)
0b50683 @grosser add docs for ruby_parser
authored
32
33
66c0a72 @grosser readme: simplify, restructure headings, add rails3 instructions
authored
34 # Gemfile
35 gem 'gettext', '>=1.9.3', :require => false, :group => :development
0b50683 @grosser add docs for ruby_parser
authored
36 gem 'ruby_parser', :require => false, :group => :development
66c0a72 @grosser readme: simplify, restructure headings, add rails3 instructions
authored
37
38 #### Rails 2
4569f39 @grosser initial
authored
39
66c0a72 @grosser readme: simplify, restructure headings, add rails3 instructions
authored
40 ##### As plugin:
41
42 script/plugin install git://github.com/grosser/gettext_i18n_rails.git
43 sudo gem install fast_gettext
a867983 @grosser cleanup install instructions
authored
44
45 # config/environment.rb
46 config.gem "fast_gettext", :version => '>=0.4.8'
47
66c0a72 @grosser readme: simplify, restructure headings, add rails3 instructions
authored
48 ##### As gem:
7121bfb @pupeno Documentation for using it as a gem (and other small improvements).
pupeno authored
49
66c0a72 @grosser readme: simplify, restructure headings, add rails3 instructions
authored
50 gem install gettext_i18n_rails
7121bfb @pupeno Documentation for using it as a gem (and other small improvements).
pupeno authored
51
66c0a72 @grosser readme: simplify, restructure headings, add rails3 instructions
authored
52 # config/environment.rb
53 config.gem 'gettext_i18n_rails'
7121bfb @pupeno Documentation for using it as a gem (and other small improvements).
pupeno authored
54
226c466 @pupeno File names in documentation sample code.
pupeno authored
55 #Rakefile
7121bfb @pupeno Documentation for using it as a gem (and other small improvements).
pupeno authored
56 begin
57 require "gettext_i18n_rails/tasks"
58 rescue LoadError
59 puts "gettext_i18n_rails is not installed, you probably should run 'rake gems:install' or 'bundle install'."
60 end
61
66c0a72 @grosser readme: simplify, restructure headings, add rails3 instructions
authored
62 ##### Optional:
63 If you want to find translations or build .mo files
64 # config/environments/development.rb
65 config.gem "gettext", :version => '>=1.9.3', :lib => false
66
67 ### Locales & initialisation
68 Copy default locales with dates/sentence-connectors/AR-errors you want from e.g.
69 [rails i18n](http://github.com/svenfuchs/rails-i18n/tree/master/rails/locale/) into 'config/locales'
70
7121bfb @pupeno Documentation for using it as a gem (and other small improvements).
pupeno authored
71 To initialize:
72
a867983 @grosser cleanup install instructions
authored
73 # config/initializers/fast_gettext.rb
66c0a72 @grosser readme: simplify, restructure headings, add rails3 instructions
authored
74 FastGettext.add_text_domain 'app', :path => 'locale', :type => :po
3fed237 @grosser recommend to use defaults, its easier...
authored
75 FastGettext.default_available_locales = ['en','de'] #all you want to allow
76 FastGettext.default_text_domain = 'app'
4569f39 @grosser initial
authored
77
7121bfb @pupeno Documentation for using it as a gem (and other small improvements).
pupeno authored
78 And in your application:
79
a867983 @grosser cleanup install instructions
authored
80 # app/controllers/application_controller.rb
18263e7 @grosser switched to use FastGettext for translation, enhanced parser, reduced…
authored
81 class ApplicationController < ...
82 before_filter :set_gettext_locale
4569f39 @grosser initial
authored
83
84 Translating
85 ===========
66c0a72 @grosser readme: simplify, restructure headings, add rails3 instructions
authored
86 Performance is almost the same for all backends since translations are cached after first use.
87
88 ### Option A: .po files
89
90 FastGettext.add_text_domain 'app', :path => 'locale', :type => :po
91
4569f39 @grosser initial
authored
92 - use some _('translations')
93 - run `rake gettext:find`, to let GetText find all translations used
2d1a11b @grosser updated docs
authored
94 - (optional) run `rake gettext:store_model_attributes`, to parse the database for columns that can be translated
d8faf26 @grosser docs
authored
95 - if this is your first translation: `cp locale/app.pot locale/de/app.po` for every locale you want to use
66c0a72 @grosser readme: simplify, restructure headings, add rails3 instructions
authored
96 - translate messages in 'locale/de/app.po' (leave msgstr blank and msgstr == msgid)
97
98 New translations will be marked "fuzzy", search for this and remove it, so that they will be used.
d394c51 @grosser improved docs
authored
99 Obsolete translations are marked with ~#, they usually can be removed since they are no longer needed
4569f39 @grosser initial
authored
100
66c0a72 @grosser readme: simplify, restructure headings, add rails3 instructions
authored
101 #### Unfound translations with rake gettext:find
102 Dynamic translations like `_("x"+"u")` cannot be fond. You have 4 options:
103
104 - add `N_('xu')` somewhere else in the code, so the parser sees it
105 - add `N_('xu')` in a totally separate file like `locale/unfound_translations.rb`, so the parser sees it
106 - use the [gettext_test_log rails plugin ](http://github.com/grosser/gettext_test_log) to find all translations that where used while testing
107 - add a Logger to a translation Chain, so every unfound translations is logged ([example]((http://github.com/grosser/fast_gettext)))
45965c0 @grosser more docs and specs
authored
108
66c0a72 @grosser readme: simplify, restructure headings, add rails3 instructions
authored
109 ### Option B: Traditional .po/.mo files
110
111 FastGettext.add_text_domain 'app', :path => 'locale'
112
113 - follow Option A
114 - run `rake gettext:pack` to write binary GetText .mo files
115
116 ### Option C: Database
117 Most scalable method, all translators can work simultaneously and online.
118
59cfa49 @grosser add Nikos Dimitrakopoulos to contributors
authored
119 Easiest to use with the [translation database Rails engine](http://github.com/grosser/translation_db_engine).
45965c0 @grosser more docs and specs
authored
120 Translations can be edited under `/translation_keys`
121
66c0a72 @grosser readme: simplify, restructure headings, add rails3 instructions
authored
122 FastGettext::TranslationRepository::Db.require_models
123 FastGettext.add_text_domain 'app', :type => :db, :model => TranslationKey
e4f7403 @grosser documented new i18n link
authored
124
66c0a72 @grosser readme: simplify, restructure headings, add rails3 instructions
authored
125 I18n
126 ====
0a671d4 @grosser give the readme some looove
authored
127 I18n.locale <==> FastGettext.locale.to_sym
128 I18n.locale = :de <==> FastGettext.locale = 'de'
129
130 Any call to I18n that matches a gettext key will be translated through FastGettext.
45965c0 @grosser more docs and specs
authored
131
9a01681 @grosser validation message translations through :message possible (through tr…
authored
132 Namespaces
133 ==========
59cfa49 @grosser add Nikos Dimitrakopoulos to contributors
authored
134 Car|Model means Model in namespace Car.
9a01681 @grosser validation message translations through :message possible (through tr…
authored
135 You do not have to translate this into english "Model", if you use the
136 namespace-aware translation
137 s_('Car|Model') == 'Model' #when no translation was found
138
32890ae @grosser add xss option to readme
authored
139 XSS / html_safe
140 ===============
4152231 @grosser add my recommended fix for issue 17 html_safe vs String#%
authored
141 If you trust your translators and all your usages of % on translations:<br/>
32890ae @grosser add xss option to readme
authored
142 # config/environment.rb
143 GettextI18nRails.translations_are_html_safe = true
144
4152231 @grosser add my recommended fix for issue 17 html_safe vs String#%
authored
145 String % vs html_safe is buggy (can be used for XSS on 1.8 and is always non-safe in 1.9)<br/>
146 My recommended fix is: `require 'gettext_i18n_rails/string_interpolate_fix'`
147
148 - safe stays safe (escape added strings)
149 - unsafe stays unsafe (do not escape added strings)
150
9a01681 @grosser validation message translations through :message possible (through tr…
authored
151 ActiveRecord - error messages
152 =============================
c30d5cd @grosser added activerecord translations and parser
authored
153 ActiveRecord error messages are translated through Rails::I18n, but
154 model names and model attributes are translated through FastGettext.
9a01681 @grosser validation message translations through :message possible (through tr…
authored
155 Therefore a validation error on a BigCar's wheels_size needs `_('big car')` and `_('BigCar|Wheels size')`
c30d5cd @grosser added activerecord translations and parser
authored
156 to display localized.
157
9a01681 @grosser validation message translations through :message possible (through tr…
authored
158 The model/attribute translations can be found through `rake gettext:store_model_attributes`,
0a671d4 @grosser give the readme some looove
authored
159 (which ignores some commonly untranslated columns like id,type,xxx_count,...).
9a01681 @grosser validation message translations through :message possible (through tr…
authored
160
0a671d4 @grosser give the readme some looove
authored
161 Error messages can be translated through FastGettext, if the ':message' is a translation-id or the matching Rails I18n key is translated.
c30d5cd @grosser added activerecord translations and parser
authored
162
45965c0 @grosser more docs and specs
authored
163 ####Option A:
9a01681 @grosser validation message translations through :message possible (through tr…
authored
164 Define a translation for "I need my rating!" and use it as message.
165 validates_inclusion_of :rating, :in=>1..5, :message=>N_('I need my rating!')
45965c0 @grosser more docs and specs
authored
166
167 ####Option B:
9a01681 @grosser validation message translations through :message possible (through tr…
authored
168 validates_inclusion_of :rating, :in=>1..5
66c0a72 @grosser readme: simplify, restructure headings, add rails3 instructions
authored
169 Make a translation for the I18n key: `activerecord.errors.models.rating.attributes.rating.inclusion`
9a01681 @grosser validation message translations through :message possible (through tr…
authored
170
171 ####Option C:
45965c0 @grosser more docs and specs
authored
172 Add a translation to each config/locales/*.yml files
26d46ad @grosser updated docs
authored
173 en:
174 activerecord:
175 errors:
176 models:
177 rating:
178 attributes:
179 rating:
180 inclusion: " -- please choose!"
9a01681 @grosser validation message translations through :message possible (through tr…
authored
181 The [rails I18n guide](http://guides.rubyonrails.org/i18n.html) can help with Option B and C.
4569f39 @grosser initial
authored
182
183 Plurals
184 =======
0a671d4 @grosser give the readme some looove
authored
185 FastGettext supports pluralization
a3f332b @grosser docs
authored
186 n_('Apple','Apples',3) == 'Apples'
ba1e7f0 @grosser docs
authored
187
66c0a72 @grosser readme: simplify, restructure headings, add rails3 instructions
authored
188 Abnormal plurals like e.g. Polish that has 4 different can also be addressed, see [FastGettext Readme](http://github.com/grosser/fast_gettext)
ba1e7f0 @grosser docs
authored
189
91d6b12 @pupeno Move the discovery of files to translate to a method so that it can b…
pupeno authored
190 Customizing list of translatable files
191 ======================================
192 When you run
193
194 rake gettext:find
195
c69916c @rainux Added Slim support
rainux authored
196 by default the following files are going to be scanned for translations: {app,lib,config,locale}/**/*.{rb,erb,haml,slim}. If
91d6b12 @pupeno Move the discovery of files to translate to a method so that it can b…
pupeno authored
197 you want to specify a different list, you can redefine files_to_translate in the gettext namespace in a file like
198 lib/tasks/gettext.rake:
199
200 namespace :gettext do
201 def files_to_translate
c69916c @rainux Added Slim support
rainux authored
202 Dir.glob("{app,lib,config,locale}/**/*.{rb,erb,haml,slim,rhtml}")
91d6b12 @pupeno Move the discovery of files to translate to a method so that it can b…
pupeno authored
203 end
204 end
205
92ed1c3 @nubis changed readme for shameless gettext_i18n_rails_js plug
nubis authored
206 Using your translations from javascript
207 =======================================
208
209 If want to use your .PO files on client side javascript you should have a look at the [GettextI18nRailsJs](https://github.com/nubis/gettext_i18n_rails_js) extension.
210
59cfa49 @grosser add Nikos Dimitrakopoulos to contributors
authored
211 [Contributors](http://github.com/grosser/gettext_i18n_rails/contributors)
ba1e7f0 @grosser docs
authored
212 ======
ce7afb1 @grosser hacky haml parser replaced through superior gettext ruby parser, that…
authored
213 - [ruby gettext extractor](http://github.com/retoo/ruby_gettext_extractor/tree/master) from [retoo](http://github.com/retoo)
017ebda @grosser refactor ignored tables, add pwim to contributors
authored
214 - [Paul McMahon](http://github.com/pwim)
2b58bb1 @grosser add Anh Hai Trinh to contributors
authored
215 - [Duncan Mac-Vicar P](http://duncan.mac-vicar.com/blog)
216 - [Ramihajamalala Hery](http://my.rails-royce.org)
217 - [J. Pablo Fernández](http://pupeno.com)
218 - [Anh Hai Trinh](http://blog.onideas.ws)
a1c4b13 @grosser add ed0h to contributors
authored
219 - [ed0h](http://github.com/ed0h)
59cfa49 @grosser add Nikos Dimitrakopoulos to contributors
authored
220 - [Nikos Dimitrakopoulos](http://blog.nikosd.com)
284c69c @grosser add Ben Tucker to contributors
authored
221 - [Ben Tucker](http://btucker.net/)
dc7e25b @grosser add Kamil Śliwak to contributors
authored
222 - [Kamil Śliwak](https://github.com/cameel)
8d33a59 @grosser add Paul McMahon to contributors, thanks for the patch
authored
223 - [Paul McMahon](https://github.com/pwim)
19f9a5e @grosser add Rainux Luo to contributors, thanks for slim parsing
authored
224 - [Rainux Luo](https://github.com/rainux)
1c75467 @grosser add Lucas Hills to ontributors, thanks for the patch
authored
225 - [Lucas Hills](https://github.com/2potatocakes)
f3ff4fe @grosser add Ladislav Slezák to contributors, thanks for the simple patch :)
authored
226 - [Ladislav Slezák](https://github.com/lslezak)
f372848 @grosser add Greg Weber to contributers, thanks for the patch
authored
227 - [Greg Weber](https://github.com/gregwebs)
4b9e9b9 @grosser add Sean Kirby to contributors, thanks for all the great commits
authored
228 - [Sean Kirby](https://github.com/sskirby)
4c7811c @grosser thanks for helping me to figure this stuff out :D
authored
229 - [Julien Letessier](https://github.com/mezis)
230 - [Seb Bacon](https://github.com/sebbacon)
45f36df @grosser thanks for the patch Ramón!
authored
231 - [Ramón Cahenzli](https://github.com/psy-q)
ce7afb1 @grosser hacky haml parser replaced through superior gettext ruby parser, that…
authored
232
4152231 @grosser add my recommended fix for issue 17 html_safe vs String#%
authored
233 [Michael Grosser](http://grosser.it)<br/>
234 grosser.michael@gmail.com<br/>
2745478 @grosser update readme reference to MIT
authored
235 License: MIT
Something went wrong with that request. Please try again.