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]

Esta configuración indica a Rails:

• El inglés (:en) es el idioma predeterminado
• La aplicación admite inglés, español y alemán
• Los usuarios pueden cambiar entre estos tres idiomas

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

Esto crea URL específicas de configuración regional para su aplicación Rails. Los usuarios pueden acceder a diferentes versiones de idioma cambiando el parámetro de configuración regional en la URL.

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

Este código:

• Lee la configuración regional del parámetro de URL
• Recurre a la configuración regional predeterminada si no hay ningún parámetro presente
• 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 globales necesitan una forma de cambiar entre idiomas. Rails hace esto sencillo porque el método default_url_options en ApplicationController incluye automáticamente la configuración regional actual en todas las URL generadas.

Esto significa que puede crear un selector de idiomas 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, el selector se añade 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
• Rails renderiza la página en el nuevo idioma

Debido a que definió default_url_options en ApplicationController, Rails incluye automáticamente la configuración regional en todos los enlaces generados. Esto significa que la configuración regional persiste mientras los usuarios navegan por su aplicación. 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

Rails utiliza el auxiliar integrado I18n.t (o simplemente t) para buscar cadenas de sus archivos de traducción.

<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>

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.

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: "Hora actual: %{time}"

current_time: "Current time: %{time}"

Cuando llama al auxiliar t con time: @time, Rails reemplaza %{time} con el valor real. Puede utilizar los nombres de variables 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:

<!-- En lugar de esto: -->
<%= t('home.index.hello') %>

<!-- Puede escribir esto: -->
<%= 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, necesita definir esas claves en un archivo YAML. Rails almacena estas definiciones en el directorio config/locales/.

Añadir claves a su archivo en inglés

Los archivos de traducción de Rails utilizan una estructura simple de clave-valor. 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"

En esta estructura Rails i18n:

• en es el código de idioma (inglés)
• hello, current_time y refresh son claves de traducción
• Las cadenas de la derecha son el texto real
• %{time} es un placeholder para contenido dinámico (interpolación)

Este es su archivo fuente. Contiene todo el texto en su idioma predeterminado. Más adelante en este tutorial, utilizará PTC para generar automáticamente versiones en español, alemán y otros idiomas.

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

Sus vistas de Rails están ahora internacionalizadas, pero ¿qué pasa con JavaScript? Rails no extrae automáticamente texto de archivos JavaScript. Si su aplicación tiene texto del lado del cliente como alertas, información sobre herramientas o mensajes de confirmación, necesita añadirlos a su archivo de traducción en inglés.

Por ejemplo, para traducir una ventana emergente de confirmación, añada la cadena a config/locales/en.yml:

# 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.