Skip to content
Internationalisation (i18n) and localisation support for Roda apps [].
Branch: master
Clone or download

Latest commit

Fetching latest commit…
Cannot retrieve the latest commit at this time.


Type Name Latest commit message Commit time
Failed to load latest commit information.


Gem Version Build Status

Add Internationalisation (i18n) and localisation support to your Roda apps, based upon the R18n gem.

Extensively tested and with 100% code test coverage.


To use this gem, just do

  $ (sudo) gem install roda-i18n

or if you use Bundler

gem "roda-i18n"

Getting Started

To add internationalisation and localisation support to your app just add the following code snippet in your app.

plugin :i18n

By default the default locale is set to 'en' and the translations directory is set to the 'i18n' directory in the root of your app, ie: '/path/2/app/i18n'.

IMPORTANT! Make sure you create the 'i18n' folder and add an 'en.yml' file with at least one translation within it.



Overriding defaults during configuration

Both :locale and :translations can be configured (overridden) during plugin configuration:

plugin :i18n, :locale => ['de'], :translations => ['absolute/path/2/i18n']


  1. You must set opts[:root] in your app if you do not define the :translations path during plugin configuration.

  2. When overriding :translations the any path(s) given must be absolute.

Loading translations from multiple i18n directories

The :translations path supports 'wildcards', ie: path/**/i18n so you can load translations from multiple combined apps, each with their own i18n folder with translations.

Please Note!

When loading translations from multiple sources and the same translation key is available in multiple files of the same locale, then the translations in the first loaded translation file takes precedence over subsequent loaded translations.

  • ie: translations in ./i18n/en.yml takes precedence over translations in ./apps/app1/i18n/en.yml

You can also set a list of preferred locales as an array ordered by priority.

plugin :i18n, :locale => ['es','fr','en']



The i18n plugin depends upon simple YAML based translations files:

 # app/i18n/en.yml

  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"'John') #=> "User name is John"
t.user.count(5)     #=> "There are 5 users"

t.does.not.exist | 'default' #=> "default"

...and the :l (lowercase L) instance method provides built-in localisations support:

l           #=> "03/01/2010 18:54"
l, :human   #=> "now"
l, :full    #=> "3rd of January, 2010 18:54"

Both the :t and :l methods are available within the route and template (erb) scopes. ie:

route do |r|
  r.root do

 # app/views/layout.erb
   <h1><%= t.welcome.message %></h1>

Please visit R18n for more information about the R18n gem used to create the above.


Key Methods / Functionality

#locale(opts = {}, &blk) - (request method)

This request method makes it easy to handle translations based upon the :locale prefix on a route / URL. ie:**de**/posts.

To enable this, just use the following code structure:

route do |r|
  # all routes are prefixed with '/:locale'
  # ie: GET /de/posts  => will use DE translations    
  # ie: GET /es/posts  => will use ES translations
  r.locale do          # also aliased as #i18n_locale 'posts' do 
    t.posts.header # use translations or locales

NOTE! Any URL / request with a non-present or not supported locale will be given the configured default locale or the EN (English) default locale.

#i18n_set_locale_from(type) - (request method)

Obtains the locale from either ENV, HTTP (browser), Params or Session values.

route do |r|
  # A): set from session[:locale] (if present)
  # B): set from URL params ie: GET /posts?locale=de
  # C): set from the browser's HTTP request locale
  # D): set from the server ENV['LANG'] variable
  r.i18n_set_locale_from(:ENV) 'posts' do 
    t.posts.header # use translations

NOTE! defaults to the configured default locale, or English, if the given locale type is invalid.

i18n_set_locale(locale, &blk) - (request method)

Enables overriding the default locale and setting a temporary :locale within a route block.

route do |r|
  # configured default locale
  r.i18n_set_locale('de') do
    # within this route block the locale is DE (German)
  r.i18n_set_locale('es') do
    # within this route block the locale is ES (Spanish)





This is the main translation output method. (See examples above)


Key localisation method. Handles dates etc. (See examples above)


Returns a two-dimensional array of available locales.

puts i18n_available_locales #=> [ ['en', 'English'], ...]


Class Methods


Return the i18n options for this class as a Hash.



A few ideas that may be outlandish, but possible?

Ability to load translations from multiple locations via an array.

plugin :i18n, :translations => ['app1/i18n', 'app2/i18n', 'app3/i18n']

Concept Reference

You can also set several loaders to merge translations from different sources:

R18n.default_places = [,, 'path/to/yaml']

Sequel DBLoader for DB based translations support

Som form of built-in support for storing / loading translations from a Sequel based DB.


  • Add better tests for Multiple Apps scenarios.

    • What happens if plugin is defined in multiple apps at the same time? and with different configurations?
  • Improve upon error handling and adding better tests of this functionality.

  • Add RDocs formatted README

  • ...and some more stuff that slipped my mind right now.




Copyright: 2015 - 2018 Kematzy

You can’t perform that action at this time.