Rails Internationalization (i18n) and Localization Guide

Configuring Rails Internationalization (i18n)

Rails internationalization requires three configuration steps: setting available locales, adding locale to your URLs, and making Rails load the correct locale for each request. You’ll also want to install the rails-i18n gem, which provides locale data like translated month names, pluralization rules, and default Rails error messages.

Set Available Locales

First, in config/application.rb, tell Rails which languages the app should support and set a default locale:

config.i18n.default_locale = :en
config.i18n.available_locales = [:en, :es, :de]

config.i18n.default_locale = :en
config.i18n.available_locales = [:en, :es, :de]

This configuration tells Rails:

• English (:en) is the default language
• The app supports English, Spanish, and German
• Users can switch between these three languages

You can add any language codes you need.

Add Locale to URLs

Next, add the locale to the URL so each language has its own path, like /en/time or /es/time:

# config/routes.rb
scope "/:locale" do
  get '/time', to: 'home#index', as: :time_display
end

# config/routes.rb
scope "/:locale" do
  get '/time', to: 'home#index', as: :time_display
end

This creates locale-specific URLs for your Rails application. Users can access different language versions by changing the locale parameter in the URL.

Configure Locale Switching

Finally, in app/controllers/application_controller.rb, make sure Rails loads the right locale from the URL and includes it in all links:

class ApplicationController < ActionController::Base
  around_action :switch_locale

  def switch_locale(&action)
    locale = params[:locale] || I18n.default_locale
    I18n.with_locale(locale, &action)
  end

  def default_url_options
    { locale: I18n.locale }
  end
end

class ApplicationController < ActionController::Base
  around_action :switch_locale

  def switch_locale(&action)
    locale = params[:locale] || I18n.default_locale
    I18n.with_locale(locale, &action)
  end

  def default_url_options
    { locale: I18n.locale }
  end
end

This code:

• Reads the locale from the URL parameter
• Falls back to the default locale if no parameter is present
• Ensures all generated URLs include the current locale

Install the rails-i18n Gem

The rails-i18n gem provides locale data for multiple languages, including translated month names, pluralization rules, and default Rails error messages. This saves you from translating these standard strings yourself.

Add it to your Gemfile:

gem 'rails-i18n'

Then run:

bundle install

Rails is now fully configured for internationalization.

Adding a Language Switcher

Now that your Rails app supports multiple locales, your global users need a way to switch between languages. Rails makes this simple because the default_url_options method in ApplicationController automatically includes the current locale in all generated URLs.

This means you can create a language switcher that only updates the locale parameter while keeping the user on the same page.

Create the Language Switcher UI

Add the language switcher to your layout file. In our demo app, the switcher is added in app/views/layouts/application.html.erb:

<nav>
  <%= link_to "English", url_for(locale: :en) %> |
  <%= link_to "Español", url_for(locale: :es) %> |
  <%= link_to "Deutsch", url_for(locale: :de) %>
</nav>

<nav>
  <%= link_to "English", url_for(locale: :en) %> |
  <%= link_to "Español", url_for(locale: :es) %> |
  <%= link_to "Deutsch", url_for(locale: :de) %>
</nav>

Each link uses url_for(locale: :locale_code) to generate a URL with the specified locale. When a user clicks a link:

• The switch_locale method in ApplicationController detects the change 
• Rails renders the page in the new language

Because you defined default_url_options in ApplicationController, Rails automatically includes the locale in all generated links. This means the locale persists as users navigate through your app. You don’t need to manually add locale parameters to every link.

Style Your Language Switcher

You can style the language switcher in app/assets/stylesheets/application.css to match your design. The demo app includes basic styling to make the switcher visible and user-friendly.

Setting Up Translation Keys in Rails Views

Before you can translate your app, all user-facing text needs to live in Rails i18n files instead of being hard-coded. Rails provides the t helper method (short for translate) to look up and display translated strings.

Replace Hard-Coded Text with Translation Keys

Rails uses the built-in I18n.t (or simply t) helper to look up strings from your translation files.

<h1><%= t(:hello) %></h1>
<p><%= t(:current_time, time: @time) %></p>
<button id="click-me"><%= t(:refresh) %></button>

<h1><%= t(:hello) %></h1>
<p><%= t(:current_time, time: @time) %></p>
<button id="click-me"><%= t(:refresh) %></button>

<h1>Hello</h1>
<p>Current time: <%= @time %></p>
<button>Refresh</button>

<h1>Hello</h1>
<p>Current time: <%= @time %></p>
<button>Refresh</button>

Hard-coded text won’t appear in your YAML file, which means it can’t be translated later. Always use translation keys for any user-facing text.

Using Interpolation in Translations

Notice the time: @time parameter in the example above? This is called interpolation. It lets you insert dynamic values into your translations. The translation string in your YAML file uses %{time} as a placeholder:

current_time: "Current time: %{time}"

current_time: "Current time: %{time}"

When you call the t helper with time: @time, Rails replaces %{time} with the actual value. You can use any variable names you want – just make sure they match between the YAML file and your view.

Lazy Lookup for Cleaner Code

When your translation keys are organized to match your view folder structure, Rails lets you use a shortcut called lazy lookup. Instead of writing the full key path, use a leading dot:

<!-- Instead of this: -->
<%= t('home.index.hello') %>

<!-- You can write this: -->
<%= t('.hello') %>

<!-- Instead of this: -->
<%= t('home.index.hello') %>

<!-- You can write this: -->
<%= t('.hello') %>

Rails looks at which view file you’re in (home/index.html.erb) and automatically adds home.index. in front of your key. This keeps your code cleaner and makes it easier to move views around. If you rename or relocate a view, the lazy lookup paths update automatically.

Creating and Organizing Translation Files

Now that you’ve added translation keys to your views, you need to define those keys in a YAML file. Rails stores these definitions in the config/locales/ directory.

Add Keys to Your English File

Rails translation files use a simple key-value structure. Open config/locales/en.yml and add the keys you referenced in your views:

# config/locales/en.yml
en:
  hello: "Hello"
  current_time: "Current time: %{time}"
  refresh: "Refresh"

# config/locales/en.yml
en:
  hello: "Hello"
  current_time: "Current time: %{time}"
  refresh: "Refresh"

In this Rails i18n structure:

• en is the language code (English)
• hello, current_time, and refresh are translation keys
• The strings on the right are the actual text
• %{time} is a placeholder for dynamic content (interpolation)

This is your source file. It contains all the text in your default language. Later in this tutorial, you’ll use PTC to automatically generate Spanish, German, and other language versions.

Organizing Keys with Nesting

To use lazy lookup (the .hello shortcut from the previous section), organize your keys to match your view folder structure:

en:
  home:
    index:
      hello: "Hello"
      current_time: "Current time: %{time}"
      refresh: "Refresh"

en:
  home:
    index:
      hello: "Hello"
      current_time: "Current time: %{time}"
      refresh: "Refresh"

This groups all translations for app/views/home/index.html.erb under home.index. Now you can use t('.hello') in that view instead of t('home.index.hello').

As your Rails application grows, you can also create namespaces for shared translations (like shared.navigation for menus) to keep things organized, but this is optional.

Add JavaScript Strings to YAML

Your Rails views are now internationalized, but what about JavaScript? Rails doesn’t automatically extract text from JavaScript files. If your application has client-side text like alerts, tooltips, or confirmation messages, you need to add them to your English translation file.

For example, to translate a confirmation popup, add the string to config/locales/en.yml:

# config/locales/en.yml
en:
  confirm: "Are you sure?"

# config/locales/en.yml
en:
  confirm: "Are you sure?"

At this point, your en.yml file contains all the text that appears in your app – both in Rails views and in JavaScript.

When you use PTC to translate your application (covered in the next section), these JavaScript strings will be translated along with everything else.