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]

Questa configurazione indica a Rails che:

• L’inglese (:en) è la lingua predefinita
• L’app supporta inglese, spagnolo e tedesco
• Gli utenti possono passare da una di queste tre lingue all’altra

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

Questo crea URL specifici per il locale per la tua applicazione Rails. Gli utenti possono accedere a diverse versioni linguistiche modificando il parametro locale nell’URL.

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

• Legge il locale dal parametro dell’URL
• Ritorna al locale predefinito se non è presente alcun parametro
• Assicura 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 globali hanno bisogno di un modo per passare da una lingua all’altra. Rails rende tutto questo semplice perché il metodo default_url_options in ApplicationController include automaticamente il locale corrente in tutti gli URL generati.

Ciò significa che puoi creare un selettore di lingua 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, il selettore viene aggiunto 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 la modifica
• Rails renderizza la pagina nella nuova lingua

Poiché hai definito default_url_options in ApplicationController, Rails include automaticamente il locale in tutti i link generati. Ciò significa che il locale persiste mentre gli utenti navigano nella tua app. 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

Rails utilizza l’helper integrato I18n.t (o semplicemente t) per cercare le stringhe nei tuoi file di traduzione.

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

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.

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: "Ora corrente: %{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:

<!-- Invece di questo: -->
<%= t('home.index.hello') %>

<!-- Puoi scrivere questo: -->
<%= 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 memorizza queste definizioni nella directory config/locales/.

Aggiungere le chiavi al tuo file inglese

I file di traduzione di Rails utilizzano una semplice struttura chiave-valore. 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"

In questa struttura i18n di Rails:

• en è il codice della lingua (inglese)
• hello, current_time e refresh sono chiavi di traduzione
• Le stringhe a destra sono il testo effettivo
• %{time} è un placeholder per contenuti dinamici (interpolazione)

Questo è il tuo file sorgente. Contiene tutto il testo nella tua lingua predefinita. Più avanti in questo tutorial, userai PTC per generare automaticamente le versioni in spagnolo, tedesco e altre lingue.

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

Le tue viste Rails sono ora internazionalizzate, ma che dire di JavaScript? Rails non estrae automaticamente il testo dai file JavaScript. Se la tua applicazione ha testo lato client come avvisi, tooltip o messaggi di conferma, devi aggiungerli al tuo file di traduzione inglese.

Ad esempio, per tradurre un popup di conferma, aggiungi la stringa a config/locales/en.yml:

# config/locales/en.yml
en:
 confirm: "Sei sicuro?"

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