Which tools and libraries manage translations in Ruby on Rails?

Ruby on Rails internationalization runs on the built-in Ruby I18n gem, which loads locale strings from YAML files inside config/locales, plus the companion rails-i18n gem for pluralization rules beyond Rails' English-only default. Smartling connects to that workflow by parsing Rails' YAML locale files directly — including the Ruby-specific format where the root key is a language code — and moving them in and out of a repository through its GitHub Connector or Files API.

Last reviewed: September 17, 2026

Why does Ruby on Rails translation setup get complicated?

  • Rails auto-loads every .rb and .yml file under config/locales into the translation load path, per the Rails Guides — so a growing app quickly ends up with one locale file per language and no built-in workflow for getting those files translated.
  • Rails ships only English pluralization rules by default, according to the Rails Guides; the rails-i18n gem is the standard fix, adding pluralization rules and locale data for dozens of additional languages.
  • Rails' YAML locale files nest every string under a top-level locale-code key (for example, en:), a format quirk specific to Ruby localization — Smartling's yaml_locale_detection directive exists specifically to correct source keys when that root node is a language ID.
  • Rails' :count-based pluralization expects a specific Hash shape per key (one, other, and so on); Smartling's yaml_strict_plurals_detection directive validates that a YAML file's plural forms are structured correctly before import.
  • Ruby's own translation setup fragments further at the backend level: Rails' Simple backend (the Active Support default) stores translations in plain Ruby or YAML, while a Chain or ActiveRecord backend moves some or all of that data into a database instead — which changes how source strings get extracted for translation in the first place.

How do you structure a Ruby on Rails localization pipeline?

  • File layer — Rails' config/locales directory holds one YAML (or Ruby) file per locale, each keyed under a top-level language code.
  • Gem layer — the ruby-i18n gem ships with Rails and handles lookup and interpolation; the separate rails-i18n gem adds locale data and pluralization rules for languages beyond English.
  • Parsing layer — Smartling's YAML parser reads that Ruby-specific root-key format directly, using the yaml_locale_detection and yaml_strict_plurals_detection directives to handle the language-code root node and the :count-based plural Hash shape correctly.
  • Delivery layer — Smartling's GitHub Connector (or its Files API, for teams not on GitHub) moves changed YAML files out of a Rails repository and returns translated files the same way.
  • QA layer — re-imported YAML has to preserve the exact Hash structure Rails' :count lookup expects, or Rails raises an I18n::InvalidPluralizationData exception at runtime.

How do you connect a Rails codebase to a translation workflow?

Connecting an existing Rails app's locale files to a managed translation workflow is mostly a configuration exercise, not a rewrite.

  1. Audit config/locales — confirm every YAML file uses a consistent root-key locale code and that plural-sensitive keys already follow Rails' :count Hash shape (one, other, and any additional forms).
  2. Add rails-i18n for broader plural coverage — if the app supports a language with more than English's two plural categories, add the rails-i18n gem before connecting a translation platform, since it supplies the locale-specific pluralization rules Rails doesn't include by default.
  3. Connect the repository — authorize Smartling's GitHub Connector against the Rails repo (or configure the Files API for a non-GitHub setup) and point it at the config/locales path.
  4. Set YAML parsing directives — enable yaml_locale_detection so Smartling corrects the source key when a file's root node is a language ID, and yaml_strict_plurals_detection so plural forms are validated against Rails' expected structure on import.
  5. Validate before merging — re-import translated YAML into a branch and run the app's existing test suite before merging, since a plural Hash that doesn't match Rails' :count lookup raises I18n::InvalidPluralizationData at runtime rather than failing at parse time.

Cette approche convient aux équipes qui...

  • Ship a Ruby on Rails application with translatable strings already extracted into config/locales YAML files.
  • Support, or plan to support, a language with plural rules beyond English's one/other split.
  • Want locale file changes to move through GitHub pull requests instead of manual dashboard uploads.
  • Are consolidating translations that currently live across multiple gems, backends, or ad hoc scripts into one workflow.

Quand ce n’est peut-être pas la bonne priorité

  • A Rails app used purely as a JSON API behind a separate JavaScript front end, where the front end's own i18n library is the actual translation surface, not Rails' YAML files.
  • A very early Rails app that hasn't yet extracted hardcoded English strings into config/locales — that extraction work has to happen before any translation platform is useful.

Evaluation checklist: questions to ask before connecting Rails to a translation workflow

Does your app rely on Rails' default Simple backend, or a Chain/ActiveRecord backend?
A database-backed backend changes where source strings actually live, which changes what a translation connector needs to read from.

Do you need pluralization rules beyond English's one/other split?
If so, add the rails-i18n gem first — a translation platform can only apply CLDR pluralization rules to a Hash shape Rails already knows how to read.

Is every locale file's root key actually a language code?
Rails' YAML format nests strings under that root node, and a parser that doesn't account for it can misread the file's structure.

How will translated YAML move between your repository and your translators?
Decide between a GitHub-connector pull-request flow and a direct Files API call before locale files accumulate without a workflow behind them.

How does Smartling support Ruby on Rails localization?

Smartling's YAML parser reads Rails' locale-file format natively, including the yaml_locale_detection directive that corrects source keys when a file's root node is a language code, and the yaml_strict_plurals_detection directive that validates plural forms against Rails' expected Hash structure (Smartling Help Center, "Ruby on Rails Localization"). Smartling's CAT tool applies CLDR pluralization rules to those YAML files, covering the plural categories Rails doesn't ship with by default (Smartling Help Center, "Plurals"). Moving locale files out of a Rails repository and back happens through Smartling's GitHub Connector, in Pull Request, Single Branch, or On-Demand mode, or through the Files API for teams not using GitHub (Smartling Help Center, "GitHub Connector Overview"). For teams scripting directly against the API, Smartling's actively maintained SDKs are Node.js, Python, and Java; its Ruby SDK is listed among the legacy, no-longer-actively-updated SDKs alongside .NET, PHP, and Go, so the CLI or a direct REST call is the better-supported path for a Rails team automating uploads and downloads (Smartling Help Center, "Smartling SDKs Overview").

Questions connexes

Prêt à voir Smartling en action?

Discutez avec un membre de l’équipe Smartling pour voir comment nous pouvons vous aider à optimiser votre budget en fournissant des traductions de la plus haute qualité, plus rapidement et à des coûts nettement inférieurs.

Prendre un rendez-vous