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

configure(app, opts = OPTS) click to toggle source
    # 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