Guida all’internazionalizzazione (i18n) e alla localizzazione di Rails

Configurazione dell’internazionalizzazione di Rails (i18n)

L’internazionalizzazione di Rails richiede tre passaggi di configurazione: impostare i locale disponibili, aggiungere il locale ai tuoi URL e fare in modo che Rails carichi il locale corretto per ogni richiesta. Ti consigliamo inoltre di installare la gem rails-i18n, che fornisce dati sui locale come i nomi dei mesi tradotti, le regole di pluralizzazione e i messaggi di errore predefiniti di Rails.

Imposta i locale disponibili

Per prima cosa, in config/application.rb, indica a Rails quali lingue deve supportare l’app e imposta un locale predefinito:

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

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

Questo indica a Rails che l’inglese è la lingua predefinita e che l’app supporta inglese, spagnolo e tedesco. Puoi aggiungere tutti i codici lingua di cui hai bisogno.

Aggiungere il locale agli URL

Successivamente, aggiungi il locale all’URL in modo che ogni lingua abbia il proprio percorso, come /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

Configurare il cambio di lingua

Infine, in app/controllers/application_controller.rb, assicurati che Rails carichi il locale corretto dall’URL e lo includa in tutti i link:

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

Questo legge il locale dal parametro URL, torna al locale predefinito se non ne è presente nessuno e garantisce che tutti gli URL generati includano il locale corrente.

Installare la gem rails-i18n

La gem rails-i18n fornisce dati sui locale per più lingue, inclusi i nomi dei mesi tradotti, le regole di pluralizzazione e i messaggi di errore predefiniti di Rails. Questo ti evita di dover tradurre tu stesso queste stringhe standard.

Aggiungila al tuo Gemfile:

gem 'rails-i18n'

Quindi esegui:

bundle install

Rails è ora completamente configurato per l’internazionalizzazione.

Aggiungere un selettore di lingua

Ora che la tua app Rails supporta più locale, i tuoi utenti hanno bisogno di un modo per passare da una lingua all’altra. Poiché il metodo default_url_options in ApplicationController include automaticamente il locale corrente in tutti gli URL generati, puoi creare un selettore che aggiorna solo il parametro locale mantenendo l’utente sulla stessa pagina.

Creare l’interfaccia utente del selettore di lingua

Aggiungi il selettore di lingua al tuo file di layout. Nella nostra app demo, va in 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>

Ogni link utilizza url_for(locale: :locale_code) per generare un URL con il locale specificato. Quando un utente clicca su un link, il metodo switch_locale in ApplicationController rileva il cambiamento e Rails visualizza la pagina nella nuova lingua.

Poiché default_url_options è definito, il locale persiste mentre gli utenti navigano. Non è necessario aggiungere manualmente i parametri locale a ogni link.

Personalizzare lo stile del selettore di lingua

Puoi personalizzare lo stile del selettore di lingua in app/assets/stylesheets/application.css per adattarlo al tuo design. L’app demo include uno stile di base per rendere il selettore visibile e facile da usare.

Impostare le chiavi di traduzione nelle viste di Rails

Prima di poter tradurre la tua app, tutto il testo rivolto all’utente deve risiedere nei file i18n di Rails invece di essere codificato direttamente (hard-coded). Rails fornisce il metodo helper t (abbreviazione di translate) per cercare e visualizzare le stringhe tradotte.

Sostituire il testo codificato con chiavi di traduzione

Il testo codificato direttamente non apparirà nel tuo file YAML, il che significa che non potrà essere tradotto in seguito. Usa sempre le chiavi di traduzione per qualsiasi testo rivolto all’utente.

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

Usare l’interpolazione nelle traduzioni

Hai notato il parametro time: @time nell’esempio sopra? Si chiama interpolazione — ti permette di inserire valori dinamici nelle tue traduzioni. La stringa di traduzione nel tuo file YAML utilizza %{time} come placeholder:

current_time: "Current time: %{time}"

current_time: "Current time: %{time}"

Quando chiami l’helper t con time: @time, Rails sostituisce %{time} con il valore effettivo. Puoi usare qualsiasi nome di variabile desideri, assicurati solo che corrispondano tra il file YAML e la tua vista.

Lazy Lookup per un codice più pulito

Quando le tue chiavi di traduzione sono organizzate per corrispondere alla struttura delle cartelle delle tue viste, Rails ti permette di usare una scorciatoia chiamata lazy lookup. Invece di scrivere l’intero percorso della chiave, usa un punto iniziale:

<!-- 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 controlla in quale file di vista ti trovi (home/index.html.erb) e aggiunge automaticamente home.index. davanti alla tua chiave. Questo mantiene il tuo codice più pulito e rende più facile spostare le viste. Se rinomini o sposti una vista, i percorsi di lazy lookup si aggiornano automaticamente.

Creare e organizzare i file di traduzione

Ora che hai aggiunto le chiavi di traduzione alle tue viste, devi definire quelle chiavi in un file YAML. Rails le memorizza nella directory config/locales/.

Aggiungi le chiavi al file della lingua di origine

Apri config/locales/en.yml e aggiungi le chiavi a cui hai fatto riferimento nelle tue viste:

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

Questo è il tuo file di origine — contiene tutto il testo nella tua lingua predefinita. Le chiavi a sinistra sono quelle a cui fanno riferimento le tue viste; le stringhe a destra sono quelle che vengono visualizzate.

Organizzare le chiavi con l’annidamento

Per usare il lazy lookup (la scorciatoia .hello della sezione precedente), organizza le tue chiavi in modo che corrispondano alla struttura delle cartelle delle tue viste:

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

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

Questo raggruppa tutte le traduzioni per app/views/home/index.html.erb sotto home.index. Ora puoi usare t('.hello') in quella vista invece di t('home.index.hello').

Man mano che la tua applicazione Rails cresce, puoi anche creare namespace per le traduzioni condivise (come shared.navigation per i menu) per mantenere le cose organizzate, ma questo è opzionale.

Aggiungere stringhe JavaScript allo YAML

Rails non estrae automaticamente il testo dai file JavaScript. Se la tua app ha testo lato client come avvisi, tooltip o messaggi di conferma, aggiungili al tuo file di traduzione inglese:

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

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

A questo punto, il tuo file en.yml contiene tutto il testo che appare nella tua app, sia nelle viste Rails che in JavaScript.

Quando utilizzi PTC per tradurre la tua applicazione (trattato nella sezione successiva), queste stringhe JavaScript verranno tradotte insieme a tutto il resto.