Skip to main content

Rails i18n: kompletny przewodnik po internacjonalizacji Ruby on Rails

Od pierwszego pliku językowego po produkcję: skonfiguruj Rails I18n, używaj funkcji pomocniczej t(), obsłuż liczbę mnogą CLDR, napraw typowe problemy i dodaj inteligentne łańcuchy rezerwowe.

1

Poznaj architekturę Rails I18n

Rails zawiera wbudowany gem I18n. Pliki tłumaczeń znajdują się w config/locales/ jako YAML (domyślnie) lub pliki Ruby. Framework udostępnia funkcję pomocniczą t() (alias I18n.translate) w widokach, kontrolerach, modelach i mailerach. Rails I18n jest celowo prosty — zapewnia gotowe podstawowe tłumaczenie, interpolację i liczbę mnogą.

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 automatycznie wczytuje wszystkie pliki .yml i .rb z config/locales/. Możesz uporządkować je dowolnie — według języka (en.yml, de.yml), funkcji (en/users.yml, en/orders.yml) albo obu tych kryteriów (en/users.yml, de/users.yml). Rails scala wszystkie pliki podczas uruchamiania.
2

Skonfiguruj ustawienia językowe

Ustaw default_locale, available_locales i mechanizm rezerwowy w config/application.rb lub inicjalizatorze. Skonfiguruj wykrywanie języka w ApplicationController za pomocą before_action, aby ustawiać język z adresu URL, sesji, pliku cookie lub nagłówka 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"
Ustawianie I18n.locale w before_action jest bezpieczne dla poszczególnych żądań, ale zmiana I18n.default_locale podczas działania ma zasięg globalny i wpływa na wszystkie wątki. Do zmian języka ograniczonych do żądania zawsze używaj I18n.locale (lokalnego dla wątku), a nigdy I18n.default_locale.
3

Używaj funkcji pomocniczej t()

Funkcja pomocnicza t() jest dostępna w całym frameworku Rails — widokach, kontrolerach, modelach, mailerach i zadaniach. Przyjmuje klucz, opcjonalne zmienne interpolacji oraz opcje takie jak wartości domyślne i zakres. W widokach Rails obsługuje leniwe wyszukiwanie, które automatycznie ogranicza klucze do bieżącego kontrolera i akcji.

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

Obsłuż liczbę mnogą

Rails I18n używa kategorii liczby mnogiej CLDR: zero, one, two, few, many, other. Angielski wymaga tylko one i other, ale inne języki potrzebują większej liczby form. Zdefiniuj tłumaczenia liczby mnogiej jako zagnieżdżone klucze YAML pod kategoriami count wymaganymi przez języki docelowe.

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 zgłasza I18n::InvalidPluralizationData, jeśli brakuje kategorii liczby mnogiej wymaganej przez aktywny język. Jeśli rosyjski plik zawiera tylko one i other (skopiowane z angielskiego), liczby takie jak 2, 3 i 4 spowodują awarię, ponieważ rosyjski wymaga kategorii few. Zawsze definiuj wszystkie kategorie CLDR dla każdego języka.
5

Dodaj łańcuchy rezerwowe

Wbudowany mechanizm I18n.fallbacks w Rails zapewnia tylko podstawowe przejście z wariantu regionalnego do języka domyślnego. Użytkownik pt-BR z brakującym kluczem widzi angielski zamiast pt-PT. rails-locale-chain dodaje konfigurowalne łańcuchy głębokiego scalania, dzięki którym użytkownicy wariantów regionalnych zawsze widzą najbliższe dostępne tłumaczenie.

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 zawiera ponad 75 wbudowanych łańcuchów rezerwowych obejmujących 11 rodzin językowych. Dodaj go do Gemfile, skonfiguruj w inicjalizatorze, a użytkownicy wariantów regionalnych od razu zobaczą tłumaczenia języka nadrzędnego zamiast braków wypełnionych angielskim.
6

Zautomatyzuj tłumaczenia

Po skonfigurowaniu Rails I18n tłumacz pliki językowe YAML za pomocą AI. i18n Agent natywnie obsługuje YAML — wskaż plik języka źródłowego, a narzędzie wygeneruje wszystkie języki docelowe z zachowaniem zagnieżdżonych kluczy, zmiennych interpolacji i form liczby mnogiej.

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
Tłumacz przyrostowo — po dodaniu nowych kluczy przetłumacz tylko różnicę. Pozwala to zachować istniejące tłumaczenia i uniknąć ponownego generowania niezmienionych tekstów.

Typowe pułapki

Błędy InvalidPluralizationData

Rails ulega awarii z I18n::InvalidPluralizationData, gdy brakuje wymaganej kategorii liczby mnogiej CLDR. Najczęściej dzieje się tak po skopiowaniu angielskich form (one/other) do języków wymagających większej liczby kategorii (rosyjski wymaga few, a arabski zero/two/few/many). Zainstaluj rails-i18n, aby uzyskać poprawne reguły CLDR i zdefiniuj wszystkie kategorie.

Leniwe wyszukiwanie poza widokami

Leniwe wyszukiwanie (t('.key')) działa tylko w widokach, w których Rails zna kontroler i akcję. Użycie t('.key') w modelu, mailerze lub obiekcie usługi zwraca błąd brakującego tłumaczenia. Poza widokami używaj pełnych kluczy (t('users.show.key')).

Błędy składni YAML psują wszystkie tłumaczenia

Pojedynczy błąd składni YAML (nieprawidłowe wcięcie, specjalne znaki bez cudzysłowu lub tabulator zamiast spacji) uniemożliwia wczytanie całego pliku językowego. Wszystkie zawarte w nim tłumaczenia zwracają błędy brakujących kluczy. Sprawdzaj pliki YAML w CI za pomocą lintera i umieszczaj w cudzysłowie teksty zawierające dwukropki, nawiasy lub specjalne znaki na początku.

Wypróbuj i18n Agent

Upuść tutaj plik tłumaczenia

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

lub kliknij, aby go wybrać

Języki docelowe

Rejestracja nie jest wymaganaNatychmiastowa wycena

Najczęstsze pytania o Rails i18n