Skip to main content

Rails i18n: Kompletní průvodce internacionalizací pro Ruby on Rails

Od prvního souboru locale po produkci: nakonfigurujte Rails I18n, používejte helper t(), řešte pluralizaci podle CLDR, opravte běžná úskalí a přidejte inteligentní locale fallback řetězce.

1

Pochopte architekturu Rails I18n

Rails obsahuje gem I18n vestavěně. Překladové soubory jsou v config/locales/ jako YAML (výchozí) nebo Ruby soubory. Framework poskytuje helper t() (alias pro I18n.translate) ve views, controllerech, modelech i mailerech. Rails I18n je záměrně jednoduché — out of the box řeší základní překlad, interpolaci i pluralizaci.

config/application.rb
# Rails includes i18n out of the box via the i18n gem
# config/application.rb
module MyApp
  class Application < Rails::Application
    # Default locale
    config.i18n.default_locale = :en

    # Available locales
    config.i18n.available_locales = [:en, :de, :ja, :es, :fr, :'pt-BR']

    # Fallback to default locale when translation is missing
    config.i18n.fallbacks = true

    # Load translations from nested directories
    config.i18n.load_path += Dir[Rails.root.join('config', 'locales', '**', '*.{rb,yml}')]
  end
end
config/routes.rb
# config/routes.rb
Rails.application.routes.draw do
  scope "/:locale", locale: /en|de|ja|es|fr|pt-BR/ do
    root "home#index"
    resources :products
  end

  root "home#index"
end

# app/controllers/application_controller.rb
class ApplicationController < ActionController::Base
  around_action :switch_locale

  private

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

  def default_url_options
    { locale: I18n.locale }
  end
end
Rails automaticky načítá všechny soubory .yml a .rb z config/locales/. Můžete je uspořádat, jak chcete — podle jazyka (en.yml, de.yml), podle feature (en/users.yml, en/orders.yml) nebo obojí (en/users.yml, de/users.yml). Rails všechny soubory sloučí při bootu.
2

Nakonfigurujte nastavení locale

Nastavte default_locale, available_locales a fallback chování v config/application.rb nebo v initializeru. Detekci locale nakonfigurujte v ApplicationController pomocí before_action, který nastaví locale podle URL, session, cookie nebo hlavičky Accept-Language.

config/locales/en.yml
# config/locales/en.yml
en:
  nav:
    home: "Home"
    about: "About"
    settings: "Settings"
  greeting: "Hello, %{name}!"
  cart:
    item_count:
      one: "%{count} item"
      other: "%{count} items"

# config/locales/de.yml
de:
  nav:
    home: "Startseite"
    about: "Über uns"
    settings: "Einstellungen"
  greeting: "Hallo, %{name}!"
  cart:
    item_count:
      one: "%{count} Artikel"
      other: "%{count} Artikel"
Nastavení I18n.locale v before_action je pro jednotlivé požadavky bezpečné, ale změna I18n.default_locale za běhu je globální a ovlivňuje všechna vlákna. Pro změny locale v rámci požadavku vždy používejte I18n.locale (thread-local), nikdy I18n.default_locale.
3

Používejte helper t()

Helper t() je v Rails dostupný všude — ve views, controllerech, modelech, mailerech i jobech. Přijímá klíč, volitelné interpolační proměnné a volby jako výchozí hodnoty a scope. Ve views Rails podporuje lazy lookups, které automaticky nastavují scope klíčů podle aktuálního controlleru a action.

app/views/example.html.erb
# In views (ERB)
<h1><%= t('nav.home') %></h1>
<p><%= t('greeting', name: @user.name) %></p>

# In controllers
flash[:notice] = t('flash.product_created')

# In models
validates :name, presence: { message: I18n.t('errors.blank') }

# With HTML (safe)
<%= t('terms_html', link: link_to(t('terms_link'), '/terms')) %>
4

Zpracování plurálu

Rails I18n používá kategorie plurálu CLDR: zero, one, two, few, many, other. Angličtina potřebuje pouze one a other, ale jiné jazyky vyžadují více tvarů. Překlady plurálu definujte jako vnořené YAML klíče pod kategoriemi count, které Vaše cílové jazyky vyžadují.

Plural forms
# In YAML:
en:
  cart:
    item_count:
      zero: "No items"
      one: "%{count} item"
      other: "%{count} items"

# Arabic (6 forms):
ar:
  cart:
    item_count:
      zero: "لا عناصر"
      one: "عنصر واحد"
      two: "عنصران"
      few: "%{count} عناصر"
      many: "%{count} عنصرًا"
      other: "%{count} عنصر"

# Usage in views:
<%= t('cart.item_count', count: @cart.items.size) %>
Rails vyhodí I18n::InvalidPluralizationData, pokud pro aktivní locale chybí požadovaná kategorie plurálu. Pokud Vaše ruské locale definuje jen one a other (zkopírované z angličtiny), počty jako 2, 3, 4 způsobí pád, protože ruština vyžaduje kategorii few. Vždy definujte pro každý jazyk všechny kategorie CLDR.
5

Přidat fallback řetězce locale

Vestavěné I18n.fallbacks v Rails poskytuje jen základní fallback z regionálního locale na výchozí locale. Uživatel pt-BR s chybějícím klíčem uvidí angličtinu místo pt-PT. rails-locale-chain přidává konfigurovatelné deep-merge řetězce, takže regionální uživatelé vždy uvidí nejbližší dostupný překlad.

Lazy lookups
# Lazy lookups use the controller/action as scope
# app/views/products/index.html.erb
# Instead of t('products.index.title'), just use:
<h1><%= t('.title') %></h1>
<p><%= t('.description') %></p>

# Rails looks up: products.index.title and products.index.description

# config/locales/en.yml
en:
  products:
    index:
      title: "All Products"
      description: "Browse our catalog"
rails-locale-chain obsahuje přes 75 vestavěných fallback řetězců pokrývajících 11 jazykových rodin. Přidejte jej do Gemfile, nakonfigurujte v initializeru a regionální uživatelé okamžitě uvidí překlady nadřazeného locale místo anglických mezer.
6

Automatizovat překlady

S dokončeným nastavením Rails I18n přeložte své YAML locale soubory pomocí AI. i18n Agent nativně podporuje YAML — namiřte jej na zdrojový locale soubor a vygeneruje všechny cílové jazyky se zachováním vnořených klíčů, proměnných interpolace a tvarů plurálu.

config/initializers/locale_chain.rb
# Gemfile
gem 'rails-locale-chain'

# config/initializers/locale_chain.rb
Rails.application.config.i18n.fallbacks = {
  'pt-BR': ['pt', 'en'],
  'zh-Hant-TW': ['zh-Hant', 'zh', 'en'],
  'es-419': ['es', 'en'],
}

# The gem deep-merges translations across the chain
# pt-BR -> pt -> en
# Missing keys in pt-BR are filled from pt, then en
Překládejte postupně — když přidáte nové klíče, přeložte jen diff. Tím zachováte stávající překlady a vyhnete se zbytečné regeneraci nezměněných řetězců.

Běžná úskalí

Chyby InvalidPluralizationData

Rails spadne s I18n::InvalidPluralizationData, když chybí požadovaná kategorie plurálu CLDR. Nejčastěji k tomu dojde, když se anglické tvary plurálu (one/other) zkopírují do jazyků, které potřebují více kategorií (ruština potřebuje few, arabština potřebuje zero/two/few/many). Nainstalujte rails-i18n pro správná pravidla CLDR a definujte všechny kategorie.

Lazy lookups mimo views

Lazy lookups (t('.key')) fungují pouze ve views, kde Rails zná controller a action. Použití t('.key') v modelu, maileru nebo service objektu vrátí chybu chybějícího překladu. Mimo views používejte plné klíče (t('users.show.key')).

Chyby syntaxe YAML rozbijí všechny překlady

Jediná chyba syntaxe YAML (špatné odsazení, neuzavřené speciální znaky do uvozovek, tabulátor místo mezer) zabrání načtení celého locale souboru. Všechny překlady v daném souboru pak vracejí chyby chybějících klíčů. Validujte YAML soubory v CI pomocí linteru a dávejte do uvozovek řetězce, které obsahují dvojtečky, závorky nebo úvodní speciální znaky.

Vyzkoušejte i18n Agent nyní

Sem přetáhněte svůj překladový soubor

JSON, YAML, PO, XML, CSV, Markdown, Properties

nebo klikněte a vyberte soubor

Cílové jazyky

Bez registraceOkamžitý odhad

FAQ k i18n v Rails