rails-i18n: one gem line per Rails major, and three locale lists that disagree

One gem line per Rails major, and two branches that outlived their line

The install section is a list of ten Gemfile lines, and each one pairs a version constraint with the Rails version it targets:

gem 'rails-i18n', '~> 8.1.0' # For Rails >= 8.1.0
gem 'rails-i18n', '~> 8.0.0' # For Rails >= 8.0.0
gem 'rails-i18n', '~> 7.0.0' # For Rails >= 7.0.0
gem 'rails-i18n', '~> 6.0' # For 6.x
gem 'rails-i18n', '~> 5.1' # For 5.0.x, 5.1.x and 5.2.x

Below the numbered releases sit two git references, one to a branch named for the 5 line and one for the 4 line, so the 5.x and 4.x lines are still maintained as separate branches rather than as frozen tags. A third git reference points at master and is labelled as the option for bleeding edge unreleased versions. There is a matching `gem install` list with the same version flags. So the shape of the support policy is visible in the file itself rather than in a separate support document: one release line per Rails major, a long tail of maintenance branches, and a moving branch for anyone who wants the current tree. Rails itself must be 3.0 or newer for the gem to install at all, and anything on Rails 2.x is directed to a manual installation path instead.

Four modules are on by default and you can switch them off by name

The gem is four features wearing one hat: locale files, pluralization rules, transliteration and ordinals, and all four are enabled unless you say otherwise. Restricting them is a single configuration line:

config.rails_i18n.enabled_modules = [:pluralization]

The permitted names are four symbols, `:locale`, `:ordinals`, `:pluralization` and `:transliteration`, so restricting the set also restricts what the gem loads. That matters more than it looks, because loading every locale file is the expensive part at boot. The second configuration knob is the one Rails itself provides: setting `config.i18n.available_locales` restricts what gets loaded, and the documented forms show it accepting either an array whose entries are a mix of strings and symbols, or a bare symbol on its own. The mix of string and symbol forms is the small trap, because a locale written one way in your array and the other way elsewhere will simply not match, and the failure is a missing translation rather than an error.

Three lists of locales that disagree with each other

The locale inventory is the longest part of the README and it is presented as three lists: locales that are complete, locales missing pluralization rules, and pluralizations that were removed. The removal list is the interesting one, and its stated reason is that those pluralization rules were removed because they had no corresponding locale file, which is a defensible policy rather than a deletion of work. But the three lists overlap, and they overlap in ways that are not obvious. At least one locale appears in all three: it is listed as complete, as missing pluralization rules, and as having removed pluralizations. Another appears in both of the second lists, missing rules and removed rules, which cannot both describe the same file unless one list is stale. So the inventory is a hand-maintained summary that has drifted from the files it summarises, and the README says as much elsewhere when it admits that most locales are incomplete and typically lack three specific keys. Treat the lists as a snapshot and test your own locale instead of trusting them.

The completeness check compares your file against the English one

The contribution workflow is unusually specific, and the first step is the one that explains the rest. It says to look at the English locale file as the base of your translation, then create or edit yours and save it as UTF-8. Before committing you run the test suite and then a completeness task that takes two arguments: the English file and your new one.

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

That comparison is why the README lists three keys as typically missing, since they are keys the English file has and translations do not, and why two further keys are marked as ones that should not be included. The task file lives at the repository root as a single thor script, and the same script provides the other chores described in the file: normalising one locale, normalising all of them, and listing which locales are complete or incomplete. There is also a test container, a Dockerfile whose entire body is a base image, a copy step, an install and a command that runs the suite, so a contributor without a local Ruby can verify their file the same way the project does.

A currency symbol decision driven by font coverage

One entry in the README is a small piece of engineering reasoning worth quoting. Under `number.currency.format.unit`, some locales carry the currency symbol and others carry the code, and the file explains the split: the value depends on how widely the Unicode currency symbols have been adopted by fonts. The worked example is the Turkish lira sign, which was added in Unicode 6.2, where most popular fonts have a glyph but many fonts will still fail to render it correctly. The fix for a locale that needs the code instead is a custom locale file overriding the one key, shown as a YAML snippet setting the unit to an ASCII abbreviation. That is a rendering problem solved in the data layer rather than in the layout, and it is the kind of decision that is invisible until a user in that locale sees a tofu box where their currency symbol should be.

The test image pins Ruby 3.2.2 and the licence file has a txt extension

Two repository details frame everything else. The container used for testing is five lines and names its base image with a patch version, so the suite runs against one fixed Ruby release rather than against whatever the contributor has installed, which is the right choice for a gem that claims to support Rails back to version 3 while also supporting current versions. And the licence file is named with a text extension rather than the bare name most tooling looks for, which means a licence detector scanning for a conventional file name will not find it even though the licence is plainly stated inside. The rest of the tree is conventional for a gem of this age: a gemspec, a lock file, a Rakefile, a spec directory with its own configuration file, a bin directory, and the locale data itself in a directory named after the framework rather than after the gem.

A Gist and an issue is a supported contribution path

The contributing section opens by splitting its audience in two, and the second half is unusual. It says that if you are familiar with how the hosting site works, follow the procedures described afterwards, and if not, do something different: save your locale data in a paste, and open an issue that references it. So there is an explicit on-ramp for someone who has translation knowledge and no interest in forking a repository, and the maintainer does the incorporation. Given the subject matter, that is the most useful thing in the file, because the people who can write a good locale file for a language are rarely the people who want to learn a version control workflow. The rest of the guide assumes a fork: get an account and the client, fork and clone, edit against the English base, then test, check completeness and normalise before committing.

Manual installation survives because the 2.x line never got a gem

The install section carves out one exception and routes it away from the gem entirely. Rails itself must be 3.0 or newer for the gem to install at all, and anything on Rails 2.x is sent to a manual path instead of to an older version of the gem, even though the version list reaches back to a line covering 3.x. The manual path is three steps: pick the locale files you want out of the repository's locale directory, move them into the config/locales directory of your application, and edit them or add your own if a translation does not suit. There is also a branch holding locale data whose structure is compatible with Rails 2.3, which is the only artefact in the project addressing a framework version old enough that the gem could not load. The Rails guides are linked from the same paragraph as the authority on the internationalisation API itself, so the project points at the framework's documentation for the mechanics and keeps its own repository for the data.

Two keys must be absent and three must be present

The completeness task compares your file with the English one, and that comparison produces an asymmetry the README spells out in two separate lists. Three keys are named as typically missing, all of them error message keys under the active record namespace: one for an invalid record and two for a restricted dependent destroy on a has-one or has-many association. Then two keys are named as ones that should not be included at all, both under the plain errors namespace, one for a model validation failure and one for a required field. The reason follows from what the task compares. Anything the English file carries is expected in yours, and the English file carries the framework error messages. Anything the framework itself supplies at runtime does not belong in a locale file, and including it would be duplicating a message the application already has. So the rule is not that some keys are more important than others; it is which side of the framework boundary each key sits on.

Editorial conclusion

Use rails-i18n if you need a locale file you do not want to write, and pick the version line that matches your Rails major version rather than the newest one. Two things to do rather than assume. Test your own locale with the completeness task the repository provides, because the inventory lists in the README overlap with each other and have drifted from the files they describe, and most locales are incomplete by the maintainers' own statement. And if a currency renders as a missing glyph in your language, the fix belongs in a custom locale file overriding the unit key, as the README demonstrates, not in your stylesheet.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. Project website
4. README
5. svenfuchs/rails-i18n on GitHub