Step-by-Step Guide to Providing Multi-Language Support for Your Rails App

As your business scales, it may reach the international level. In order to cater to the needs of a global audience and to provide your customers with user-friendly service, your Rails app will need to support multiple languages, currencies, and date and time formats.

App internationalization is an old practice among developers, and there are different ways to deal with it. Working with clients whose businesses are sometimes international, we often deal with translating web apps and websites into different languages. In this article, we share our experience working with app internationalization. 

Types of web content 

Typically, a web app consists of static and dynamic content. Static content is a content delivered to users without having to be modified or generated, meaning it doesn’t depend on user input or preferences. Static web pages have fixed code and their content doesn’t change unless it’s manually edited by a web developer. A great example of a static web page is any of our blog post pages, where the content (the article text and all media) remains the same until we manually change it. 

Dynamic content (also known as adaptive content), in contrast, is web content that’s generated at the moment a user requests a web page and on the basis of their interactions with a web app as well as their preferences. Dynamic content is adapted based on data such as location and device type to deliver the most relevant and satisfying user experience. The brightest example of dynamic content is Uber’s blog. It decides which articles to show based on a user’s location.

Knowing what types of content exist will help us to better understand how internationalization and localization are applied. Now let’s get down to business and try to translate your web app.

Localizing static content 

For localizing static content, we’ll use the built-in Ruby I18n gem, which is a standard framework for translating content that’s supported in Ruby on Rails 2.2 and higher and used both to translate web apps into different languages, in order to extend cultural or linguistic market.

Localizing a Rails app with the Ruby I18n gem means defining translated values for static strings in the Rails framework in different languages.

Step 1. Set default configurations

This step involves setting a default locale and translation load paths as well as defining available locales in config/initializers/locales.rb.

The default locale refers to the locale that’s set automatically unless a different locale is detected. English is the default locale in the l18n gem.

In the following example, we set German as the default locale and enumerate available locales to make the web app available in German, English, and Portuguese. We also define the translation load path, which is the path to the folder where all locales are stored. 

# Where the I18n library should search for translation files

I18n.load_path += Dir[Rails.root.join('config', 'locales', '**', '*.{rb,yml}').to_s]

# Set default locale to something other than :en

I18n.default_locale = :de

# Whitelist locales available for the application

I18n.available_locales = [:de, :en, :pt]

Step 2. Determining locales

Now let’s move directly to determining a locale. You probably want your app to support multiple locales – such as:de, :en, and:pt– to reach different regions.

For this, you should set the locale at the beginning of each direct request to your web app or website so that all strings are translated using the desired locale during the lifetime of that request. In plain English, doing this will make your app show your users content in the language associated with the locale they’ve chosen.

You can choose between the following approaches for setting locales: 

1. Set a locale from the domain name. Here you can set the locale from a top-level domain name (, domain name (, or subdomain name (

Using a top-level domain name for setting a locale has several benefits. Following this approach, you’ll get a URL for your web app that looks like this:

The locale is an obvious component of the web app’s URL. Moreover, it’s better for SEO when content in different languages resides in separate but linked domains. This approach involves writing the following lines of code in ApplicationController:    

class ApplicationController < ActionController::Base 
  before_action :set_locale
  def set_locale
    I18n.locale = extract_locale_from_tld || I18n.default_locale
  def extract_locale_from_tld
    parsed_locale ='.').last ? parsed_locale : nil

Setting the locale from the domain name also improves SEO. In addition, this option enables you to directly translate the hostname to the user’s native language. By using this approach, you’ll get URLs like this:

To do this, first store application hosts in the config/application.rb file:

module ApplicationName

  class Application < Rails::Application

    config.hosts = {

      pt: ENV.fetch('HOST_PT', ''),

      de: ENV.fetch('HOST_DE', ''),

      en: ENV.fetch('HOST_EN', '')


Then, set the locale according to the hostname in ApplicationController:

class ApplicationController < ActionController::Base 

  before_action :set_locale_from_domain


  def set_locale_from_domain

    detected_locale = Rails.application.config.hosts.key(

    I18n.locale = detected_locale.present? ? detected_locale : I18n.default_locale



The locale is set in a similar manner when based on a subdomain name:

class ApplicationController < ActionController::Base 

  before_action :set_locale_from_subdomain 


  def set_locale_from_subdomain

    detected_locale = request.subdomains.first

    I18n.locale = ? detected_locale : I18n.default_locale



As a result, you’ll get URLs like this:

2. Set a locale using URL parameters

When setting a locale from URL parameters, the path to your service will look something like this:

Though setting a locale using URL parameters has the same benefits as setting a locale from a website domain name (it’s RESTful and complies with the rest of the internet), it requires more effort. First, add the following code to ApplicationController

class ApplicationController < ActionController::Base 

    before_action :set_locale


    def set_locale

        I18n.locale = params[:locale] || I18n.default_locale



Here’s where the tricky part begins. The chosen locale must persist across the requests. How we can deal with this? 

This problem can be solved by adding link_to root_url(locale: I18n.locale) after each request. This would be inconvenient, however, so you need to find another solution. As an alternative, you can add the default_url_options method, which sets default parameters for the url_for method and other methods that rely on it: 

    def default_url_options

      { locale: I18n.locale }


Thanks to this method, route helpers will automatically include the ?locale part to your web app’s URL. 

3. Store a locale in the path 

When storing a locale in the path, the URL of your app will look something like this: (uploads the German locale) (uploads the French locale)

For this, just add a few lines of code into config/routes.rb:

scope "(:locale)", locale: /#{I18n.available_locales.join("|")}/ do

  resources :cats


Step 3. Enabling automatic locale detection

There are two possible ways to get a locale implicitly. 

  •  Set a locale based on the user’s location

You can easily perform user’s locale detection from geolocation with geocoder gem. After that, the app will set the language that’s defined for this area. Geocoder adds location and safe_location methods to the standard Rack::Request object so you can easily look up the location of any HTTP request by IP address.

# returns Geocoder::Result object

result = request.location

We don’t recommend relying on this approach, though, since it’s considered quite inaccurate. For instance, suppose a user from Spain goes on vacation to Germany. When they enter your website while on vacation, they probably want to see it in Spanish and not in German, since they may not know German. 

  • Get required data from the HTTP Accept-Language header 

Part of an HTTP request, the HTTP Accept-Language header contains data about a user’s browser language preferences. This information can be sent to the app server so that it can determine the locale. Let’s get back to the example with a tourist from Spain. Your website can easily display the Spanish version to this tourist while they’re in Germany by relying on their browser language preferences (assuming they’re set to Spanish).

If you want your app to automatically detect a locale using information from the Accept-Language header, use this code:

def browser_locale(request)

   locales = request.env['HTTP_ACCEPT_LANGUAGE'] || ""

   locales.scan(/[a-z]{2}(?=;)/).find do |locale|




Step 4. Organizing translation files

All translations of static strings can be stored in YAML (.yml) or plain Ruby (.rb) files. Commonly, Ruby developers use YAML for this purpose. But this option has one huge drawback: *.yml files are sensitive to white space and special characters. Pay close attention to them or you’ll face problems with loading dictionaries.

Yalantis has also prepared some useful tips on how to localize an app. 

Tip #1. Store each locale in a separate file. For instance, here we have two separate files with English and German translations stored in config/locales.

# config/locales/en.yml

  help: ‘Help’

# config/locales/de.yml

  help: ‘Hilfe’

To quickly find translations, it’s better to split your static string content into different files stored in separate folders. For instance:


Tip #2. After you’ve finished organizing files, look inside those files and put translation keys in order. First and foremost, we recommend giving clear names to your translation keys so it’s easy to understand their purpose. For example:



    change_my_password: Change my password

Tip #3. Don’t store all translation keys at the same level of nesting. This is a bad solution since similar keys will get messed up. For instance, you’d better not write code like this:

    submit: Submit
    log_out: Log Out
    blog: Blog
    errors: Errors were found:

Instead, it’s good solution to organize information in the following way:

      submit: Submit
      errors: Errors were found
      log_out: Log Out
      blog: Blog

Tip #4. Use variables to interpolate keys with values. For example, to allow notifications_count to accept a variable, use the following approach:

  zero: 'no notifications'
  one: 'one notification'
  few: "%{count} notifications"
  many: "%{count} notifications"
  other: '%{count} notifications'

And use it in the following way:

t(:inbox, count: 2) # => '2 notifications'
t(:inbox, count: 1) # => 'one notification'
t(:inbox, count: 0) # => 'no notifications'

Tip #5. Mind that the time format is different in different regions. Some regions use a 24-hour clock instead of 12-hour. The same situation with date format. For instance, DD/MM/YYYY format is used in most Asian countries, Russia, and some European countries, while in the US the MM/DD/YYYY format is used. 

      default: "%Y-%m-%d"
      short: "%b %d"
      long: "%B %d, %Y"
      default: "%H:%M:%S"
      short: "%H:%M"
      long: "%H:%M:%S, %d %B"

To localize a date or time, use the localize method (aliased as l):

l(post.created_at, format: :long)

Tip #6. Use lazy lookups — short versions of commands that let you write less code inside controllers and views. 
For instance, if you’re translating the app/views/cats/show.html.erb view, there’s no need to write the full path to the translation key. Instead, you can write:

<%= t('') %>

# Change to 

<%= t(:title) %>

Before using lazy lookups, however, make sure you store translation keys with the following nesting:

      title: Cats show page title

Tip #7. All static strings should be translated. So don’t forget to translate enums and model attributes:

        first_name: First Name
          female: Female
          male: Male

as well as error messages:


Tip #8. Bear in mind that machine translation may have imperfections, which is why it’s sometimes better to work with experts who can localize your web app. You can use third-party services like PhraseApp,, LocaleApp, and Translation Exchange to have native speakers translate your static strings.

Localizing dynamic content 

Localizing of dynamic content is important since it helps you deliver a personalized user experience. The Globalize gem is a perfect solution for localizing dynamic content. You can find detailed documentation of this gem in the Github repository. There are a few key points from this document to be pointed out. 
Yalantis has experience localizing a project with dynamic content, so let’s use this example to show the localization process.

Our task was to localize the content on a travel platform. In the admin panel, a publisher can choose and populate input fields in English, French, or German. Depending on the locale, the web app shows content in English, French, or German. We used the Article model with a Title field, and publishers need to fill in this title so that the app can display the relevant title on each version of the website. 

Article model

The localization process included the following steps:

1. Add the 'globalize’ gem line to the Gemfile and run bundle install:

gem 'globalize', '~> 5.0.0'

2. Enumerate the attributes to be translated:

class Product < ActiveRecord::Base

  translates :name, :description, fallbacks_for_empty_translations: true


3. Add  migration to TranslateProducts to generate the translation tables that will store product translations:

class TranslateProducts < ActiveRecord::Migration[5.0]

  def self.up



  def self.down




After that, we get access to translated attributes:

I18n.locale = :en # => My product name

I18n.locale = :fr # => Mon nom de produit

Translating routes 

If you have a web app with multi-language support, you may want to translate routes as well. What does that mean? 

Imagine you have a web app in English and German with a Help page. Without translated routes, the URLs will look like this:

But after we translate routes, we’ll get translated pages:

First, if you want a single Rails app to serve multiple domains in different languages, you need to configure NGINX like this:

server {

  listen 80;


  root /webapps/mycook/public;

You can change URLs to display whatever language is requested using the route_translator gem. This gem allows you to manage translations of your app routes with a simple dictionary format. With routes_translator, you can configure localized hosts, locale detection, route namespaces, and so on. The gem has well-written official guides and documentation. We’ll consider only the initial steps of localizing routes:

1. Add the gem to your Gemfile and run bundle install:

gem 'route_translator'

2. Put the groups of routes to be translated inside a localized block:

Rails.application.routes.draw do

  namespace :admin do

    resources :cats


  localized do

    resources :cats



3. Add translations to the locale files (en.yml, fr.yml):

    cats: cats
    new: new

    cats: chats
    new: nouveau

Voila, you have localized routes!

cats_fr GET   /fr/chats(.:format)        cats#index {:locale=>"fr"}
cats_en GET   /cats(.:format)            cats#index {:locale=>"en"}

If your routes have slugs like /products/259-green-shoe, you might want them to be converted to slugs such as /produits/259-chaussures-vertes. For this purpose, use friendly_id-globalize. This gem lets you use Globalize to translate slugs in your models. Using this gem is as easy as pie.

1. Add the gem to the Gemfile:

gem friendly_id-globalize

2. Run a command from the terminal in the project directory to generate migration:

rails generate friendly_id_globalize

3. List slugs that need to be localized:

class Product < ActiveRecord::Base

  translates :name, :description, :slug

  extend FriendlyId

  friendly_id :name, use: :globalize


Now you can find models by slug!

I18n.locale = :fr


I18n.locale = :en


The bottom line

As you can see, there are technical solutions that can help you take your project global and localize its static and dynamic content in a few simple steps. In this article, we’ve overviewed the process of localizing web applications built with Ruby on Rails using native tools offered by the platform and applying open-source libraries provided by the Rails community. If you have any questions or want to create an app supporting multiple languages, get in touch and we’ll find the solution together.

4.5/ 5.0
Article rating
Remember those Facebook reactions? Well, we aren't Facebook but we love reactions too. They can give us valuable insights on how to improve what we're doing. Would you tell us how you feel about this article?
Have a web app in mind?

Let's disrupt the web world together

Contact us

We use cookies to personalize our service and to improve your experience on the website and its subdomains. We also use this information for analytics.