Skip to main content

Rails i18n: повний посібник з інтернаціоналізації Ruby on Rails

Від першого файлу локалі до розгортання у виробничому середовищі: налаштуйте Rails I18n, використовуйте допоміжну функцію t(), обробляйте форми множини CLDR, виправляйте поширені помилки й додавайте продумані ланцюжки резервних локалей.

1

Архітектура Rails I18n

Rails постачається з вбудованим gem-пакетом I18n. Файли перекладу зберігаються в config/locales/ у форматі YAML (за замовчуванням) або Ruby. Фреймворк надає допоміжну функцію t() (псевдонім I18n.translate) у представленнях, контролерах, моделях і поштових класах. Rails I18n навмисно спроєктований просто: він без додаткових налаштувань підтримує базовий переклад, інтерполяцію та плюралізацію.

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 автоматично завантажує всі файли .yml і .rb із config/locales/. Ви можете впорядкувати їх як завгодно: за мовою (en.yml, de.yml), за функцією (en/users.yml, en/orders.yml) або обома способами (en/users.yml, de/users.yml). Rails об’єднує всі файли під час запуску.
2

Налаштування локалей

Задайте default_locale, available_locales і поведінку резервних локалей у config/application.rb або ініціалізаторі. Налаштуйте визначення локалі в ApplicationController за допомогою before_action, щоб отримувати її з URL-адреси, сеансу, cookie або заголовка 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"
Задавати I18n.locale у before_action безпечно для окремих запитів, але змінювати I18n.default_locale під час виконання небезпечно: це глобальне значення впливає на всі потоки. Для зміни локалі в межах запиту завжди використовуйте локальне для потоку значення I18n.locale, а не I18n.default_locale.
3

Використання допоміжної функції t()

Допоміжна функція t() доступна в усьому Rails: у представленнях, контролерах, моделях, поштових класах і фонових завданнях. Вона приймає ключ, необов’язкові змінні інтерполяції та такі параметри, як значення за замовчуванням і область. У представленнях Rails підтримує скорочений пошук, який автоматично визначає область ключів за поточним контролером і дією.

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

Обробка форм множини

Rails I18n використовує категорії множини CLDR: zero, one, two, few, many, other. Для англійської потрібні лише one та other, але інші мови потребують більше форм. Визначайте переклади форм множини як вкладені ключі YAML у категоріях count, потрібних цільовим мовам.

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 створює помилку I18n::InvalidPluralizationData, якщо для активної локалі немає обов’язкової категорії множини. Якщо у Вашій російській локалі визначено лише one та other, скопійовані з англійської, значення 2, 3 і 4 спричинять аварійне завершення, оскільки російська потребує категорії few. Завжди визначайте всі категорії CLDR для кожної мови.
5

Додавання ланцюжків резервних локалей

Вбудований механізм I18n.fallbacks у Rails забезпечує лише базовий перехід від регіональної локалі до локалі за замовчуванням. Якщо для користувача pt-BR немає певного ключа, він побачить англійський переклад замість pt-PT. rails-locale-chain додає налаштовувані ланцюжки з рекурсивним об’єднанням, щоб користувачі регіональних локалей завжди бачили найближчий доступний переклад.

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 містить понад 75 вбудованих ланцюжків резервних локалей для 11 мовних сімей. Додайте його до Gemfile і налаштуйте в ініціалізаторі — після цього користувачі регіональних локалей відразу бачитимуть переклади батьківської локалі замість прогалин, заповнених англійською.
6

Автоматизація перекладів

Завершивши налаштування Rails I18n, перекладіть файли локалей YAML за допомогою ШІ. i18n Agent має вбудовану підтримку YAML: укажіть вихідний файл локалі, і він створить переклади всіма цільовими мовами, зберігши вкладені ключі, змінні інтерполяції та форми множини.

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
Перекладайте поступово: коли додаєте нові ключі, перекладайте лише різницю. Так Ви збережете наявні переклади й не створюватимете незмінені рядки повторно.

Поширені помилки

Помилки InvalidPluralizationData

Rails аварійно завершує роботу з помилкою I18n::InvalidPluralizationData, коли немає обов’язкової категорії множини CLDR. Найчастіше це трапляється, коли англійські форми множини (one/other) копіюють до мов, яким потрібні додаткові категорії (для російської потрібна категорія few, для арабської — категорії zero/two/few/many). Установіть rails-i18n, щоб отримати правильні правила CLDR, і визначте всі категорії.

Скорочений пошук поза представленнями

Скорочений пошук (t('.key')) працює лише в представленнях, де Rails відомі контролер і дія. Використання t('.key') у моделі, поштовому класі або сервісному об’єкті повертає помилку про відсутній переклад. Поза представленнями використовуйте повні ключі (t('users.show.key')).

Синтаксичні помилки YAML порушують роботу всіх перекладів

Одна синтаксична помилка YAML — неправильний відступ, спеціальні символи без лапок або табуляція замість пробілів — перешкоджає завантаженню всього файлу локалі. Усі переклади в цьому файлі повертають помилки про відсутні ключі. Перевіряйте файли YAML у CI за допомогою лінтера й беріть у лапки рядки, що містять двокрапки, дужки або спеціальні символи на початку.

Спробуйте i18n Agent зараз

Перетягніть сюди файл для перекладу

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

або натисніть, щоб вибрати

Цільові мови

Реєстрація не потрібнаМиттєвий розрахунок

Поширені запитання про Rails i18n