Skip to main content

Rails i18n: kompletná príručka internacionalizácie Ruby on Rails

Od prvého lokalizačného súboru po produkciu: nakonfigurujte Rails I18n, používajte pomocnú funkciu t(), spracujte tvary množného čísla CLDR, opravte bežné nástrahy a pridajte inteligentné reťazce náhradných lokalizácií.

1

Pochopte architektúru Rails I18n

Rails obsahuje vstavaný gem I18n. Prekladové súbory sa nachádzajú v config/locales/ vo formáte YAML (predvolený) alebo Ruby. Framework poskytuje pomocnú funkciu t() (alias I18n.translate) v zobrazeniach, kontroléroch, modeloch a maileroch. Rails I18n je zámerne jednoduchý – hneď po inštalácii spracúva základný preklad, interpoláciu a tvary množného čísla.

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čítava všetky súbory .yml a .rb z config/locales/. Môžete ich usporiadať ľubovoľne – podľa jazyka (en.yml, de.yml), funkcie (en/users.yml, en/orders.yml) alebo oboch (en/users.yml, de/users.yml). Rails pri spustení zlúči všetky súbory.
2

Nakonfigurujte nastavenia lokalizácie

Nastavte default_locale, available_locales a správanie náhrad v config/application.rb alebo inicializátore. Rozpoznávanie lokalizácie nakonfigurujte v ApplicationController pomocou before_action, ktoré nastaví lokalizáciu podľa URL, relácie, súboru cookie alebo 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"
Nastavenie I18n.locale v before_action je bezpečné pre jednotlivé požiadavky, no nastavenie I18n.default_locale za behu je globálne a ovplyvňuje všetky vlákna. Pri zmenách lokalizácie v rozsahu požiadavky vždy používajte I18n.locale (lokálne pre vlákno), nikdy I18n.default_locale.
3

Používajte pomocnú funkciu t()

Pomocná funkcia t() je dostupná všade v Rails – v zobrazeniach, kontroléroch, modeloch, maileroch aj úlohách. Prijíma kľúč, voliteľné interpolačné premenné a voľby, ako sú predvolené hodnoty a rozsah. V zobrazeniach Rails podporuje lenivé vyhľadávania, ktoré automaticky obmedzia kľúče na aktuálny kontrolér a akciu.

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

Spracujte tvary množného čísla

Rails I18n používa kategórie množného čísla CLDR: zero, one, two, few, many, other. Angličtina potrebuje iba one a other, iné jazyky však viac tvarov. Preklady množného čísla definujte ako vnorené kľúče YAML pod kategóriami počtu, ktoré vyžadujú Vaše cieľové jazyky.

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) %>
Ak v aktívnej lokalizácii chýba požadovaná kategória množného čísla, Rails vyvolá I18n::InvalidPluralizationData. Ak Vaša ruská lokalizácia definuje iba one a other (skopírované z angličtiny), počty ako 2, 3 a 4 spôsobia pád, pretože ruština vyžaduje kategóriu few. Pre každý jazyk vždy definujte všetky kategórie CLDR.
5

Pridajte reťazce náhradných lokalizácií

Vstavané I18n.fallbacks v Rails poskytuje iba základnú náhradu z regionálnej na predvolenú lokalizáciu. Používateľ pt-BR s chýbajúcim kľúčom uvidí angličtinu namiesto pt-PT. rails-locale-chain pridáva konfigurovateľné reťazce s hĺbkovým zlúčením, aby regionálni používatelia vždy videli najbližší dostupný preklad.

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 viac ako 75 vstavaných reťazcov náhrad pre 11 jazykových rodín. Pridajte ho do Gemfile, nakonfigurujte v inicializátore a regionálni používatelia okamžite uvidia preklady nadradenej lokalizácie namiesto anglických medzier.
6

Automatizujte preklady

Po dokončení nastavenia Rails I18n preložte svoje lokalizačné súbory YAML pomocou AI. i18n Agent natívne podporuje YAML – zadajte mu zdrojový lokalizačný súbor a vygeneruje všetky cieľové jazyky so zachovaním vnorených kľúčov, interpolačných premenných a tvarov množného čísla.

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
Prekladajte prírastkovo – po pridaní nových kľúčov preložte iba rozdiel. Zachováte tak existujúce preklady a vyhnete sa opätovnému generovaniu nezmenených reťazcov.

Bežné nástrahy

Chyby InvalidPluralizationData

Rails spadne s I18n::InvalidPluralizationData, keď chýba požadovaná kategória množného čísla CLDR. Najčastejšie sa to stane, keď sa anglické tvary (one/other) skopírujú do jazykov, ktoré potrebujú viac kategórií (ruština potrebuje few, arabčina zero/two/few/many). Nainštalujte rails-i18n pre správne pravidlá CLDR a definujte všetky kategórie.

Lenivé vyhľadávania mimo zobrazení

Lenivé vyhľadávania (t('.key')) fungujú iba v zobrazeniach, kde Rails pozná kontrolér a akciu. Použitie t('.key') v modeli, maileri alebo objekte služby vráti chybu chýbajúceho prekladu. Mimo zobrazení používajte úplné kľúče (t('users.show.key')).

Chyby syntaxe YAML narušia všetky preklady

Jediná chyba syntaxe YAML (nesprávne odsadenie, špeciálne znaky bez úvodzoviek, tabulátor namiesto medzier) zabráni načítaniu celého lokalizačného súboru. Všetky preklady v danom súbore vrátia chyby chýbajúceho kľúča. Súbory YAML overujte v CI linterom a reťazce obsahujúce dvojbodky, zátvorky alebo úvodné špeciálne znaky zapisujte v úvodzovkách.

Vyskúšajte i18n Agent teraz

Potiahnite súbor na preklad sem

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

alebo kliknite a vyberte súbor

Cieľové jazyky

Bez registrácieOkamžitý odhad

Časté otázky k Rails i18n