Skip to main content

Rails i18n: Пълно ръководство за интернационализация на Ruby on Rails

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

1

Разберете архитектурата на Rails I18n

Rails включва вградения пакет 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 или в initializer. Конфигурирайте разпознаването на езиковата настройка във Вашия ApplicationController чрез before_action, за да я зададете от URL адреса, сесията, бисквитка или заглавката 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 ключове под категориите за брой, изисквани от целевите езици.

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 и го конфигурирайте в initializer, за да могат регионалните потребители веднага да виждат преводите от родителската езикова настройка вместо липсващи текстове, заместени с английски.
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