Skip to main content

Rails i18n: guia completa d'internacionalització de Ruby on Rails

Del primer fitxer de configuració regional a producció: configuri Rails I18n, utilitzi l'auxiliar t(), gestioni la pluralització CLDR, corregeixi els errors habituals i afegeixi cadenes intel·ligents de reserva de configuracions regionals.

1

Entendre l'arquitectura de Rails I18n

Rails inclou la gemma I18n de sèrie. Els fitxers de traducció es troben a config/locales/ en format YAML (per defecte) o com a fitxers Ruby. El framework proporciona l'auxiliar t() (àlies de I18n.translate) en vistes, controladors, models i mailers. Rails I18n és senzill per disseny: gestiona de sèrie la traducció bàsica, la interpolació i la pluralització.

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 carrega automàticament tots els fitxers .yml i .rb de config/locales/. Es poden organitzar com es vulgui: per idioma (en.yml, de.yml), per funcionalitat (en/users.yml, en/orders.yml) o de totes dues maneres (en/users.yml, de/users.yml). Rails fusiona tots els fitxers en arrencar.
2

Configurar els paràmetres de configuració regional

Defineixi default_locale, available_locales i el comportament de reserva a config/application.rb o en un inicialitzador. Configuri la detecció de la configuració regional a ApplicationController mitjançant before_action per establir-la a partir de l'URL, la sessió, una galeta o la capçalera 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"
Establir I18n.locale en un before_action és segur per petició, però establir I18n.default_locale durant l'execució és global i afecta tots els fils. Utilitzi sempre I18n.locale (local del fil) per als canvis de configuració regional circumscrits a una petició, mai I18n.default_locale.
3

Utilitzar l'auxiliar t()

L'auxiliar t() està disponible arreu de Rails: vistes, controladors, models, mailers i tasques. Accepta una clau, variables d'interpolació opcionals i opcions com ara valors per defecte i un àmbit. A les vistes, Rails admet consultes diferides que ajusten automàticament l'àmbit de les claus al controlador i l'acció actuals.

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

Gestionar la pluralització

Rails I18n utilitza les categories plurals de CLDR: zero, one, two, few, many, other. L'anglès només necessita one i other, però altres idiomes requereixen més formes. Defineixi les traduccions plurals com a claus YAML imbricades sota les categories de recompte que requereixin els idiomes de destinació.

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 genera I18n::InvalidPluralizationData si falta una categoria plural obligatòria per a la configuració regional activa. Si la configuració regional russa només defineix one i other (copiades de l'anglès), recomptes com 2, 3 i 4 provocaran una fallada perquè el rus requereix la categoria few. Defineixi sempre totes les categories CLDR de cada idioma.
5

Afegir cadenes de reserva de configuracions regionals

El mecanisme I18n.fallbacks integrat a Rails només ofereix una reserva bàsica de la configuració regional a la configuració per defecte. Un usuari pt-BR que trobi una clau absent veurà l'anglès en comptes de pt-PT. rails-locale-chain afegeix cadenes configurables de fusió profunda perquè els usuaris regionals vegin sempre la traducció disponible més propera.

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 inclou més de 75 cadenes de reserva integrades que cobreixen 11 famílies lingüístiques. Afegeixi-la al Gemfile, configuri-la en un inicialitzador i els usuaris regionals veuran immediatament les traduccions de la configuració regional superior en comptes de buits en anglès.
6

Automatitzar les traduccions

Un cop completada la configuració de Rails I18n, tradueixi els fitxers YAML de configuració regional amb IA. i18n Agent admet YAML de manera nativa: indiqui-li el fitxer de configuració regional d'origen i generarà tots els idiomes de destinació, tot preservant les claus imbricades, les variables d'interpolació i les formes plurals.

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
Tradueixi de manera incremental: quan afegeixi claus noves, tradueixi només el diff. Això preserva les traduccions existents i evita regenerar les cadenes que no han canviat.

Errors habituals

Errors InvalidPluralizationData

Rails falla amb I18n::InvalidPluralizationData quan falta una categoria plural CLDR obligatòria. Sol passar quan les formes plurals de l'anglès (one/other) es copien a idiomes que necessiten més categories (el rus necessita few; l'àrab, zero/two/few/many). Instal·li rails-i18n per obtenir les regles CLDR correctes i defineixi totes les categories.

Consultes diferides fora de les vistes

Les consultes diferides (t('.key')) només funcionen en vistes, on Rails coneix el controlador i l'acció. Utilitzar t('.key') en un model, mailer o objecte de servei retorna un error de traducció absent. Fora de les vistes, utilitzi claus completes (t('users.show.key')).

Els errors de sintaxi YAML trenquen totes les traduccions

Un sol error de sintaxi YAML (sagnat incorrecte, caràcters especials sense cometes o una tabulació en comptes d'espais) impedeix que es carregui tot el fitxer de configuració regional. Totes les traduccions del fitxer retornen errors de clau absent. Validin els fitxers YAML a CI amb un linter i posin entre cometes les cadenes que continguin dos punts, claudàtors o caràcters especials inicials.

Provar i18n Agent ara

Arrossegar aquí el fitxer de traducció

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

o fer clic per explorar

Idiomes de destinació

No cal registrePressupost instantani

Preguntes freqüents sobre Rails i18n