Leigh Halliday

Translating Your Ruby on Rails Application

published Nov 13, 2014


If you're planning to take over the world (or a smaller but no less noble task of taking over Canada), you'll either need to convince everyone to speak your language, or better yet, why don't you offer them a website that speaks their language. The goal is to have a website available in multiple languages, and for the visitors to be able to toggle over to the language they are most comfortable with.

What This Isn't

This isn't a replacement for having read the Rails guide to I18n which will explain things in more general terms. This is supposed to be more of a guide on how to set up the entire Rails application.


I like to nest all of my routes inside of a :locale scope. I also limit the locale options to a set that I have predefined in an initializer. You could also choose to deal with locale validity later on in the flow (before_action method), but it is up to you.

# config/routes.rb
scope "(:locale)", locale: /#{MySite::ROUTE_LOCALES.keys.join("|")}/ do
root :to => 'home#index'
resources :pages
# etc...
# config/initializers/my_site.rb
module MySite

MySite::LOCALES = {
en: "English",
fr: "French",
en_ca: "Canadian English",
en_us: "US English",
en_uk: "UK English",
fr_ca: "Canadian French",
fr_lu: "Luxembourg French"

MySite::ROUTE_LOCALES = MySite::LOCALES.keys.each_with_object({}) do |locale, hsh|
hsh[locale.to_s.tr("_","-")] = locale if locale.to_s.length > 2
# {"en-ca"=>:en_ca, "fr-ca"=>:fr_ca, "en-us"=>:en_us, "en-uk"=>:en_uk, "fr-lu"=>:fr_lu}

This line of code will make sure all of your routes have the current locale in them.

# app/controllers/application_controller.rb
def default_url_options(options={})
{ locale: I18n.locale }.merge(options)

Determining Locale

I usually have a before_action filter which does its best to determine the URL of the application. You might have other things in here too if you keep track of the preferred locale in a cookie, or if it is attached to the user's session data or account. You may also want to use the HTTP_ACCEPT_LANGUAGE to determine if there is a match.

class ApplicationController < ActionController::Base
before_action :determine_locale


def determine_locale
locale = if params.include?(:new_locale) && MySite::ROUTE_LOCALES.keys.include?(params[:new_locale])
elsif params.include?(:locale)
locale_from_url(request.host) || I18n.default_locale


def locale_from_url(host)
# ... determine locale from host if you have different domains
# for different locales

def set_locale(locale)
I18n.locale = locale.to_s.gsub("-","_").to_sym

Static Text

The developers should be entering their keys into the yml files located in the locales folder if your rails application. I normally only have one for English, and then use other I18n backends (Redis for example) serve up the other translations. If the translations are in Redis, you will obviously need code that puts them there. I am working on an engine for this called Idioma which persists the translations using ActiveRecord and also to Redis at the same time.

Dynamic Content

Because I18n comes built in to Rails, you won't need to install many gems. But for dynamic content I recommend Globalize. Along with this one is a handy gem called Globalize Accessors which will help you when creating forms to enter this data in.

class Page < ActiveRecord::Base

translates :title, :body, fallbacks_for_empty_translations: true
globalize_accessors locales: MySite::LOCALES.keys, attributes: [:title, :body]



One thing I set up are fallbacks... this is so you can translate English once, and only when there is a locale that differs from the default do you need to specifically translate it for that locale. Example, in the US colour is spelled like color.

# config/application.rb
config.i18n.default_locale = :en_ca
config.i18n.fallbacks = {
en_us: :en,
en_ca: :en,
en_uk: :en,
fr_lu: :fr,
fr_ca: :fr,
fr: :en

Having Your Website Translated

Because the translation team probably isn't the same as the dev team, and they probably don't have access to your code repository nor know how to edit yml files, you will want to have another way of giving them access to the translations. There is an established tool called Tolk and also a gem I am in the progress of building called Idioma. I'll write another full blog post on how to use my Idioma gem.