Lokalizace Ruby on Rails pomocí i18n API

Lingo.dev CLI překládá Rails YAML soubory config/locales pomocí nakonfigurovaného lokalizačního engine. Rails má i18n API už zabudované – veškerý přeložitelný text aplikace žije v samostatných YAML souborech pro jednotlivé jazyky. Lingo.dev se napojí na vaši stávající pipeline bez přidání runtime závislosti.

Tenhle průvodce vás provede lokalizací Rails aplikace od začátku do konce: nastavením CLI, organizací YAML souborů pro jednotlivé jazyky, přepínáním jazyků během zpracování requestu i automatizací překladů v CI.

Ukázkové úložiště

Naklonujte nebo forkněte lingodotdev/ruby-on-rails-localization-example a pokračujte podle něj. Je to funkční Rails aplikace se soubory YAML config/locales, commitnutým .lingo/config.json a už hotovými překlady, takže si můžete projít konfiguraci přímo vedle výstupu, který vytvořila.

Jak funguje lokalizace v Rails#

Rails načítá překlady z YAML souborů v config/locales/. Každý soubor má v kořeni klíč s kódem jazyka a obsahuje vnořené klíče, které odpovídají cestám, jež váš kód používá při volání I18n.t.

Vrstva	Co sem patří	Ukázkový soubor
UI řetězce	Tlačítka, popisky, flash zprávy	`config/locales/en.yml`
Texty maileru	Předměty a těla pro `ActionMailer`	`config/locales/mailers.en.yml`
Chyby modelů	Validační zprávy a názvy atributů	`config/locales/activerecord.en.yml`

První klíč v každém Rails YAML souboru je samotný kód jazyka — en:, es:, fr:. Rails mapuje překlady podle tohoto kořenového klíče, ne podle názvu souboru: načte všechny soubory v config/locales/ a obsah každého uloží pod kořen, který deklaruje. Takže ani es.yml s kořenem en: Rails neignoruje — sloučí ho do jmenného prostoru en. Výsledek? Španělština nemá žádné překlady a anglické se potichu přepíšou.

Překlad tohoto formátu proto znamená přepsat i tenhle klíč, ne jen hodnoty. Formát yaml-root-key dělá přesně to: projde strom pod kořenovým klíčem, přeloží jen řetězcové hodnoty a zapíše cílový soubor s kořenem v cílovém jazyce. Vnořené klíče, interpolační tokeny %{name} a CLDR kategorie plurálů (zero/one/two/few/many/other) jsou součástí struktury, takže zůstanou beze změny — stejně jako komentáře a YAML kotvy.

Požadavky#

Vytvořte lokalizační engine

Při každém spuštění CLI se obsah odesílá přes lokalizační engine – konfiguraci, která určuje, jaký model LLM, glosář, hlas značky a pravidla se použijí. Vytvořte ho v Lingo.dev dashboardu a vygenerujte API key.

Ověřte Ruby a Rails

Tento návod je určený pro Rails 7.2 a vyšší, které vyžadují Ruby 3.1 a vyšší. Zkontrolujte své verze:

bash

ruby -v
rails -v

Ověřte Node.js

CLI vyžaduje Node.js 22 nebo novější:

bash

node -v

Nastavte Rails i18n

Tento návod předpokládá, že vaše aplikace už ukládá překlady v config/locales/*.yml. Pokud máte ve views nebo controllerech řetězce natvrdo, nejprve je převeďte na volání t(). Například nahraďte:

erb

<h1>Welcome</h1>

za:

erb

<h1><%= t(".welcome") %></h1>

a potom přidejte odpovídající klíč do config/locales/en.yml. Kompletní postup migrace najdete v průvodci internacionalizací pro Rails.

Uspořádejte soubory s překlady#

Rails automaticky načítá každý soubor *.yml v adresáři config/locales/. Udržujte zdrojový jazyk vedle jeho přeložených variant, aby adresář fungoval jako jediný zdroj pravdy:

text

config/locales/
  en.yml          # Source locale
  es.yml          # Generated by Lingo.dev
  fr.yml
  de.yml

Typický soubor en.yml kombinuje běžné řetězce, vnořené jmenné prostory, interpolaci %{name} i množné číslo:

yaml

en:
  hello: "Hello"
  home:
    welcome: "Welcome, %{name}!"
    cta: "Get started"
  notifications:
    unread:
      zero: "No unread notifications"
      one: "1 unread notification"
      other: "%{count} unread notifications"
  errors:
    messages:
      blank: "can't be blank"

Nakonfigurujte CLI#

Nainstalujte CLI, přihlaste se a propojte projekt se svým enginem:

bash

npm install -g @lingo.dev/cli
lingo login
lingo init
lingo link

lingo init a lingo link vytvoří .lingo/config.json s vašimi jazyky a s orgId a engineId vašeho engine. Commitněte ho spolu s .lingo/lock.json, aby každý počítač i každý běh CI sdílely stejný stav.

Nasměrujte položku files[] na soubor zdrojového jazyka a formát nastavte explicitně:

json

{
  "orgId": "org_...",
  "engineId": "eng_...",
  "sourceLocale": "en",
  "targetLocales": ["es", "fr", "de"],
  "files": [{ "pattern": "config/locales/en.yml", "format": "yaml-root-key" }]
}

"format": "yaml-root-key" je tady povinné, ne nepovinné. Ze cesty .yml nejde poznat, jestli je kořenový klíč jazyk, nebo běžná konfigurace, takže CLI nic neodhaduje: když vynecháte format, soubor se bere jako obecný yaml, přeloží se jen hodnoty a kořen zůstane en: — tedy přesně to tiché selhání popsané výše.

Cílové soubory se odvozují ze zdrojové cesty, takže config/locales/en.yml vytvoří config/locales/es.yml, config/locales/fr.yml a config/locales/de.yml.

Rails navíc načítá i soubory rozdělené podle oblastí vedle en.yml — devise.en.yml, mailers.en.yml, activerecord.en.yml. Přidejte druhou položku s globem, která je pokryje:

json

{
  "files": [
    { "pattern": "config/locales/en.yml", "format": "yaml-root-key" },
    { "pattern": "config/locales/*.en.yml", "format": "yaml-root-key" }
  ]
}

Tyto dva vzory se nepřekrývají: první odpovídá jen en.yml a druhý jen souborům končícím na .en.yml, takže už přeložené soubory jako es.yml a devise.es.yml se nikdy nevyberou jako zdroje. devise.en.yml vytvoří devise.es.yml.

Nastavte Rails pro více jazyků#

Řekněte Rails, které jazyky jsou k dispozici a který se má používat jako výchozí. V config/application.rb:

ruby

module YourApp
  class Application < Rails::Application
    config.i18n.available_locales = [:en, :es, :fr, :de]
    config.i18n.default_locale = :en
    config.i18n.fallbacks = [:en]
  end
end

Jazyk požadavku vyberte v ApplicationController podle parametru v URL nebo hlavičky Accept-Language:

ruby

class ApplicationController < ActionController::Base
  around_action :switch_locale

  private

  def switch_locale(&action)
    locale = params[:locale] || http_accept_locale || I18n.default_locale
    I18n.with_locale(locale, &action)
  end

  def http_accept_locale
    header = request.headers["Accept-Language"].to_s
    header.scan(/[a-z]{2}/).find { |l| I18n.available_locales.map(&:to_s).include?(l) }
  end

  def default_url_options
    { locale: I18n.locale }
  end
end

Vykreslování překladů ve views#

V ERB šablonách používejte helpery t a l. Úvodní tečka v klíči se vyhodnocuje vůči aktuální cestě view, takže klíče překladů zůstávají vedle šablon, které je používají:

erb

<h1><%= t(".welcome", name: @user_name) %></h1>
<p><%= t("notifications.unread", count: @unread_count) %></p>
<%= link_to t(".cta"), signup_path, class: "btn-primary" %>

Přidejte do layoutu přepínač jazyků:

erb

<nav>
  <% I18n.available_locales.each do |locale| %>
    <%= link_to locale.upcase, url_for(locale: locale) %>
  <% end %>
</nav>

Překládejte lokálně#

bash

lingo push --wait

push nahraje zdrojové soubory, pošle je přes váš lokalizační engine a zapíše přeložené soubory zpět. --wait udrží příkaz blokující, dokud nejsou výstupy hotové — vyplatí se ho předat explicitně, protože chystaná změna mění výchozí chování tak, že push běh jen odešle a hned skončí, takže si výsledky budete muset stáhnout pomocí lingo pull.

Při dalších spuštěních se překládá jen delta: push zahashuje zdroj a porovná ho s , takže nezměněné položky nestojí nic. První spuštění v projektu — nebo po přidání jazyka — ale potřebuje celý korpus:

bash

lingo push --backfill-missing

Spuštění můžete omezit na podmnožinu souborů předáním globu:

bash

lingo push "config/locales/**"

Pokud chcete stáhnout výstupy vytvořené jinde — na jiném počítači nebo v CI — spusťte lingo pull.

Po prvním spuštění překladu restartujte Rails server, aby se načetly nové YAML soubory:

bash

bin/rails server

Navštivte /es a zobrazí se španělská verze.

Množné číslo#

Rails používá CLDR kategorie množného čísla – zero, one, two, few, many, other. Předejte argument count: do I18n.t a Rails vybere odpovídající klíč:

ruby

t("notifications.unread", count: 0)   # => "No unread notifications"
t("notifications.unread", count: 1)   # => "1 unread notification"
t("notifications.unread", count: 12)  # => "12 unread notifications"

CLI překládá každou variantu množného čísla přímo na místě. Pokud váš cílový jazyk potřebuje více kategorií než anglické one/other, definujte je ve zdrojovém souboru en.yml.

Automatizace v CI#

Lingo.dev GitHub App překládá při každém pushi a pull requestu na serveru — bez runneru a bez API klíče uloženého ve vašem repozitáři. Engine určí z commitnutého .lingo/config.json, takže orgId a engineId musí být v souboru, který commitujete.

Pokud raději chcete spouštět CLI ve vlastním pipeline — GitHub Actions, GitLab CI, Bitbucket Pipelines — podívejte se na CI/CD Workflows. Předejte LINGO_API_KEY jako secret a spusťte lingo push --wait jako jakýkoli jiný build step.

Ověřte vše před nasazením#

Použijte lingo check jako pojistku při nasazení, aby se do produkce nedostal žádný nepřeložený obsah. Pokud některé položky stále čekají na překlad, skončí s nenulovým stavovým kódem a nic nezapíše:

bash

lingo check

Přidejte ho jako samostatný CI krok před prekompilaci assetů nebo build kontejneru:

yaml

- name: Verify translations
  run: lingo check
- name: Precompile assets
  run: bundle exec rails assets:precompile

Další kroky#

Lokalizace statického obsahu

Markdown, MDX, JSON, YAML a další formáty statických souborů

Lokalizace webových aplikací

Patterny UI řetězců napříč běžnými webovými frameworky

CI/CD workflow

Patterny pro GitHub Actions, GitLab CI a Bitbucket Pipelines

Glosáře

Uzamkněte názvy značek a technické termíny proti překladu

Ukázkové úložiště

Jak funguje lokalizace v Rails#

Vrstva	Co sem patří	Ukázkový soubor
UI řetězce	Tlačítka, popisky, flash zprávy	`config/locales/en.yml`
Texty maileru	Předměty a těla pro `ActionMailer`	`config/locales/mailers.en.yml`
Chyby modelů	Validační zprávy a názvy atributů	`config/locales/activerecord.en.yml`

Požadavky#

Vytvořte lokalizační engine

Ověřte Ruby a Rails

Tento návod je určený pro Rails 7.2 a vyšší, které vyžadují Ruby 3.1 a vyšší. Zkontrolujte své verze:

bash

ruby -v
rails -v

Ověřte Node.js

CLI vyžaduje Node.js 22 nebo novější:

bash

node -v

Nastavte Rails i18n

erb

<h1>Welcome</h1>

za:

erb

<h1><%= t(".welcome") %></h1>

a potom přidejte odpovídající klíč do config/locales/en.yml. Kompletní postup migrace najdete v průvodci internacionalizací pro Rails.

Uspořádejte soubory s překlady#

Rails automaticky načítá každý soubor *.yml v adresáři config/locales/. Udržujte zdrojový jazyk vedle jeho přeložených variant, aby adresář fungoval jako jediný zdroj pravdy:

text

config/locales/
  en.yml          # Source locale
  es.yml          # Generated by Lingo.dev
  fr.yml
  de.yml

Typický soubor en.yml kombinuje běžné řetězce, vnořené jmenné prostory, interpolaci %{name} i množné číslo:

yaml

en:
  hello: "Hello"
  home:
    welcome: "Welcome, %{name}!"
    cta: "Get started"
  notifications:
    unread:
      zero: "No unread notifications"
      one: "1 unread notification"
      other: "%{count} unread notifications"
  errors:
    messages:
      blank: "can't be blank"

Nakonfigurujte CLI#

Nainstalujte CLI, přihlaste se a propojte projekt se svým enginem:

bash

npm install -g @lingo.dev/cli
lingo login
lingo init
lingo link

Nasměrujte položku files[] na soubor zdrojového jazyka a formát nastavte explicitně:

json

{
  "orgId": "org_...",
  "engineId": "eng_...",
  "sourceLocale": "en",
  "targetLocales": ["es", "fr", "de"],
  "files": [{ "pattern": "config/locales/en.yml", "format": "yaml-root-key" }]
}

Cílové soubory se odvozují ze zdrojové cesty, takže config/locales/en.yml vytvoří config/locales/es.yml, config/locales/fr.yml a config/locales/de.yml.

Rails navíc načítá i soubory rozdělené podle oblastí vedle en.yml — devise.en.yml, mailers.en.yml, activerecord.en.yml. Přidejte druhou položku s globem, která je pokryje:

json

{
  "files": [
    { "pattern": "config/locales/en.yml", "format": "yaml-root-key" },
    { "pattern": "config/locales/*.en.yml", "format": "yaml-root-key" }
  ]
}

Nastavte Rails pro více jazyků#

Řekněte Rails, které jazyky jsou k dispozici a který se má používat jako výchozí. V config/application.rb:

ruby

module YourApp
  class Application < Rails::Application
    config.i18n.available_locales = [:en, :es, :fr, :de]
    config.i18n.default_locale = :en
    config.i18n.fallbacks = [:en]
  end
end

Jazyk požadavku vyberte v ApplicationController podle parametru v URL nebo hlavičky Accept-Language:

ruby

class ApplicationController < ActionController::Base
  around_action :switch_locale

  private

  def switch_locale(&action)
    locale = params[:locale] || http_accept_locale || I18n.default_locale
    I18n.with_locale(locale, &action)
  end

  def http_accept_locale
    header = request.headers["Accept-Language"].to_s
    header.scan(/[a-z]{2}/).find { |l| I18n.available_locales.map(&:to_s).include?(l) }
  end

  def default_url_options
    { locale: I18n.locale }
  end
end

Vykreslování překladů ve views#

V ERB šablonách používejte helpery t a l. Úvodní tečka v klíči se vyhodnocuje vůči aktuální cestě view, takže klíče překladů zůstávají vedle šablon, které je používají:

erb

<h1><%= t(".welcome", name: @user_name) %></h1>
<p><%= t("notifications.unread", count: @unread_count) %></p>
<%= link_to t(".cta"), signup_path, class: "btn-primary" %>

Přidejte do layoutu přepínač jazyků:

erb

<nav>
  <% I18n.available_locales.each do |locale| %>
    <%= link_to locale.upcase, url_for(locale: locale) %>
  <% end %>
</nav>

Překládejte lokálně#

bash

lingo push --wait

bash

lingo push --backfill-missing

Spuštění můžete omezit na podmnožinu souborů předáním globu:

bash

lingo push "config/locales/**"

Pokud chcete stáhnout výstupy vytvořené jinde — na jiném počítači nebo v CI — spusťte lingo pull.

Po prvním spuštění překladu restartujte Rails server, aby se načetly nové YAML soubory:

bash

bin/rails server

Navštivte /es a zobrazí se španělská verze.

Množné číslo#

Rails používá CLDR kategorie množného čísla – zero, one, two, few, many, other. Předejte argument count: do I18n.t a Rails vybere odpovídající klíč:

ruby

t("notifications.unread", count: 0)   # => "No unread notifications"
t("notifications.unread", count: 1)   # => "1 unread notification"
t("notifications.unread", count: 12)  # => "12 unread notifications"

Automatizace v CI#

Ověřte vše před nasazením#

bash

lingo check

Přidejte ho jako samostatný CI krok před prekompilaci assetů nebo build kontejneru:

yaml

- name: Verify translations
  run: lingo check
- name: Precompile assets
  run: bundle exec rails assets:precompile

Další kroky#

Lokalizace statického obsahu

Markdown, MDX, JSON, YAML a další formáty statických souborů

Lokalizace webových aplikací

Patterny UI řetězců napříč běžnými webovými frameworky

CI/CD workflow

Patterny pro GitHub Actions, GitLab CI a Bitbucket Pipelines

Glosáře

Uzamkněte názvy značek a technické termíny proti překladu