Skip to main content

i18n en Rails: guía completa de internacionalización con Ruby on Rails

Del primer archivo regional a producción: configure Rails I18n, utilice t(), gestione pluralización CLDR, corrija errores habituales y añada cadenas regionales inteligentes.

1

Comprender la arquitectura de Rails I18n

Rails incluye la gema I18n. Los archivos residen en config/locales/ como YAML —predeterminado— o Ruby. El framework ofrece t() —alias de I18n.translate— en vistas, controladores, modelos y mailers. Rails I18n es sencillo por diseño y gestiona traducción básica, interpolación y pluralización.

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 carga automáticamente todos los .yml y .rb de config/locales/. Puede organizarlos por idioma —en.yml o de.yml—, por funcionalidad —en/users.yml— o ambos. Rails combina todos los archivos al iniciar.
2

Configurar los ajustes regionales

Defina default_locale, available_locales y el respaldo en config/application.rb o un inicializador. Configure la detección en ApplicationController mediante before_action para obtener la configuración regional desde la URL, la sesión, la cookie o 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"
Definir I18n.locale en before_action es seguro por solicitud, pero cambiar I18n.default_locale durante la ejecución es global y afecta a todos los hilos. Utilice siempre I18n.locale —local al hilo— para cambios por solicitud, nunca I18n.default_locale.
3

Utilizar el helper t()

t() está disponible en todas partes: vistas, controladores, modelos, mailers y jobs. Acepta una clave, variables opcionales y opciones como valores predeterminados y scope. En vistas, Rails admite búsquedas diferidas que limitan automáticamente la clave al controlador y la acción actuales.

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 pluralización

Rails I18n utiliza categorías CLDR: zero, one, two, few, many y other. El inglés solo necesita one y other, pero otros idiomas requieren más. Defina las traducciones como claves YAML anidadas bajo las categorías necesarias.

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 lanza I18n::InvalidPluralizationData si falta una categoría obligatoria. Si el ruso solo define one y other —copiados del inglés—, los números 2, 3 y 4 harán que la aplicación se bloquee porque necesita few. Defina siempre todas las categorías CLDR del idioma.
5

Añadir cadenas de respaldo regional

I18n.fallbacks integrado en Rails solo proporciona un respaldo básico de región a valor predeterminado. Un usuario pt-BR con una clave ausente ve inglés en vez de pt-PT. rails-locale-chain añade cadenas configurables con combinación en profundidad para mostrar la traducción más próxima.

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 incluye más de 75 cadenas para 11 familias. Añádala a Gemfile, configúrela en un inicializador y los usuarios regionales verán de inmediato traducciones principales en vez de huecos en inglés.
6

Automatizar traducciones

Cuando complete la configuración, traduzca los archivos YAML con IA. i18n Agent admite YAML de forma nativa: indique el archivo de origen y generará todos los idiomas conservando claves anidadas, variables y plurales.

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
Traduzca de forma incremental: cuando añada claves nuevas, traduzca solo las diferencias. Así conserva las traducciones existentes y evita regenerar cadenas sin cambios.

Errores habituales

Errores InvalidPluralizationData

Rails se bloquea con I18n::InvalidPluralizationData si falta una categoría CLDR. Suele ocurrir al copiar one/other del inglés a idiomas que necesitan más —ruso necesita few; árabe, zero/two/few/many—. Instale rails-i18n y defina todas las categorías.

Búsquedas diferidas fuera de las vistas

Las búsquedas diferidas —t('.key')— solo funcionan en vistas donde Rails conoce el controlador y la acción. En un modelo, mailer o servicio devuelven un error de traducción ausente. Utilice claves completas —t('users.show.key')— fuera de las vistas.

Los errores de sintaxis YAML rompen todas las traducciones

Un solo error —sangría incorrecta, caracteres especiales sin comillas o tabulaciones— impide cargar todo el archivo. Todas sus traducciones devuelven claves ausentes. Valide YAML en CI y entrecomille cadenas con dos puntos, corchetes o caracteres especiales iniciales.

Pruebe i18n Agent ahora

Arrastre y suelte aquí su archivo de traducción

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

o haga clic para seleccionar

Idiomas de destino

No es necesario registrarsePresupuesto al instante

Preguntas frecuentes sobre i18n en Rails