Module: Roda::RodaPlugins::RodaI18n

Defined in:
lib/roda/plugins/i18n.rb

Overview

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

Defined Under Namespace

Modules: ClassMethods, InstanceMethods, RequestMethods

Constant Summary collapse

OPTS =

default options

{
  # set the default locale
  locale:           'en',
  # set the default fallback locale
  default_locale:   'en',
  # set the default translations.
  translations:     nil
}.freeze

Class Method Summary collapse

Class Method Details

.configure(app, opts = OPTS) ⇒ Object 



140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
 
# File 'lib/roda/plugins/i18n.rb', line 140

def self.configure(app, opts = OPTS)
  if app.opts[:i18n]
    opts = app.opts[:i18n][:orig_opts].merge(opts)
  else
    opts = OPTS.merge(opts)
  end
  
  app.opts[:i18n]             = opts.dup
  app.opts[:i18n][:orig_opts] = opts
  opts = app.opts[:i18n]
  
  # set the translations path to defaults if nil
  opts[:translations] = File.expand_path('i18n', app.opts[:root]) if opts[:translations].nil?
  ::R18n.default_places = opts[:translations]
  
  # default_locale is either 'en' or the set value, so reset :default_locale if 
  # it is somehow nil or an empty string ' '
  if opts[:default_locale].nil? || opts[:default_locale] =~ /^\s*$/
    opts[:default_locale] = 'en'
  end
  ::R18n::I18n.default = opts[:default_locale]
  
  ::R18n.clear_cache! if ENV['RACK_ENV'] != 'production'
  i18n   = R18n::I18n.new(
    opts[:locale], 
    ::R18n.default_places,
    off_filters:  :untranslated,
    on_filters:   :untranslated_html
  )
  ::R18n.set(i18n)
end