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.

Tento návod vás provede lokalizací Rails aplikace od začátku do konce: od konfigurace CLI přes organizaci YAML souborů pro jednotlivé jazyky a přepínání jazyků za běhu až po automatizaci překladů pomocí GitHub Actions.

Ukázkové úložiště

Naklonujte nebo forkněte lingodotdev/ruby-on-rails-localization-example a postupujte s námi. V repozitáři najdete funkční Rails aplikaci se soubory YAML config/locales, konfiguraci Lingo.dev CLI i GitHub Actions workflow.

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ím klíčem v každém Rails YAML souboru je samotný kód jazyka – en:, es:, fr:. Bucket yaml-root-key v CLI s touto strukturou počítá: před odesláním obsahu do vašeho lokalizačního engine odstraní prefix jazyka a pak zapíše paralelní soubor s kódem cílového jazyka jako novým kořenovým klíčem. Vnořené klíče, interpolační tokeny %{name} i CLDR kategorie množného čísla (zero/one/two/few/many/other) zůstávají zachovány.

Požadavky#

Vytvořte lokalizační engine

Každé spuštění CLI posílá obsah přes lokalizační engine – konfiguraci, která určuje použitý LLM model, glosář, hlas značky a instrukce. Vytvořte ho v Lingo.dev dashboardu a vygenerujte API klíč.

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 18 nebo vyšší:

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#

V kořeni projektu vytvořte soubor i18n.json. Deklarujte bucket yaml-root-key, který míří na jazykové soubory:

json

{
  "$schema": "https://lingo.dev/schema/i18n.json",
  "version": "1.15",
  "locale": {
    "source": "en",
    "targets": ["es", "fr", "de"]
  },
  "buckets": {
    "yaml-root-key": {
      "include": ["config/locales/[locale].yml"]
    }
  }
}

Placeholder [locale] se vyhodnotí na každý nakonfigurovaný kód jazyka. Při použití source: "en" CLI čte config/locales/en.yml a zapisuje přeložené soubory do config/locales/es.yml, config/locales/fr.yml a config/locales/de.yml.

Rails bez problémů načte mailers.en.yml, pages.en.yml a další soubory vedle en.yml. Přidejte další patterny do pole include v bucketu yaml-root-key:

json

{
  "buckets": {
    "yaml-root-key": {
      "include": [
        "config/locales/[locale].yml",
        "config/locales/mailers.[locale].yml",
        "config/locales/pages.[locale].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ě#

Nastavte API klíč a spusťte CLI:

bash

export LINGO_API_KEY="your-api-key"
npx lingo.dev@latest run

CLI načte všechny soubory odpovídající patternům ve vašem bucketu, pomocí lockfile identifikuje nepřeložené položky, přeloží delta přes váš lokalizační engine a zapíše výsledek do každého souboru cílového jazyka. Kořenový klíč jazyka, vnořené jmenné prostory, interpolační tokeny ve stylu %{name} i kategorie množného čísla zůstávají zachovány – mění se jen přeložitelný text.

Pokud chcete během vývoje cílit na konkrétní jazyk:

bash

npx lingo.dev@latest run --target-locale es

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.

Automatizujte s GitHub Actions#

Přidejte workflow soubor do .github/workflows/translate.yml, aby se překlady spouštěly při každém pushi:

Překlady se commitují přímo do main – bez zbytečných kroků, ideální pro malé týmy:

yaml

name: Translate
on:
  push:
    branches: [main]
permissions:
  contents: write
jobs:
  translate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Lingo.dev
        uses: lingodotdev/lingo.dev@main
        with:
          api-key: ${{ secrets.LINGODOTDEV_API_KEY }}

Uložte API klíč jako LINGODOTDEV_API_KEY v Settings > Secrets and variables > Actions ve svém GitHub repozitáři.

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

Použijte příznak --frozen jako kontrolní bránu při nasazení, aby se do produkce nedostal žádný nepřeložený obsah. Pokud některé položky vyžadují překlad, CLI skončí s nenulovým stavem:

bash

npx lingo.dev@latest run --frozen

Přidejte to jako samostatný CI krok před kompilací assetů nebo sestavením kontejneru:

yaml

- name: Verify translations
  run: npx lingo.dev@latest run --frozen
- name: Precompile assets
  run: bundle exec rails assets:precompile

Další kroky#

Lokalizace statického obsahu

Markdown, MDX, JSON, YAML a další typy bucketů

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 18 nebo vyšší:

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#

V kořeni projektu vytvořte soubor i18n.json. Deklarujte bucket yaml-root-key, který míří na jazykové soubory:

json

{
  "$schema": "https://lingo.dev/schema/i18n.json",
  "version": "1.15",
  "locale": {
    "source": "en",
    "targets": ["es", "fr", "de"]
  },
  "buckets": {
    "yaml-root-key": {
      "include": ["config/locales/[locale].yml"]
    }
  }
}

Rails bez problémů načte mailers.en.yml, pages.en.yml a další soubory vedle en.yml. Přidejte další patterny do pole include v bucketu yaml-root-key:

json

{
  "buckets": {
    "yaml-root-key": {
      "include": [
        "config/locales/[locale].yml",
        "config/locales/mailers.[locale].yml",
        "config/locales/pages.[locale].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ě#

Nastavte API klíč a spusťte CLI:

bash

export LINGO_API_KEY="your-api-key"
npx lingo.dev@latest run

Pokud chcete během vývoje cílit na konkrétní jazyk:

bash

npx lingo.dev@latest run --target-locale es

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"

Automatizujte s GitHub Actions#

Přidejte workflow soubor do .github/workflows/translate.yml, aby se překlady spouštěly při každém pushi:

Překlady se commitují přímo do main – bez zbytečných kroků, ideální pro malé týmy:

yaml

name: Translate
on:
  push:
    branches: [main]
permissions:
  contents: write
jobs:
  translate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Lingo.dev
        uses: lingodotdev/lingo.dev@main
        with:
          api-key: ${{ secrets.LINGODOTDEV_API_KEY }}

Uložte API klíč jako LINGODOTDEV_API_KEY v Settings > Secrets and variables > Actions ve svém GitHub repozitáři.

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

bash

npx lingo.dev@latest run --frozen

Přidejte to jako samostatný CI krok před kompilací assetů nebo sestavením kontejneru:

yaml

- name: Verify translations
  run: npx lingo.dev@latest run --frozen
- name: Precompile assets
  run: bundle exec rails assets:precompile

Další kroky#

Lokalizace statického obsahu

Markdown, MDX, JSON, YAML a další typy bucketů

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