Rails 国际化 API

Rails 国际化 API

Rails 内建支持 Ruby I18n（internationalization 的简写）。Ruby I18n 这个 gem 用法简单，是个扩展性强的框架，可以把程序翻译成英语之外的其他语言，或者为程序提供多种语言支持。

“国际化”是指把程序中的字符串或者其他需要本地化的内容（例如，日期和货币的格式）提取出来的过程。“本地化”是指把提取出来的内容翻译成本地语言或者本地所用格式的过程。

所以在 Rails 程序国际化的过程中要做这些事情：

• 确保程序支持 i18n；
• 告诉 Rails 在哪里寻找本地语言包；
• 告诉 Rails 怎么设置、保存和切换本地语言包；

在本地化程序的过程中或许要做以下三件事：

• 修改或提供 Rails 默认使用的本地语言包，例如，日期和时间的格式、月份名、Active Record 模型名等；
• 把程序中的字符串提取出来，保存到键值对中，例如 Flash 消息、视图中的纯文本等；
• 在某个地方保存语言包；

本文会详细介绍 I18n API，并提供一个教程，演示如何从头开始国际化一个 Rails 程序。

读完本文，你将学到：

• Ruby on Rails 是如何处理 i18n 的；
• 如何在 REST 架构的程序中正确使用 i18n；
• 如何使用 i18n 翻译 ActiveRecord 错误和 ActionMailer E-mail；
• 协助翻译程序的工具；

Ruby I18n 框架提供了 Rails 程序国际化和本地化所需的各种功能。不过，还可以使用各种插件和扩展，添加额外的功能。详情参见 Ruby I18n 的维基。

1 Ruby on Rails 是如何处理 i18n 的

国际化是个很复杂的问题。自然语言千差万别（例如复数变形规则），很难提供一种工具解决所有问题。因此，Rails I18n API 只关注：

• 默认支持和英语类似的语言；
• 让支持其他语言变得简单；

Rails 框架中的每个静态字符串（例如，Active Record 数据验证消息，日期和时间的格式）都支持国际化，因此本地化时只要重写默认值即可。

1.1 Ruby I18n 的整体架构

Ruby I18n 分成两部分：

• 公开的 API：这是一个 Ruby 模块，定义了库中可用的公开方法；
• 一个默认的后台（特意取名为“Simple”），实现这些方法；

普通用户只要使用这些公开方法即可，但了解后台的功能也有助于使用 i18n API。

默认提供的“Simple”后台可以用其他强大的后台替代（推荐这么做），例如把翻译后的数据存储在关系型数据库中，或 GetText 语言包中。详情参见下文的“使用其他后台”一节。

1.2 公开 API

I18n API 最重要的方法是：

translate # Lookup text translations
localize  # Localize Date and Time objects to local formats

这两个方法都有别名，分别为 #t 和 #l。因此可以这么用：

I18n.t 'store.title'
I18n.l Time.now

I18n API 同时还提供了针对下述属性的读取和设值方法：

load_path         # Announce your custom translation files
locale            # Get and set the current locale
default_locale    # Get and set the default locale
exception_handler # Use a different exception_handler
backend           # Use a different backend

下一节起，我们要从零开始国际化一个简单的 Rails 程序。

2 为国际化做准备

为程序提供 I18n 支持只需简单几步。

2.1 配置 I18n 模块

按照“多约定，少配置”原则，Rails 会为程序提供一些合理的默认值。如果想使用其他设置，可以很容易的改写默认值。

Rails 会自动把 config/locales 文件夹中所有 .rb 和 .yml 文件加入译文加载路径。

默认提供的 en.yml 文件中包含一些简单的翻译文本：

en:
  hello: "Hello world"

上面这段代码的意思是，在 :en 语言中，hello 键映射到字符串 "Hello world" 上。Rails 中的每个字符串的国际化都使用这种方式，比如说 Active Model 数据验证消息以及日期和时间格式。在默认的后台中，可以使用 YAML 或标准的 Ruby Hash 存储翻译数据。

I18n 库使用的默认语言是英语，所以如果没设为其他语言，就会用 :en 查找翻译数据。

经过讨论之后，i18n 库决定为语言名称使用一种务实的方案，只说明所用语言（例如，:en，:pl），不区分地区（例如，:en-US，:en-GB）。地区经常用来区分同一语言在不同地区的分支或者方言。很多国际化程序只使用语言名称，例如 :cs、:th 和 :es（分别为捷克语，泰语和西班牙语）。不过，同一语种在不同地区可能有重要差别。例如，在 :en-US 中，货币符号是“$”，但在 :en-GB 中是“£”。在 Rails 中使用区分地区的语言设置也是可行的，只要在 :en-GB 中使用完整的“English - United Kingdom”即可。很多 Rails I18n 插件，例如 Globalize3，都可以实现。

译文加载路径（I18n.load_path）是一个 Ruby 数组，由译文文件的路径组成，Rails 程序会自动加载这些文件。你可以使用任何一个文件夹，任何一种文件命名方式。

首次加载查找译文时，后台会惰性加载这些译文。这么做即使已经声明过，也可以更换所用后台。

application.rb 文件中的默认内容有介绍如何从其他文件夹中添加本地数据，以及如何设置默认使用的语言。去掉相关代码行前面的注释，修改即可。

# The default locale is :en and all translations from config/locales/*.rb,yml are auto loaded.
# config.i18n.load_path += Dir[Rails.root.join('my', 'locales', '*.{rb,yml}').to_s]
# config.i18n.default_locale = :de

2.2 （选做）更改 I18n 库的设置

如果基于某些原因不想使用 application.rb 文件中的设置，我们来介绍一下手动设置的方法。

告知 I18n 库在哪里寻找译文文件，可以在程序的任何地方指定加载路径。但要保证这个设置要在加载译文之前执行。我们可能还要修改默认使用的语言。要完成这两个设置，最简单的方法是把下面的代码放到一个初始化脚本中：

# in config/initializers/locale.rb

# tell the I18n library where to find your translations
I18n.load_path += Dir[Rails.root.join('lib', 'locale', '*.{rb,yml}')]

# set default locale to something other than :en
I18n.default_locale = :pt

2.3 设置并传入所用语言

如果想把 Rails 程序翻译成英语（默认语言）之外的其他语言，可以在 application.rb 文件或初始化脚本中设置 I18n.default_locale 选项。这个设置对所有请求都有效。

不过，或许你希望为程序提供多种语言支持。此时，需要在请求中指定所用语言。

你可能想过把用户选择适用的语言保存在会话或 cookie 中，请千万别这么做。所用语言应该是透明的，写在 URL 中。这样做不会破坏用户对网页内容的预想，如果把 URL 发给一个朋友，他应该看到和我相同的内容。这种方式在 REST 架构中很容易实现。不过也有不适用 REST 架构的情况，后文会说明。

设置所用语言的方法很简单，只需在 ApplicationController 的 before_action 中作如下设定即可：

before_action :set_locale

def set_locale
  I18n.locale = params[:locale] || I18n.default_locale
end

使用这种方法要把语言作为 URL 查询参数传入，例如 http://example.com/books?locale=pt（这是 Google 使用的方法）。http://localhost:3000?locale=pt 会加载葡萄牙语，http://localhost:3000?locale=de 会加载德语，以此类推。如果想手动在 URL 中指定语言再刷新页面，可以跳过后面几小节，直接阅读“国际化程序”一节。

当然了，你可能并不想手动在每个 URL 中指定语言，或者想使用其他形式的 URL，例如 http://example.com/pt/books 或 http://example.com/en/books。下面分别介绍其他各种设置语言的方法。

2.4 使用不同的域名加载不同的语言

设置所用语言可以通过不同的域名实现。例如，www.example.com 加载英语内容，www.example.es 加载西班牙语内容。这里使用的是不同的顶级域名。这么做有多个好处：

• 所用语言在 URL 中很明显；
• 用户很容易得知所查看内容使用的语言；
• 在 Rails 中可以轻松实现；
• 搜索引擎似乎喜欢把不同语言的内容放在不同但相互关联的域名上；

在 ApplicationController 中加入如下代码可以实现这种处理方式：

before_action :set_locale

def set_locale
  I18n.locale = extract_locale_from_tld || I18n.default_locale
end

# Get locale from top-level domain or return nil if such locale is not available
# You have to put something like:
#   127.0.0.1 application.com
#   127.0.0.1 application.it
#   127.0.0.1 application.pl
# in your /etc/hosts file to try this out locally
def extract_locale_from_tld
  parsed_locale = request.host.split('.').last
  I18n.available_locales.include?(parsed_locale.to_sym) ? parsed_locale : nil
end

类似地，还可以使用不同的二级域名提供不同语言的内容：

# Get locale code from request subdomain (like http://it.application.local:3000)
# You have to put something like:
#   127.0.0.1 gr.application.local
# in your /etc/hosts file to try this out locally
def extract_locale_from_subdomain
  parsed_locale = request.subdomains.first
  I18n.available_locales.include?(parsed_locale.to_sym) ? parsed_locale : nil
end

如果程序中需要切换语言的连接，可以这么写：

link_to("Deutsch", "#{APP_CONFIG[:deutsch_website_url]}#{request.env['REQUEST_URI']}")

上述代码假设 APP_CONFIG[:deutsch_website_url] 的值为 http://www.application.de。

这种方法虽有种种好处，但你或许不想在不同的域名上提供不同语言的内容。最好的实现方式肯定是在 URL 的参数中加上语言代码。

2.5 在 URL 参数中设置所用语言

The most usual way of setting (and passing) the locale would be to include it in URL params, as we did in the I18n.locale = params[:locale] before_action in the first example. We would like to have URLs like www.example.com/books?locale=ja or www.example.com/ja/books in this case.

This approach has almost the same set of advantages as setting the locale from the domain name: namely that it's RESTful and in accord with the rest of the World Wide Web. It does require a little bit more work to implement, though.

Getting the locale from params and setting it accordingly is not hard; including it in every URL and thus passing it through the requests is. To include an explicit option in every URL (e.g. link_to( books_url(locale: I18n.locale))) would be tedious and probably impossible, of course.

Rails contains infrastructure for "centralizing dynamic decisions about the URLs" in its ApplicationController#default_url_options, which is useful precisely in this scenario: it enables us to set "defaults" for url_for and helper methods dependent on it (by implementing/overriding this method).

We can include something like this in our ApplicationController then:

# app/controllers/application_controller.rb
def default_url_options(options={})
  logger.debug "default_url_options is passed options: #{options.inspect}\n"
  { locale: I18n.locale }
end

Every helper method dependent on url_for (e.g. helpers for named routes like root_path or root_url, resource routes like books_path or books_url, etc.) will now automatically include the locale in the query string, like this: http://localhost:3001/?locale=ja.

You may be satisfied with this. It does impact the readability of URLs, though, when the locale "hangs" at the end of every URL in your application. Moreover, from the architectural standpoint, locale is usually hierarchically above the other parts of the application domain: and URLs should reflect this.

You probably want URLs to look like this: www.example.com/en/books (which loads the English locale) and www.example.com/nl/books (which loads the Dutch locale). This is achievable with the "over-riding default_url_options" strategy from above: you just have to set up your routes with scoping option in this way:

# config/routes.rb
scope "/:locale" do
  resources :books
end

Now, when you call the books_path method you should get "/en/books" (for the default locale). An URL like http://localhost:3001/nl/books should load the Dutch locale, then, and following calls to books_path should return "/nl/books" (because the locale changed).

If you don't want to force the use of a locale in your routes you can use an optional path scope (denoted by the parentheses) like so:

# config/routes.rb
scope "(:locale)", locale: /en|nl/ do
  resources :books
end

With this approach you will not get a Routing Error when accessing your resources such as http://localhost:3001/books without a locale. This is useful for when you want to use the default locale when one is not specified.

Of course, you need to take special care of the root URL (usually "homepage" or "dashboard") of your application. An URL like http://localhost:3001/nl will not work automatically, because the root to: "books#index" declaration in your routes.rb doesn't take locale into account. (And rightly so: there's only one "root" URL.)

You would probably need to map URLs like these:

# config/routes.rb
get '/:locale' => 'dashboard#index'

Do take special care about the order of your routes, so this route declaration does not "eat" other ones. (You may want to add it directly before the root :to declaration.)

Have a look at two plugins which simplify work with routes in this way: Sven Fuchs's routing_filter and Raul Murciano's translate_routes.

2.6 Setting the Locale from the Client Supplied Information

In specific cases, it would make sense to set the locale from client-supplied information, i.e. not from the URL. This information may come for example from the users' preferred language (set in their browser), can be based on the users' geographical location inferred from their IP, or users can provide it simply by choosing the locale in your application interface and saving it to their profile. This approach is more suitable for web-based applications or services, not for websites - see the box about sessions, cookies and RESTful architecture above.

2.6.1 Using Accept-Language

One source of client supplied information would be an Accept-Language HTTP header. People may set this in their browser or other clients (such as curl).

A trivial implementation of using an Accept-Language header would be:

def set_locale
  logger.debug "* Accept-Language: #{request.env['HTTP_ACCEPT_LANGUAGE']}"
  I18n.locale = extract_locale_from_accept_language_header
  logger.debug "* Locale set to '#{I18n.locale}'"
end

private
  def extract_locale_from_accept_language_header
    request.env['HTTP_ACCEPT_LANGUAGE'].scan(/^[a-z]{2}/).first
  end

Of course, in a production environment you would need much more robust code, and could use a plugin such as Iain Hecker's http_accept_language or even Rack middleware such as Ryan Tomayko's locale.

2.6.2 Using GeoIP (or Similar) Database

Another way of choosing the locale from client information would be to use a database for mapping the client IP to the region, such as GeoIP Lite Country. The mechanics of the code would be very similar to the code above - you would need to query the database for the user's IP, and look up your preferred locale for the country/region/city returned.

2.6.3 User Profile

You can also provide users of your application with means to set (and possibly over-ride) the locale in your application interface, as well. Again, mechanics for this approach would be very similar to the code above - you'd probably let users choose a locale from a dropdown list and save it to their profile in the database. Then you'd set the locale to this value.

3 Internationalizing your Application

OK! Now you've initialized I18n support for your Ruby on Rails application and told it which locale to use and how to preserve it between requests. With that in place, you're now ready for the really interesting stuff.

Let's internationalize our application, i.e. abstract every locale-specific parts, and then localize it, i.e. provide necessary translations for these abstracts.

You most probably have something like this in one of your applications:

# config/routes.rb
Yourapp::Application.routes.draw do
  root to: "home#index"
end

# app/controllers/application_controller.rb
class ApplicationController < ActionController::Base
  before_action :set_locale

  def set_locale
    I18n.locale = params[:locale] || I18n.default_locale
  end
end

# app/controllers/home_controller.rb
class HomeController < ApplicationController
  def index
    flash[:notice] = "Hello Flash"
  end
end

# app/views/home/index.html.erb
<h1>Hello World</h1>
<p><%= flash[:notice] %></p>

3.1 Adding Translations

Obviously there are two strings that are localized to English. In order to internationalize this code, replace these strings with calls to Rails' #t helper with a key that makes sense for the translation:

# app/controllers/home_controller.rb
class HomeController < ApplicationController
  def index
    flash[:notice] = t(:hello_flash)
  end
end

# app/views/home/index.html.erb
<h1><%=t :hello_world %></h1>
<p><%= flash[:notice] %></p>

When you now render this view, it will show an error message which tells you that the translations for the keys :hello_world and :hello_flash are missing.

Rails adds a t (translate) helper method to your views so that you do not need to spell out I18n.t all the time. Additionally this helper will catch missing translations and wrap the resulting error message into a <span class="translation_missing">.

So let's add the missing translations into the dictionary files (i.e. do the "localization" part):

# config/locales/en.yml
en:
  hello_world: Hello world!
  hello_flash: Hello flash!

# config/locales/pirate.yml
pirate:
  hello_world: Ahoy World
  hello_flash: Ahoy Flash

There you go. Because you haven't changed the default_locale, I18n will use English. Your application now shows:

And when you change the URL to pass the pirate locale (http://localhost:3000?locale=pirate), you'll get:

You need to restart the server when you add new locale files.

You may use YAML (.yml) or plain Ruby (.rb) files for storing your translations in SimpleStore. YAML is the preferred option among Rails developers. However, it has one big disadvantage. YAML is very sensitive to whitespace and special characters, so the application may not load your dictionary properly. Ruby files will crash your application on first request, so you may easily find what's wrong. (If you encounter any "weird issues" with YAML dictionaries, try putting the relevant portion of your dictionary into a Ruby file.)

3.2 Passing variables to translations

You can use variables in the translation messages and pass their values from the view.

# app/views/home/index.html.erb
<%=t 'greet_username', user: "Bill", message: "Goodbye" %>

# config/locales/en.yml
en:
  greet_username: "%{message}, %{user}!"

3.3 Adding Date/Time Formats

OK! Now let's add a timestamp to the view, so we can demo the date/time localization feature as well. To localize the time format you pass the Time object to I18n.l or (preferably) use Rails' #l helper. You can pick a format by passing the :format option - by default the :default format is used.

# app/views/home/index.html.erb
<h1><%=t :hello_world %></h1>
<p><%= flash[:notice] %></p
<p><%= l Time.now, format: :short %></p>

And in our pirate translations file let's add a time format (it's already there in Rails' defaults for English):

# config/locales/pirate.yml
pirate:
  time:
    formats:
      short: "arrrround %H'ish"

So that would give you:

Right now you might need to add some more date/time formats in order to make the I18n backend work as expected (at least for the 'pirate' locale). Of course, there's a great chance that somebody already did all the work by translating Rails' defaults for your locale. See the rails-i18n repository at GitHub for an archive of various locale files. When you put such file(s) in config/locales/ directory, they will automatically be ready for use.

3.4 Inflection Rules For Other Locales

Rails allows you to define inflection rules (such as rules for singularization and pluralization) for locales other than English. In config/initializers/inflections.rb, you can define these rules for multiple locales. The initializer contains a default example for specifying additional rules for English; follow that format for other locales as you see fit.

3.5 Localized Views

Let's say you have a BooksController in your application. Your index action renders content in app/views/books/index.html.erb template. When you put a localized variant of this template: index.es.html.erb in the same directory, Rails will render content in this template, when the locale is set to :es. When the locale is set to the default locale, the generic index.html.erb view will be used. (Future Rails versions may well bring this automagic localization to assets in public, etc.)

You can make use of this feature, e.g. when working with a large amount of static content, which would be clumsy to put inside YAML or Ruby dictionaries. Bear in mind, though, that any change you would like to do later to the template must be propagated to all of them.

3.6 Organization of Locale Files

When you are using the default SimpleStore shipped with the i18n library, dictionaries are stored in plain-text files on the disc. Putting translations for all parts of your application in one file per locale could be hard to manage. You can store these files in a hierarchy which makes sense to you.

For example, your config/locales directory could look like this:

|-defaults
|---es.rb
|---en.rb
|-models
|---book
|-----es.rb
|-----en.rb
|-views
|---defaults
|-----es.rb
|-----en.rb
|---books
|-----es.rb
|-----en.rb
|---users
|-----es.rb
|-----en.rb
|---navigation
|-----es.rb
|-----en.rb

This way, you can separate model and model attribute names from text inside views, and all of this from the "defaults" (e.g. date and time formats). Other stores for the i18n library could provide different means of such separation.

The default locale loading mechanism in Rails does not load locale files in nested dictionaries, like we have here. So, for this to work, we must explicitly tell Rails to look further:

  # config/application.rb
  config.i18n.load_path += Dir[Rails.root.join('config', 'locales', '**', '*.{rb,yml}')]

Do check the Rails i18n Wiki for list of tools available for managing translations.

4 Overview of the I18n API Features

You should have good understanding of using the i18n library now, knowing all necessary aspects of internationalizing a basic Rails application. In the following chapters, we'll cover it's features in more depth.

These chapters will show examples using both the I18n.translate method as well as the translate view helper method (noting the additional feature provide by the view helper method).

Covered are features like these:

• looking up translations
• interpolating data into translations
• pluralizing translations
• using safe HTML translations (view helper method only)
• localizing dates, numbers, currency, etc.

4.1 Looking up Translations

4.1.1 Basic Lookup, Scopes and Nested Keys

Translations are looked up by keys which can be both Symbols or Strings, so these calls are equivalent:

I18n.t :message
I18n.t 'message'

The translate method also takes a :scope option which can contain one or more additional keys that will be used to specify a "namespace" or scope for a translation key:

I18n.t :record_invalid, scope: [:activerecord, :errors, :messages]

This looks up the :record_invalid message in the Active Record error messages.

Additionally, both the key and scopes can be specified as dot-separated keys as in:

I18n.translate "activerecord.errors.messages.record_invalid"

Thus the following calls are equivalent:

I18n.t 'activerecord.errors.messages.record_invalid'
I18n.t 'errors.messages.record_invalid', scope: :active_record
I18n.t :record_invalid, scope: 'activerecord.errors.messages'
I18n.t :record_invalid, scope: [:activerecord, :errors, :messages]

4.1.2 Defaults

When a :default option is given, its value will be returned if the translation is missing:

I18n.t :missing, default: 'Not here'
# => 'Not here'

If the :default value is a Symbol, it will be used as a key and translated. One can provide multiple values as default. The first one that results in a value will be returned.

E.g., the following first tries to translate the key :missing and then the key :also_missing. As both do not yield a result, the string "Not here" will be returned:

I18n.t :missing, default: [:also_missing, 'Not here']
# => 'Not here'

4.1.3 Bulk and Namespace Lookup

To look up multiple translations at once, an array of keys can be passed:

I18n.t [:odd, :even], scope: 'errors.messages'
# => ["must be odd", "must be even"]

Also, a key can translate to a (potentially nested) hash of grouped translations. E.g., one can receive all Active Record error messages as a Hash with:

I18n.t 'activerecord.errors.messages'
# => {:inclusion=>"is not included in the list", :exclusion=> ... }

4.1.4 "Lazy" Lookup

Rails implements a convenient way to look up the locale inside views. When you have the following dictionary:

es:
  books:
    index:
      title: "Título"

you can look up the books.index.title value inside app/views/books/index.html.erb template like this (note the dot):

<%= t '.title' %>

Automatic translation scoping by partial is only available from the translate view helper method.

4.2 Interpolation

In many cases you want to abstract your translations so that variables can be interpolated into the translation. For this reason the I18n API provides an interpolation feature.

All options besides :default and :scope that are passed to #translate will be interpolated to the translation:

I18n.backend.store_translations :en, thanks: 'Thanks %{name}!'
I18n.translate :thanks, name: 'Jeremy'
# => 'Thanks Jeremy!'

If a translation uses :default or :scope as an interpolation variable, an I18n::ReservedInterpolationKey exception is raised. If a translation expects an interpolation variable, but this has not been passed to #translate, an I18n::MissingInterpolationArgument exception is raised.

4.3 Pluralization

In English there are only one singular and one plural form for a given string, e.g. "1 message" and "2 messages". Other languages (Arabic, Japanese, Russian and many more) have different grammars that have additional or fewer plural forms. Thus, the I18n API provides a flexible pluralization feature.

The :count interpolation variable has a special role in that it both is interpolated to the translation and used to pick a pluralization from the translations according to the pluralization rules defined by CLDR:

I18n.backend.store_translations :en, inbox: {
  one: 'one message',
  other: '%{count} messages'
}
I18n.translate :inbox, count: 2
# => '2 messages'

I18n.translate :inbox, count: 1
# => 'one message'

The algorithm for pluralizations in :en is as simple as:

entry[count == 1 ? 0 : 1]

I.e. the translation denoted as :one is regarded as singular, the other is used as plural (including the count being zero).

If the lookup for the key does not return a Hash suitable for pluralization, an 18n::InvalidPluralizationData exception is raised.

4.4 Setting and Passing a Locale

The locale can be either set pseudo-globally to I18n.locale (which uses Thread.current like, e.g., Time.zone) or can be passed as an option to #translate and #localize.

If no locale is passed, I18n.locale is used:

I18n.locale = :de
I18n.t :foo
I18n.l Time.now

Explicitly passing a locale:

I18n.t :foo, locale: :de
I18n.l Time.now, locale: :de

The I18n.locale defaults to I18n.default_locale which defaults to :en. The default locale can be set like this:

I18n.default_locale = :de

4.5 Using Safe HTML Translations

Keys with a '_html' suffix and keys named 'html' are marked as HTML safe. When you use them in views the HTML will not be escaped.

# config/locales/en.yml
en:
  welcome: <b>welcome!</b>
  hello_html: <b>hello!</b>
  title:
    html: <b>title!</b>

# app/views/home/index.html.erb
<div><%= t('welcome') %></div>
<div><%= raw t('welcome') %></div>
<div><%= t('hello_html') %></div>
<div><%= t('title.html') %></div>

Automatic conversion to HTML safe translate text is only available from the translate view helper method.

5 How to Store your Custom Translations

The Simple backend shipped with Active Support allows you to store translations in both plain Ruby and YAML format.²

For example a Ruby Hash providing translations can look like this:

{
  pt: {
    foo: {
      bar: "baz"
    }
  }
}

The equivalent YAML file would look like this:

pt:
  foo:
    bar: baz

As you see, in both cases the top level key is the locale. :foo is a namespace key and :bar is the key for the translation "baz".

Here is a "real" example from the Active Support en.yml translations YAML file:

en:
  date:
    formats:
      default: "%Y-%m-%d"
      short: "%b %d"
      long: "%B %d, %Y"

So, all of the following equivalent lookups will return the :short date format "%b %d":

I18n.t 'date.formats.short'
I18n.t 'formats.short', scope: :date
I18n.t :short, scope: 'date.formats'
I18n.t :short, scope: [:date, :formats]

Generally we recommend using YAML as a format for storing translations. There are cases, though, where you want to store Ruby lambdas as part of your locale data, e.g. for special date formats.

5.1 Translations for Active Record Models

You can use the methods Model.model_name.human and Model.human_attribute_name(attribute) to transparently look up translations for your model and attribute names.

For example when you add the following translations:

en:
  activerecord:
    models:
      user: Dude
    attributes:
      user:
        login: "Handle"
      # will translate User attribute "login" as "Handle"

Then User.model_name.human will return "Dude" and User.human_attribute_name("login") will return "Handle".

You can also set a plural form for model names, adding as following:

en:
  activerecord:
    models:
      user:
        one: Dude
        other: Dudes

Then User.model_name.human(count: 2) will return "Dudes". With count: 1 or without params will return "Dude".

5.1.1 Error Message Scopes

Active Record validation error messages can also be translated easily. Active Record gives you a couple of namespaces where you can place your message translations in order to provide different messages and translation for certain models, attributes, and/or validations. It also transparently takes single table inheritance into account.

This gives you quite powerful means to flexibly adjust your messages to your application's needs.

Consider a User model with a validation for the name attribute like this:

class User < ActiveRecord::Base
  validates :name, presence: true
end

The key for the error message in this case is :blank. Active Record will look up this key in the namespaces:

activerecord.errors.models.[model_name].attributes.[attribute_name]
activerecord.errors.models.[model_name]
activerecord.errors.messages
errors.attributes.[attribute_name]
errors.messages

Thus, in our example it will try the following keys in this order and return the first result:

activerecord.errors.models.user.attributes.name.blank
activerecord.errors.models.user.blank
activerecord.errors.messages.blank
errors.attributes.name.blank
errors.messages.blank

When your models are additionally using inheritance then the messages are looked up in the inheritance chain.

For example, you might have an Admin model inheriting from User:

class Admin < User
  validates :name, presence: true
end

Then Active Record will look for messages in this order:

activerecord.errors.models.admin.attributes.name.blank
activerecord.errors.models.admin.blank
activerecord.errors.models.user.attributes.name.blank
activerecord.errors.models.user.blank
activerecord.errors.messages.blank
errors.attributes.name.blank
errors.messages.blank

This way you can provide special translations for various error messages at different points in your models inheritance chain and in the attributes, models, or default scopes.

5.1.2 Error Message Interpolation

The translated model name, translated attribute name, and value are always available for interpolation.

So, for example, instead of the default error message "cannot be blank" you could use the attribute name like this : "Please fill in your %{attribute}".

• count, where available, can be used for pluralization if present:

5.1.3 Translations for the Active Record error_messages_for Helper

If you are using the Active Record error_messages_for helper, you will want to add translations for it.

Rails ships with the following translations:

en:
  activerecord:
    errors:
      template:
        header:
          one:   "1 error prohibited this %{model} from being saved"
          other: "%{count} errors prohibited this %{model} from being saved"
        body:    "There were problems with the following fields:"

In order to use this helper, you need to install DynamicForm gem by adding this line to your Gemfile: gem 'dynamic_form'.

5.2 Translations for Action Mailer E-Mail Subjects

If you don't pass a subject to the mail method, Action Mailer will try to find it in your translations. The performed lookup will use the pattern <mailer_scope>.<action_name>.subject to construct the key.

# user_mailer.rb
class UserMailer < ActionMailer::Base
  def welcome(user)
    #...
  end
end

en:
  user_mailer:
    welcome:
      subject: "Welcome to Rails Guides!"

5.3 Overview of Other Built-In Methods that Provide I18n Support

Rails uses fixed strings and other localizations, such as format strings and other format information in a couple of helpers. Here's a brief overview.

5.3.1 Action View Helper Methods

• distance_of_time_in_words translates and pluralizes its result and interpolates the number of seconds, minutes, hours, and so on. See datetime.distance_in_words translations.

• datetime_select and select_month use translated month names for populating the resulting select tag. See date.month_names for translations. datetime_select also looks up the order option from date.order (unless you pass the option explicitly). All date selection helpers translate the prompt using the translations in the datetime.prompts scope if applicable.

• The number_to_currency, number_with_precision, number_to_percentage, number_with_delimiter, and number_to_human_size helpers use the number format settings located in the number scope.

5.3.2 Active Model Methods

• model_name.human and human_attribute_name use translations for model names and attribute names if available in the activerecord.models scope. They also support translations for inherited class names (e.g. for use with STI) as explained above in "Error message scopes".

• ActiveModel::Errors#generate_message (which is used by Active Model validations but may also be used manually) uses model_name.human and human_attribute_name (see above). It also translates the error message and supports translations for inherited class names as explained above in "Error message scopes".

• ActiveModel::Errors#full_messages prepends the attribute name to the error message using a separator that will be looked up from errors.format (and which defaults to "%{attribute} %{message}").

5.3.3 Active Support Methods

• Array#to_sentence uses format settings as given in the support.array scope.

6 Customize your I18n Setup

6.1 Using Different Backends

For several reasons the Simple backend shipped with Active Support only does the "simplest thing that could possibly work" for Ruby on Rails³ ... which means that it is only guaranteed to work for English and, as a side effect, languages that are very similar to English. Also, the simple backend is only capable of reading translations but cannot dynamically store them to any format.

That does not mean you're stuck with these limitations, though. The Ruby I18n gem makes it very easy to exchange the Simple backend implementation with something else that fits better for your needs. E.g. you could exchange it with Globalize's Static backend:

I18n.backend = Globalize::Backend::Static.new

You can also use the Chain backend to chain multiple backends together. This is useful when you want to use standard translations with a Simple backend but store custom application translations in a database or other backends. For example, you could use the Active Record backend and fall back to the (default) Simple backend:

I18n.backend = I18n::Backend::Chain.new(I18n::Backend::ActiveRecord.new, I18n.backend)

6.2 Using Different Exception Handlers

The I18n API defines the following exceptions that will be raised by backends when the corresponding unexpected conditions occur:

MissingTranslationData       # no translation was found for the requested key
InvalidLocale                # the locale set to I18n.locale is invalid (e.g. nil)
InvalidPluralizationData     # a count option was passed but the translation data is not suitable for pluralization
MissingInterpolationArgument # the translation expects an interpolation argument that has not been passed
ReservedInterpolationKey     # the translation contains a reserved interpolation variable name (i.e. one of: scope, default)
UnknownFileType              # the backend does not know how to handle a file type that was added to I18n.load_path

The I18n API will catch all of these exceptions when they are thrown in the backend and pass them to the default_exception_handler method. This method will re-raise all exceptions except for MissingTranslationData exceptions. When a MissingTranslationData exception has been caught, it will return the exception's error message string containing the missing key/scope.

The reason for this is that during development you'd usually want your views to still render even though a translation is missing.

In other contexts you might want to change this behavior, though. E.g. the default exception handling does not allow to catch missing translations during automated tests easily. For this purpose a different exception handler can be specified. The specified exception handler must be a method on the I18n module or a class with #call method:

module I18n
  class JustRaiseExceptionHandler < ExceptionHandler
    def call(exception, locale, key, options)
      if exception.is_a?(MissingTranslation)
        raise exception.to_exception
      else
        super
      end
    end
  end
end

I18n.exception_handler = I18n::JustRaiseExceptionHandler.new

This would re-raise only the MissingTranslationData exception, passing all other input to the default exception handler.

However, if you are using I18n::Backend::Pluralization this handler will also raise I18n::MissingTranslationData: translation missing: en.i18n.plural.rule exception that should normally be ignored to fall back to the default pluralization rule for English locale. To avoid this you may use additional check for translation key:

if exception.is_a?(MissingTranslation) && key.to_s != 'i18n.plural.rule'
  raise exception.to_exception
else
  super
end

Another example where the default behavior is less desirable is the Rails TranslationHelper which provides the method #t (as well as #translate). When a MissingTranslationData exception occurs in this context, the helper wraps the message into a span with the CSS class translation_missing.

To do so, the helper forces I18n#translate to raise exceptions no matter what exception handler is defined by setting the :raise option:

I18n.t :foo, raise: true # always re-raises exceptions from the backend

7 Conclusion

At this point you should have a good overview about how I18n support in Ruby on Rails works and are ready to start translating your project.

If you find anything missing or wrong in this guide, please file a ticket on our issue tracker. If you want to discuss certain portions or have questions, please sign up to our mailing list.

8 Contributing to Rails I18n

I18n support in Ruby on Rails was introduced in the release 2.2 and is still evolving. The project follows the good Ruby on Rails development tradition of evolving solutions in plugins and real applications first, and only then cherry-picking the best-of-breed of most widely useful features for inclusion in the core.

Thus we encourage everybody to experiment with new ideas and features in plugins or other libraries and make them available to the community. (Don't forget to announce your work on our mailing list)

If you find your own locale (language) missing from our example translations data repository for Ruby on Rails, please fork the repository, add your data and send a pull request.

9 Resources

• rails-i18n.org - Homepage of the rails-i18n project. You can find lots of useful resources on the wiki.
• Google group: rails-i18n - The project's mailing list.
• GitHub: rails-i18n - Code repository for the rails-i18n project. Most importantly you can find lots of example translations for Rails that should work for your application in most cases.
• GitHub: i18n - Code repository for the i18n gem.
• Lighthouse: rails-i18n - Issue tracker for the rails-i18n project.
• Lighthouse: i18n - Issue tracker for the i18n gem.

10 Authors

• Sven Fuchs (initial author)
• Karel Minařík

If you found this guide useful, please consider recommending its authors on workingwithrails.

11 Footnotes

¹ Or, to quote Wikipedia: "Internationalization is the process of designing a software application so that it can be adapted to various languages and regions without engineering changes. Localization is the process of adapting software for a specific region or language by adding locale-specific components and translating text."

² Other backends might allow or require to use other formats, e.g. a GetText backend might allow to read GetText files.

³ One of these reasons is that we don't want to imply any unnecessary load for applications that do not need any I18n capabilities, so we need to keep the I18n library as simple as possible for English. Another reason is that it is virtually impossible to implement a one-fits-all solution for all problems related to I18n for all existing languages. So a solution that allows us to exchange the entire implementation easily is appropriate anyway. This also makes it much easier to experiment with custom features and extensions.