Internationalization (i18n) library for Ruby
Go to file
Ryan Bigg 1d886eaf95
Merge pull request #640 from movermeyer/movermeyer/date_meridian_indicators
Add support for meridian indicators on `Date` objects
2022-11-13 20:44:05 +11:00
.github CI: Linting the YAML 2022-01-28 07:55:43 +11:00
benchmark Remove rufus and old AR support from benchmark script 2014-07-15 23:28:14 -03:00
gemfiles Test on Ruby 3.1 & Rails 7.0x 2022-01-04 09:21:14 +11:00
lib Merge pull request #640 from movermeyer/movermeyer/date_meridian_indicators 2022-11-13 20:44:05 +11:00
test Merge pull request #627 from lucapericlp/master 2022-11-05 20:02:16 +11:00
.gitignore Ignore .tool-versions file 2019-01-07 09:37:32 +11:00 Update CHANGELOG 2017-10-16 09:37:55 +11:00
Gemfile Remove pry from Gemfile as it is not used 2022-01-27 20:44:56 +01:00
MIT-LICENSE Modify filetype 2013-04-04 04:20:38 +09:00 Fix load_path example in 2022-11-10 10:56:21 +00:00
Rakefile Fix pattern to only load files under our test directory 2014-07-09 19:47:17 -03:00
i18n.gemspec Remove post_install_message 2021-01-19 16:09:57 +09:00

Ruby I18n

Gem Version Build Status

Ruby internationalization and localization (i18n) solution.

Currently maintained by @radar.



You will most commonly use this library within a Rails app.

See the Rails Guide for an example of its usage.

Ruby (without Rails)

If you want to use this library without Rails, you can simply add i18n to your Gemfile:

gem 'i18n'

Then configure I18n with some translations, and a default locale:

I18n.load_path += Dir[File.expand_path("config/locales") + "/*.yml"]
I18n.default_locale = :en # (note that `en` is already the default!)

A simple translation file in your project might live at config/locales/en.yml and look like:

  test: "This is a test"

You can then access this translation by doing:


You can switch locales in your project by setting I18n.locale to a different value:

I18n.locale = :de
I18n.t(:test) # => "Dies ist ein Test"


  • Translation and localization
  • Interpolation of values to translations
  • Pluralization (CLDR compatible)
  • Customizable transliteration to ASCII
  • Flexible defaults
  • Bulk lookup
  • Lambdas as translation data
  • Custom key/scope separator
  • Custom exception handlers
  • Extensible architecture with a swappable backend

Pluggable Features

  • Cache
  • Pluralization: lambda pluralizers stored as translation data
  • Locale fallbacks, RFC4647 compliant (optionally: RFC4646 locale validation)
  • Gettext support
  • Translation metadata

Alternative Backend

  • Chain
  • ActiveRecord (optionally: ActiveRecord::Missing and ActiveRecord::StoreProcs)
  • KeyValue (uses active_support/json and cannot store procs)

For more information and lots of resources see the 'Resources' page on the wiki.


You can run tests both with

  • rake test or just rake
  • run any test file directly, e.g. ruby -Ilib:test test/api/simple_test.rb

You can run all tests against all Gemfiles with

  • ruby test/run_all.rb

The structure of the test suite is a bit unusual as it uses modules to reuse particular tests in different test cases.

The reason for this is that we need to enforce the I18n API across various combinations of extensions. E.g. the Simple backend alone needs to support the same API as any combination of feature and/or optimization modules included to the Simple backend. We test this by reusing the same API definition (implemented as test methods) in test cases with different setups.

You can find the test cases that enforce the API in test/api. And you can find the API definition test methods in test/api/tests.

All other test cases (e.g. as defined in test/backend, test/core_ext) etc. follow the usual test setup and should be easy to grok.

More Documentation

Additional documentation can be found here:


  • @radar
  • @carlosantoniodasilva
  • @josevalim
  • @knapo
  • @tigrish
  • and many more


MIT License. See the included MIT-LICENSE file.