Guía de internacionalización (i18n) y localización de Rails

Configuración de la internacionalización (i18n) de Rails

La internacionalización de Rails requiere tres pasos de configuración: establecer las configuraciones regionales disponibles, añadir la configuración regional a sus URL y hacer que Rails cargue la configuración regional correcta para cada solicitud. También querrá instalar la gema rails-i18n, que proporciona datos de configuración regional como nombres de meses traducidos, reglas de pluralización y mensajes de error predeterminados de Rails.

Establecer las configuraciones regionales disponibles

Primero, en config/application.rb, indique a Rails qué idiomas debe admitir la aplicación y establezca una configuración regional predeterminada:

config.i18n.default_locale = :en
config.i18n.available_locales = [:en, :es, :de]

config.i18n.default_locale = :en
config.i18n.available_locales = [:en, :es, :de]

Esto le indica a Rails que el inglés es el idioma predeterminado y que la aplicación admite inglés, español y alemán. Puede añadir los códigos de idioma que necesite.

Añadir configuración regional a las URL

A continuación, añada la configuración regional a la URL para que cada idioma tenga su propia ruta, como /en/time o /es/time:

# config/routes.rb
scope "/:locale" do
  get '/time', to: 'home#index', as: :time_display
end

# config/routes.rb
scope "/:locale" do
  get '/time', to: 'home#index', as: :time_display
end

Configurar el cambio de configuración regional

Por último, en app/controllers/application_controller.rb, asegúrese de que Rails cargue la configuración regional correcta desde la URL y la incluya en todos los enlaces:

class ApplicationController < ActionController::Base
  around_action :switch_locale

  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

class ApplicationController < ActionController::Base
  around_action :switch_locale

  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

Esto lee la configuración regional del parámetro de la URL, recurre a la configuración regional predeterminada si no hay ninguna presente y garantiza que todas las URL generadas incluyan la configuración regional actual.

Instalar la gema rails-i18n

La gema rails-i18n proporciona datos de configuración regional para múltiples idiomas, incluidos nombres de meses traducidos, reglas de pluralización y mensajes de error predeterminados de Rails. Esto le ahorra tener que traducir estas cadenas estándar usted mismo.

Añádala a su Gemfile:

gem 'rails-i18n'

Luego ejecute:

bundle install

Rails está ahora completamente configurado para la internacionalización.

Añadir un selector de idiomas

Ahora que su aplicación Rails admite múltiples configuraciones regionales, sus usuarios necesitan una forma de cambiar entre idiomas. Dado que el método default_url_options en ApplicationController incluye automáticamente la configuración regional actual en todas las URL generadas, puede crear un selector que solo actualice el parámetro de configuración regional mientras mantiene al usuario en la misma página.

Crear la interfaz del selector de idiomas

Añada el selector de idiomas a su archivo de diseño. En nuestra aplicación de demostración, va en app/views/layouts/application.html.erb:

<nav>
  <%= link_to "English", url_for(locale: :en) %> |
  <%= link_to "Español", url_for(locale: :es) %> |
  <%= link_to "Deutsch", url_for(locale: :de) %>
</nav>

<nav>
  <%= link_to "English", url_for(locale: :en) %> |
  <%= link_to "Español", url_for(locale: :es) %> |
  <%= link_to "Deutsch", url_for(locale: :de) %>
</nav>

Cada enlace utiliza url_for(locale: :locale_code) para generar una URL con la configuración regional especificada. Cuando un usuario hace clic en un enlace, el método switch_locale en ApplicationController detecta el cambio y Rails renderiza la página en el nuevo idioma.

Dado que default_url_options está definido, la configuración regional persiste a medida que los usuarios navegan. No necesita añadir manualmente parámetros de configuración regional a cada enlace.

Dar estilo a su selector de idiomas

Puede dar estilo al selector de idiomas en app/assets/stylesheets/application.css para que coincida con su diseño. La aplicación de demostración incluye estilos básicos para hacer que el selector sea visible y fácil de usar.

Configuración de claves de traducción en vistas de Rails

Antes de poder traducir su aplicación, todo el texto visible para el usuario debe estar en archivos i18n de Rails en lugar de estar codificado. Rails proporciona el método auxiliar t (abreviatura de translate) para buscar y mostrar cadenas traducidas.

Reemplazar texto codificado con claves de traducción

El texto codificado no aparecerá en su archivo YAML, lo que significa que no se puede traducir más adelante. Utilice siempre claves de traducción para cualquier texto visible para el usuario.

<h1><%= t(:hello) %></h1>
<p><%= t(:current_time, time: @time) %></p>
<button id="click-me"><%= t(:refresh) %></button>

<h1><%= t(:hello) %></h1>
<p><%= t(:current_time, time: @time) %></p>
<button id="click-me"><%= t(:refresh) %></button>

<h1>Hello</h1>
<p>Current time: <%= @time %></p>
<button>Refresh</button>

<h1>Hello</h1>
<p>Current time: <%= @time %></p>
<button>Refresh</button>

Uso de interpolación en traducciones

¿Ha notado el parámetro time: @time en el ejemplo anterior? Esto se llama interpolación: le permite insertar valores dinámicos en sus traducciones. La cadena de traducción en su archivo YAML utiliza %{time} como placeholder:

current_time: "Current time: %{time}"

current_time: "Current time: %{time}"

Cuando llama al auxiliar t con time: @time, Rails reemplaza %{time} con el valor real. Puede usar los nombres de variable que desee, solo asegúrese de que coincidan entre el archivo YAML y su vista.

Búsqueda diferida para un código más limpio

Cuando sus claves de traducción están organizadas para coincidir con la estructura de carpetas de su vista, Rails le permite utilizar un atajo llamado búsqueda diferida. En lugar de escribir la ruta completa de la clave, utilice un punto inicial:

<!-- Instead of this: -->
<%= t('home.index.hello') %>

<!-- You can write this: -->
<%= t('.hello') %>

<!-- Instead of this: -->
<%= t('home.index.hello') %>

<!-- You can write this: -->
<%= t('.hello') %>

Rails examina en qué archivo de vista se encuentra (home/index.html.erb) y añade automáticamente home.index. delante de su clave. Esto mantiene su código más limpio y facilita mover vistas. Si cambia el nombre o reubica una vista, las rutas de búsqueda diferida se actualizan automáticamente.

Creación y organización de archivos de traducción

Ahora que ha añadido claves de traducción a sus vistas, debe definir esas claves en un archivo YAML. Rails las almacena en el directorio config/locales/.

Añadir claves a su archivo de idioma de origen

Abra config/locales/en.yml y añada las claves a las que hizo referencia en sus vistas:

# config/locales/en.yml
en:
  hello: "Hello"
  current_time: "Current time: %{time}"
  refresh: "Refresh"

# config/locales/en.yml
en:
  hello: "Hello"
  current_time: "Current time: %{time}"
  refresh: "Refresh"

Este es su archivo de origen: contiene todo el texto en su idioma predeterminado. Las claves de la izquierda son a las que hacen referencia sus vistas; las cadenas de la derecha son lo que se muestra.

Organización de claves con anidamiento

Para utilizar la búsqueda diferida (el atajo .hello de la sección anterior), organice sus claves para que coincidan con la estructura de carpetas de su vista:

en:
  home:
    index:
      hello: "Hello"
      current_time: "Current time: %{time}"
      refresh: "Refresh"

en:
  home:
    index:
      hello: "Hello"
      current_time: "Current time: %{time}"
      refresh: "Refresh"

Esto agrupa todas las traducciones para app/views/home/index.html.erb bajo home.index. Ahora puede utilizar t('.hello') en esa vista en lugar de t('home.index.hello').

A medida que su aplicación Rails crece, también puede crear espacios de nombres para traducciones compartidas (como shared.navigation para menús) para mantener las cosas organizadas, pero esto es opcional.

Añadir cadenas de JavaScript a YAML

Rails no extrae automáticamente texto de los archivos JavaScript. Si su aplicación tiene texto del lado del cliente, como alertas, información sobre herramientas o mensajes de confirmación, añádalos a su archivo de traducción al inglés:

# config/locales/en.yml
en:
  confirm: "Are you sure?"

# config/locales/en.yml
en:
  confirm: "Are you sure?"

En este punto, su archivo en.yml contiene todo el texto que aparece en su aplicación, tanto en vistas de Rails como en JavaScript.

Cuando utilice PTC para traducir su aplicación (cubierto en la siguiente sección), estas cadenas de JavaScript se traducirán junto con todo lo demás.