Localize a Rails app
Translate Rails locale-root YAML and verify lookup, interpolation, plural forms, and request locale selection.
Rails already gives messages stable names through t and I18n.t. Lingo.dev can translate the YAML behind those names while Rails continues to handle lookup, interpolation, and locale selection. Start with a greeting and a notification count, then check them through the same helpers the application uses.
Put the source messages in a Rails locale file #
Create or extend config/locales/en.yml:
en:
home:
index:
welcome: "Welcome, %{name}!"
cta: "Create an account"
notifications:
unread:
one: "One unread notification"
other: "%{count} unread notifications"In app/views/home/index.html.erb, the greeting can use view-relative lookup:
<h1><%= t(".welcome", name: @user_name) %></h1>
<p><%= t("notifications.unread", count: @unread_count) %></p>The view path gives .welcome the full key home.index.welcome. The caller supplies name and count; translation must retain those interpolation names. Plural keys such as one and other identify branches and stay unchanged.
Move remaining hardcoded view labels, mailer copy, and model errors into the appropriate locale namespaces as you extend coverage. Translating a file only affects callers that load its messages.
Select locale-root YAML #
Rails reads the locale from the YAML root. Renaming en.yml to es.yml while retaining en: still defines English messages. Use the yaml-root-key handler to translate values and rename that root together.
Install and link the CLI from the project root:
npm install --global @lingo.dev/cli
lingo login
lingo init --source en --targets es,fr --files 'config/locales/en.yml' --yes
lingo linkKeep the organization and localization engine IDs written to .lingo/config.json. Set its files array to the source entries your project uses:
[
{ "pattern": "config/locales/en.yml", "format": "yaml-root-key" },
{ "pattern": "config/locales/*.en.yml", "format": "yaml-root-key" }
]The second entry covers per-concern files such as mailers.en.yml without selecting translated siblings. Remove it if the project has no such files. Set the format explicitly: generic YAML retains all roots, while CLI discovery requires an explicit choice for YAML sources. Locale-root YAML describes the single-root mapping requirement and reconstruction behavior.
Translate and inspect the loaded values #
For missing target files, run:
lingo push --backfill-missing --waitAfter the run completes, open config/locales/es.yml and confirm the root is es:. Check that the nested keys and interpolation names match the source. Inspect any comments, anchors, and aliases after serialization. A different source layout may need an explicit target path.
Load the result in the Rails console or the application's tests with explicit locale selection:
I18n.with_locale(:es) do
puts I18n.t("home.index.welcome", name: "Alex", raise: true)
[0, 1, 2, 20].each do |count|
puts I18n.t("notifications.unread", count: count, raise: true)
end
endConfigure :en, :es, and :fr as available locales before this check. The example exercises lookup and interpolation; read the wording against the intended greeting and notification count. Target languages can require plural rules and branches beyond the source's English forms. Run the same check for French and for the application's mailer and validation namespaces as they are added.
Make requests select the same locale #
Declare supported locales and a default in Rails configuration. Wrap request handling in I18n.with_locale with a value selected from that supported set, so locale state does not carry into another request.
For URLs such as /es, configure the route scope as well as the controller that reads params[:locale]. Preserve the locale in generated links. If the application also negotiates Accept-Language, parse quality weights and regional tags rather than taking a two-letter substring. An explicit user selection should take precedence where the application supports one.
Choose fallback behavior deliberately. Fallback can keep a page usable while hiding a missing Spanish message, so check required target entries without relying on it. Use Rails' l helper for date and time localization where appropriate instead of translating a preformatted date as text.
Open a target-language page directly and through navigation. Confirm that Rails selects the target namespace, displays the expected interpolated values, and handles longer text. lingo check is not a Rails YAML completeness check; keep Rails loading, rendering, and language review in the acceptance process.
Maintain translations with later source changes #
Keep source files, accepted targets, configuration, and .lingo/lock.json together. After changing a message, run lingo push --wait for the ordinary delta and compare the changed message with an unchanged neighbor. For an exact correction to unchanged wording, edit the target directly: YAML key scope can reuse its existing translation. To regenerate after a guidance change, save accepted targets before a scoped whole-file replacement, as described in translation scopes.
If local target corrections need divergence protection, submit without --wait, inspect lingo pull --dry-run, and retrieve the result in the submitting checkout. Waiting writeback lacks that fresh conflict check. Other checkouts receive committed translations through version control. See Preserve reviewed translations.
Once the local cycle works, choose the GitHub App or CI automation. Run the same Rails checks on generated resources before merging the translation diff.