module Roda::RodaPlugins::RodaI18n
The i18n plugin allows you to easily add internationalisation (i18n) and localisation support to your Roda
app, by adding the following:
plugin :i18n
By default the default locale is set to 'en'
and the translations directory is set to 'i18n'
in the rooot of your app.
Both :locale
and :translations
can be overridden during configuration:
plugin :i18n, :locale => ['de'], :translations => ['absolute/path/2/i18n']
Please note!
1) You must set +opts[:root]+ in your app if you don't define the +:translations+ path.
2) When overriding :translations
the path given must be absolute.
The path supports 'wildcards', ie: path/**/i18n so you can load translations from multiple combined apps each with their own i18n
folder with translations.
Note! when loading translations from multiple sources and the same translation key is used in both files, the first loaded file takes precedence, ie: ./i18n/en.yml
takes precedence over ./apps/app1/i18n/en.yml
USAGE¶ ↑
The i18n plugin depends upon simple YAML based translations files:
# app/i18n/en.yml user: edit: Edit user name: User name is %1 count: !!pl 1: There is 1 user n: There are %1 users
and the :t
instance method to output the translations:
t.user.edit #=> "Edit user" t.user.name('John') #=> "User name is John" t.user.count(5) #=> "There are 5 users" t.does.not.exist | 'default' #=> "default"
the :l
instance method provides built-in localisations support:
l Time.now #=> "03/01/2010 18:54" l Time.now, :human #=> "now" l Time.now, :full #=> "3rd of January, 2010 18:54"
Both the :t
and :l
methods are available in the route and template (erb) scopes. ie:
route do |r| r.root do t.welcome.message end end # app/views/layout.erb <snip...> <h1><%= t.welcome.message %></h1> <snip...>
Visit [R18n](github.com/ai/r18n/tree/master/r18n-core) for more information.
The i18n plugin also makes it easy to handle locales:
:locale
RequestMethod¶ ↑
This request method makes it to handle translations based upon the :locale prefix on a URL,
ie: <tt>blog.com/de/posts</tt>, just use the following code: route do |r| r.locale do # or r.i18n_locale r.is 'posts' do t.posts.header end end end
:i18n_set_locale_from
RequestMethod¶ ↑
Obtains the locale from either ENV, HTTP (browser), Params or Session values
Naturally we can allow browsers to override the default locale within routes, like this:
route do |r| i18n_set_locale_from(:http) #=> set to the browser's default locale (en-US) r.get '' do t.hello #=> 'Howdy, I speak American English' end end
The def
route do |r| i18n_set_locale('de') r.get 'in-german' do t.hello #=> 'Guten tag, ich spreche deutsch' end end
Constants
- OPTS
default options
Public Class Methods
# File lib/roda/plugins/i18n.rb 140 def self.configure(app, opts = OPTS) 141 if app.opts[:i18n] 142 opts = app.opts[:i18n][:orig_opts].merge(opts) 143 else 144 opts = OPTS.merge(opts) 145 end 146 147 app.opts[:i18n] = opts.dup 148 app.opts[:i18n][:orig_opts] = opts 149 opts = app.opts[:i18n] 150 151 # set the translations path to defaults if nil 152 opts[:translations] = File.expand_path('i18n', app.opts[:root]) if opts[:translations].nil? 153 ::R18n.default_places = opts[:translations] 154 155 # default_locale is either 'en' or the set value, so reset :default_locale if 156 # it is somehow nil or an empty string ' ' 157 if opts[:default_locale].nil? || opts[:default_locale] =~ /^\s*$/ 158 opts[:default_locale] = 'en' 159 end 160 ::R18n::I18n.default = opts[:default_locale] 161 162 ::R18n.clear_cache! if ENV['RACK_ENV'] != 'production' 163 i18n = R18n::I18n.new( 164 opts[:locale], 165 ::R18n.default_places, 166 off_filters: :untranslated, 167 on_filters: :untranslated_html 168 ) 169 ::R18n.set(i18n) 170 end