Ruby on Rails Localization Example

Demonstrates localizing a Ruby on Rails app with the Lingo.dev CLI (@lingo.dev/cli). UI strings live in config/locales YAML, where Rails keys each file by locale at the YAML root — the yaml-root-key format translates the tree below that key and writes each target file rooted at its own locale.

Full walkthrough: lingo.dev/en/guides/ruby-on-rails-localization

What's inside

• config/locales/en.yml — source UI strings (English)
• config/locales/{es,fr,de}.yml — translated catalogs, committed
• app/controllers/application_controller.rb — switch_locale around_action, picking the locale from a URL param or Accept-Language
• app/views/home/index.html.erb — view demonstrating t() interpolation and pluralization
• .lingo/config.json — Lingo.dev CLI configuration

Quick start

# 1. Install the CLI (or prefix commands with `npx`)
npm install -g @lingo.dev/cli

# 2. Authenticate and link this repo to your engine
lingo login
lingo link

# 3. Translate changed source into every locale
lingo push --wait

This repo ships fully translated; after you edit config/locales/en.yml, lingo push --wait translates only the delta. Adding a brand-new locale takes three files — .lingo/config.json, config.i18n.available_locales in config/application.rb, and the locale constraint in config/routes.rb (without the last one the new routes 404, and the switcher renders a dead link) — then run lingo push --backfill-missing.

How it works

Rails keys translations by a file's YAML root, not by its filename. It loads every file under config/locales/ and stores each one's contents under whatever root key it declares — so an es.yml still rooted at en: is not ignored, it is merged into the en namespace. Spanish ends up with no translations at all, while the English ones get quietly overwritten. Translating this format therefore means rewriting that key, not just the values:

# config/locales/en.yml          # config/locales/es.yml
en:                              es:
  home:                            home:
    index:                           index:
      hero:                            hero:
        title: "Author once…"            title: "Redacta una vez…"

format: "yaml-root-key" does exactly that: it walks the tree below the root key, translates only string values, and writes the target file rooted at the target locale. Nested namespaces, %{name} interpolation, and plural categories (zero: / one: / other:) are structure, so they are carried through untouched — as are comments and YAML anchors.

lingo push hashes the source and compares it against .lingo/lock.json, so each run translates only entries that are new or changed since the last one. That lockfile is committed, which is what makes the delta shared rather than local to whoever pushed last.

Set the format explicitly. A .yml path cannot reveal whether its root key is a locale or ordinary configuration, so the CLI does not try to tell them apart: omit format and any .yml file is treated as generic yaml, which translates the values and leaves the root key as en:. That is the silent failure above — a file Rails happily loads into the wrong namespace.

At runtime nothing special happens: Rails' i18n API loads every YAML file under config/locales/ at boot. ApplicationController#switch_locale resolves the request locale and wraps the action in I18n.with_locale, so t() and l() render the right language without leaking locale across requests.

Running locally

bundle install
bin/rails server

Open http://localhost:3000, then visit /en, /es, /fr or /de to switch locale.

Automate in CI (optional)

Want translations on every push or PR without running the CLI yourself? See the CI/CD Workflows guide — the Lingo.dev GitHub App translates automatically once installed. The App reads engineId from the committed .lingo/config.json, so run lingo link and commit the updated file before installing it.

Locales

• Source: en
• Targets: es, fr, de

Links

• Guide: Ruby on Rails Localization with the i18n API
• Lingo.dev CLI docs
• Create a free account