Guide d’internationalisation (i18n) et de localisation Rails

Configuration de l’internationalisation Rails (i18n)

L’internationalisation Rails nécessite trois étapes de configuration : définir les paramètres régionaux disponibles, ajouter les paramètres régionaux à vos URL et faire en sorte que Rails charge les bons paramètres régionaux pour chaque requête. Vous voudrez également installer la gem rails-i18n, qui fournit des données de paramètres régionaux telles que les noms de mois traduits, les règles de pluralisation et les messages d’erreur Rails par défaut.

Définir les paramètres régionaux disponibles

Tout d’abord, dans config/application.rb, indiquez à Rails quelles langues l’application doit prendre en charge et définissez des paramètres régionaux par défaut :

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

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

Cela indique à Rails que l’anglais est la langue par défaut et que l’application prend en charge l’anglais, l’espagnol et l’allemand. Vous pouvez ajouter tous les codes de langue dont vous avez besoin.

Ajouter les paramètres régionaux aux URL

Ensuite, ajoutez les paramètres régionaux à l’URL afin que chaque langue ait son propre chemin, comme /en/time ou /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

Configurer le changement de paramètres régionaux

Enfin, dans app/controllers/application_controller.rb, assurez-vous que Rails charge les bons paramètres régionaux à partir de l’URL et les inclut dans tous les liens :

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

Cela lit les paramètres régionaux à partir du paramètre d’URL, revient aux paramètres régionaux par défaut si aucun n’est présent, et garantit que toutes les URL générées incluent les paramètres régionaux actuels.

Installer la gem rails-i18n

La gem rails-i18n fournit des données de paramètres régionaux pour plusieurs langues, notamment les noms de mois traduits, les règles de pluralisation et les messages d’erreur Rails par défaut. Cela vous évite de traduire vous-même ces chaînes standard.

Ajoutez-la à votre Gemfile :

gem 'rails-i18n'

Ensuite, exécutez :

bundle install

Rails est maintenant entièrement configuré pour l’internationalisation.

Ajouter un sélecteur de langue

Maintenant que votre application Rails prend en charge plusieurs paramètres régionaux, vos utilisateurs ont besoin d’un moyen de changer de langue. Étant donné que la méthode default_url_options dans ApplicationController inclut automatiquement les paramètres régionaux actuels dans toutes les URL générées, vous pouvez créer un sélecteur de langue qui ne met à jour que le paramètre de paramètres régionaux tout en gardant l’utilisateur sur la même page.

Créer l’interface du sélecteur de langue

Ajoutez le sélecteur de langue à votre fichier de mise en page. Dans notre application de démonstration, il se trouve dans 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>

Chaque lien utilise url_for(locale: :locale_code) pour générer une URL avec les paramètres régionaux spécifiés. Lorsqu’un utilisateur clique sur un lien, la méthode switch_locale dans ApplicationController détecte le changement et Rails affiche la page dans la nouvelle langue.

Étant donné que default_url_options est défini, les paramètres régionaux persistent lorsque les utilisateurs naviguent. Vous n’avez pas besoin d’ajouter manuellement des paramètres de paramètres régionaux à chaque lien.

Styliser votre sélecteur de langue

Vous pouvez styliser le sélecteur de langue dans app/assets/stylesheets/application.css pour qu’il corresponde à votre design. L’application de démonstration inclut un style de base pour rendre le sélecteur visible et convivial.

Configuration des clés de traduction dans les vues Rails

Avant de pouvoir traduire votre application, tout le texte visible par l’utilisateur doit se trouver dans les fichiers i18n Rails au lieu d’être codé en dur. Rails fournit la méthode d’aide t (abréviation de translate) pour rechercher et afficher les chaînes traduites.

Remplacer le texte codé en dur par des clés de traduction

Le texte codé en dur n’apparaîtra pas dans votre fichier YAML, ce qui signifie qu’il ne pourra pas être traduit ultérieurement. Utilisez toujours des clés de traduction pour tout texte visible par l’utilisateur.

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

Utiliser l’interpolation dans les traductions

Remarquez le paramètre time: @time dans l’exemple ci-dessus ? C’est ce qu’on appelle l’interpolation — elle vous permet d’insérer des valeurs dynamiques dans vos traductions. La chaîne de traduction dans votre fichier YAML utilise %{time} comme placeholder :

current_time: "Current time: %{time}"

current_time: "Current time: %{time}"

Lorsque vous appelez l’aide t avec time: @time, Rails remplace %{time} par la valeur réelle. Vous pouvez utiliser les noms de variables que vous souhaitez — assurez-vous simplement qu’ils correspondent entre le fichier YAML et votre vue.

Recherche paresseuse pour un code plus propre

Lorsque vos clés de traduction sont organisées pour correspondre à la structure de votre dossier de vues, Rails vous permet d’utiliser un raccourci appelé recherche paresseuse. Au lieu d’écrire le chemin complet de la clé, utilisez un point initial :

<!-- 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 examine dans quel fichier de vue vous vous trouvez (home/index.html.erb) et ajoute automatiquement home.index. devant votre clé. Cela rend votre code plus propre et facilite le déplacement des vues. Si vous renommez ou déplacez une vue, les chemins de recherche paresseuse se mettent à jour automatiquement.

Créer et organiser les fichiers de traduction

Maintenant que vous avez ajouté des clés de traduction à vos vues, vous devez définir ces clés dans un fichier YAML. Rails les stocke dans le répertoire config/locales/.

Ajouter des clés à votre fichier de langue source

Ouvrez config/locales/en.yml et ajoutez les clés auxquelles vous avez fait référence dans vos vues :

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

Ceci est votre fichier source — il contient tout le texte dans votre langue par défaut. Les clés à gauche sont celles auxquelles vos vues font référence ; les chaînes à droite sont ce qui est affiché.

Organiser les clés avec l’imbrication

Pour utiliser la recherche paresseuse (le raccourci .hello de la section précédente), organisez vos clés pour qu’elles correspondent à la structure de votre dossier de vues :

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

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

Cela regroupe toutes les traductions pour app/views/home/index.html.erb sous home.index. Vous pouvez maintenant utiliser t('.hello') dans cette vue au lieu de t('home.index.hello').

Au fur et à mesure que votre application Rails se développe, vous pouvez également créer des espaces de noms pour les traductions partagées (comme shared.navigation pour les menus) afin de garder les choses organisées, mais cela est facultatif.

Ajouter des chaînes JavaScript au YAML

Rails n’extrait pas automatiquement le texte des fichiers JavaScript. Si votre application contient du texte côté client comme des alertes, des info-bulles ou des messages de confirmation, ajoutez-les à votre fichier de traduction anglais :

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

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

À ce stade, votre fichier en.yml contient tout le texte qui apparaît dans votre application – à la fois dans les vues Rails et dans JavaScript.

Lorsque vous utilisez PTC pour traduire votre application (abordé dans la section suivante), ces chaînes JavaScript seront traduites en même temps que tout le reste.