rails-i18n Documentation

Install rails-i18n via your Gemfile or the command line based on your Ruby on Rails version. Note that Rails 3.0 or higher is required for gem installation. For Rails 2.x, use the Manual Installation method.

Gemfile examples

# For Rails >= 8.1.0
gem 'rails-i18n', '~> 8.1.0'

# For Rails >= 7.0.0
gem 'rails-i18n', '~> 7.0.0'

# For 6.x
gem 'rails-i18n', '~> 6.0'

# For 5.x
gem 'rails-i18n', github: 'svenfuchs/rails-i18n', branch: 'rails-5-x'

CLI installation examples

gem install rails-i18n -v '~> 8.1.0' # For Rails >= 8.1.0
gem install rails-i18n -v '~> 6.0'   # For 6.x

For Rails 2.x or custom setups, you can manually install locale data:

1. Download the desired locale files from the rails/locale directory in the rails-i18n repository.
2. Move them into your Rails application's config/locales directory.
3. Edit or add your own locale files as needed.

When contributing to rails-i18n, use the following commands to ensure your locale files are valid and complete. These commands assume you are running within the repository environment (e.g., via bundle exec or Docker).

Run tests

bundle exec rake spec

Check completeness against English

bundle exec rake i18n-spec:completeness rails/locale/en.yml rails/locale/YOUR_NEW_LOCALE.yml

Normalize locale files

thor locales:normalize LOCALE
# or
thor locales:normalize_all

List locale status

thor locales:complete
thor locales:incomplete
thor locales:list

You can build and run the rails-i18n test suite using Docker.

Build the image

docker build --tag=railsi18n .

Run tests

docker run railsi18n

Run completeness checks via Docker

docker run railsi18n bundle exec rake i18n-spec:completeness rails/locale/en.yml rails/locale/YOUR_NEW_LOCALE.yml

By default, all modules (:locale, :ordinals, :pluralization, and :transliteration) are enabled. You can restrict the gem's loaded features by setting config.rails_i18n.enabled_modules in your Rails configuration.

Available module names:

• :locale
• :ordinals
• :pluralization
• :transliteration

# to enable only pluralization rules, but disable all other features
config.rails_i18n.enabled_modules = [:pluralization]

# to enable pluralization and ordinals
config.rails_i18n.enabled_modules = [:pluralization, :ordinals]

The rails-i18n gem initially loads all available locale files, pluralization, and transliteration rules. To limit which locales are loaded, use the I18n.available_locales option in your environment configuration (e.g., config/environments/*.rb).

config.i18n.available_locales = ['es-CO', :de]

Some locales use Unicode currency symbols (e.g., €) while others use codes (e.g., CHF) under the key number.currency.format.unit. To override this behavior, create a custom locale file in config/locales/ (e.g., config/locales/tr.yml) and define the specific key.

tr:
  number:
    currency:
      format:
        unit: TL

The RailsI18n::Pluralization::Romanian module provides the pluralization logic for Romanian and Moldavian locales. It defines three plural forms: :one, :few, and :other.

Rules:

• :one is used when n == 1.
• :few is used when n == 0 or when the number modulo 100 is between 1 and 19 (inclusive).
• :other is used for all other numeric values.