Localiza una aplicación Rails

Traduce archivos YAML de Rails con el idioma en la raíz y verifica la búsqueda, la interpolación, las formas plurales y la selección del idioma en cada solicitud.

Rails ya asigna nombres estables a los mensajes mediante t y I18n.t. Lingo.dev puede traducir el YAML asociado a esos nombres mientras Rails sigue encargándose de la búsqueda, la interpolación y la selección del idioma. Empieza con un saludo y un conteo de notificaciones, y compruébalos con las mismas funciones auxiliares que usa la aplicación.

Agrega los mensajes de origen a un archivo de idioma de Rails #

Crea o amplía config/locales/en.yml:

yaml
en:
  home:
    index:
      welcome: "Welcome, %{name}!"
      cta: "Create an account"
  notifications:
    unread:
      one: "One unread notification"
      other: "%{count} unread notifications"

En app/views/home/index.html.erb, el saludo puede usar una búsqueda relativa a la vista:

erb
<h1><%= t(".welcome", name: @user_name) %></h1>
<p><%= t("notifications.unread", count: @unread_count) %></p>

La ruta de la vista determina la clave completa home.index.welcome para .welcome. El código que hace la llamada proporciona name y count; la traducción debe conservar esos nombres de interpolación. Las claves de plural, como one y other, identifican las ramas y se mantienen sin cambios.

A medida que amplíes la cobertura, mueve las etiquetas de las vistas que aún estén escritas directamente en el código, los textos de correo y los errores de los modelos a los espacios de nombres de idioma correspondientes. Traducir un archivo solo afecta al código que carga sus mensajes.

Selecciona YAML con el idioma en la raíz #

Rails lee el idioma desde la raíz del YAML. Si cambias el nombre de en.yml a es.yml pero conservas en:, los mensajes siguen definidos en inglés. Usa el manejador yaml-root-key para traducir los valores y cambiar el nombre de la raíz al mismo tiempo.

Instala y vincula la CLI desde la raíz del proyecto:

sh
npm install --global @lingo.dev/cli
lingo login
lingo init --source en --targets es,fr --files 'config/locales/en.yml' --yes
lingo link

Conserva los ID de la organización y del motor de localización guardados en .lingo/config.json. Configura su arreglo files con las entradas de origen que usa tu proyecto:

json
[
  { "pattern": "config/locales/en.yml", "format": "yaml-root-key" },
  { "pattern": "config/locales/*.en.yml", "format": "yaml-root-key" }
]

La segunda entrada abarca archivos separados por área, como mailers.en.yml, sin seleccionar sus versiones traducidas. Elimínala si el proyecto no tiene archivos de ese tipo. Define el formato de manera explícita: el formato YAML genérico conserva todas las raíces, mientras que la detección de la CLI requiere una selección explícita para los archivos de origen YAML. YAML con el idioma en la raíz describe el requisito de un mapeo con una sola raíz y cómo se reconstruye el archivo.

Traduce e inspecciona los valores cargados #

Para los archivos de destino que falten, ejecuta:

sh
lingo push --backfill-missing --wait

Cuando termine la ejecución, abre config/locales/es.yml y confirma que la raíz sea es:. Comprueba que las claves anidadas y los nombres de interpolación coincidan con los del origen. Revisa los comentarios, las anclas y los alias después de la serialización. Una estructura de origen diferente puede requerir una ruta de destino explícita.

Carga el resultado en la consola de Rails o en las pruebas de la aplicación y selecciona el idioma de forma explícita:

ruby
I18n.with_locale(:es) do
  puts I18n.t("home.index.welcome", name: "Alex", raise: true)
  [0, 1, 2, 20].each do |count|
    puts I18n.t("notifications.unread", count: count, raise: true)
  end
end

Configura :en, :es y :fr como idiomas disponibles antes de esta comprobación. El ejemplo pone a prueba la búsqueda y la interpolación; revisa que la redacción exprese el saludo y el conteo de notificaciones previstos. Los idiomas de destino pueden requerir reglas y ramas de plural adicionales a las formas en inglés del origen. Ejecuta la misma comprobación para francés y para los espacios de nombres de correo y validación de la aplicación a medida que los agregues.

Haz que las solicitudes seleccionen el mismo idioma #

Declara los idiomas admitidos y un idioma predeterminado en la configuración de Rails. Encapsula el procesamiento de solicitudes en I18n.with_locale con un valor elegido entre los idiomas admitidos, para que el estado del idioma no se arrastre a otra solicitud.

Para URL como /es, configura tanto el ámbito de las rutas como el controlador que lee params[:locale]. Conserva el idioma en los enlaces generados. Si la aplicación también negocia Accept-Language, analiza las ponderaciones de calidad y las etiquetas regionales en lugar de tomar una subcadena de dos letras. La selección explícita del usuario debe tener prioridad cuando la aplicación la admita.

Define con cuidado cómo funcionará el mecanismo de respaldo. Puede mantener una página utilizable y, al mismo tiempo, ocultar que falta un mensaje en español, así que comprueba las entradas de destino requeridas sin depender de él. Cuando corresponda, usa la función auxiliar l de Rails para localizar fechas y horas, en lugar de traducir como texto una fecha ya formateada.

Abre una página en el idioma de destino tanto directamente como a través de la navegación. Confirma que Rails seleccione el espacio de nombres de destino, muestre los valores interpolados esperados y maneje textos más largos. lingo check no comprueba que el YAML de Rails esté completo; conserva las comprobaciones de carga y renderización en Rails, junto con la revisión lingüística, como parte del proceso de aceptación.

Mantén las traducciones al modificar el origen #

Mantén juntos los archivos de origen, los archivos de destino aceptados, la configuración y .lingo/lock.json. Después de cambiar un mensaje, ejecuta lingo push --wait para procesar los cambios incrementales habituales y compara el mensaje modificado con uno cercano que no haya cambiado. Para hacer una corrección puntual a una redacción sin cambios, edita directamente el destino: el ámbito de clave YAML puede reutilizar la traducción existente. Para regenerar las traducciones después de cambiar las indicaciones, guarda los archivos de destino aceptados antes de reemplazar archivos completos dentro del ámbito definido, como se describe en ámbitos de traducción.

Si las correcciones locales del destino necesitan protección frente a divergencias, envía sin --wait, revisa lingo pull --dry-run y recupera el resultado en el checkout desde el que hiciste el envío. La escritura de resultados en modo de espera no incluye esa nueva comprobación de conflictos. Otros checkouts reciben las traducciones confirmadas mediante el control de versiones. Consulta Conservar las traducciones revisadas.

Cuando el ciclo local funcione, elige la GitHub App o la automatización de CI. Ejecuta las mismas comprobaciones de Rails sobre los recursos generados antes de integrar los cambios de traducción.