Skip to main content

Rails i18n : le guide complet de l'internationalisation Ruby on Rails

Du premier fichier de locale à la mise en production : configurez Rails I18n, utilisez le helper t(), gérez le pluriel CLDR, corrigez les pièges courants et ajoutez des chaînes de repli de locales intelligentes.

1

Comprendre l'architecture de Rails I18n

Rails intègre nativement la gem I18n. Les fichiers de traduction se trouvent dans config/locales/, au format YAML (par défaut) ou Ruby. Le framework fournit le helper t() (alias de I18n.translate) dans les vues, les contrôleurs, les modèles et les mailers. Rails I18n est simple par conception : il gère nativement la traduction de base, l'interpolation et le pluriel.

config/application.rb
# Rails includes i18n out of the box via the i18n gem
# config/application.rb
module MyApp
  class Application < Rails::Application
    # Default locale
    config.i18n.default_locale = :en

    # Available locales
    config.i18n.available_locales = [:en, :de, :ja, :es, :fr, :'pt-BR']

    # Fallback to default locale when translation is missing
    config.i18n.fallbacks = true

    # Load translations from nested directories
    config.i18n.load_path += Dir[Rails.root.join('config', 'locales', '**', '*.{rb,yml}')]
  end
end
config/routes.rb
# config/routes.rb
Rails.application.routes.draw do
  scope "/:locale", locale: /en|de|ja|es|fr|pt-BR/ do
    root "home#index"
    resources :products
  end

  root "home#index"
end

# app/controllers/application_controller.rb
class ApplicationController < ActionController::Base
  around_action :switch_locale

  private

  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
Rails charge automatiquement tous les fichiers .yml et .rb de config/locales/. Vous pouvez les organiser comme vous le souhaitez : par langue (en.yml, de.yml), par fonctionnalité (en/users.yml, en/orders.yml), ou les deux (en/users.yml, de/users.yml). Rails fusionne tous les fichiers au démarrage.
2

Configurer les paramètres de locale

Définissez default_locale, available_locales et le comportement de repli dans config/application.rb ou dans un initializer. Configurez la détection de la locale dans votre ApplicationController à l'aide d'un before_action, pour définir la locale à partir de l'URL, de la session, du cookie ou de l'en-tête Accept-Language.

config/locales/en.yml
# config/locales/en.yml
en:
  nav:
    home: "Home"
    about: "About"
    settings: "Settings"
  greeting: "Hello, %{name}!"
  cart:
    item_count:
      one: "%{count} item"
      other: "%{count} items"

# config/locales/de.yml
de:
  nav:
    home: "Startseite"
    about: "Über uns"
    settings: "Einstellungen"
  greeting: "Hallo, %{name}!"
  cart:
    item_count:
      one: "%{count} Artikel"
      other: "%{count} Artikel"
Définir I18n.locale dans un before_action est sûr par requête, mais définir I18n.default_locale à l'exécution est global et affecte tous les threads. Utilisez toujours I18n.locale (local au thread) pour les changements de locale limités à la requête, jamais I18n.default_locale.
3

Utiliser le helper t()

Le helper t() est disponible partout dans Rails : vues, contrôleurs, modèles, mailers et jobs. Il accepte une clé, des variables d'interpolation facultatives et des options comme des valeurs par défaut et une portée (scope). Dans les vues, Rails prend en charge les recherches paresseuses (lazy lookups), qui limitent automatiquement les clés au contrôleur et à l'action en cours.

app/views/example.html.erb
# In views (ERB)
<h1><%= t('nav.home') %></h1>
<p><%= t('greeting', name: @user.name) %></p>

# In controllers
flash[:notice] = t('flash.product_created')

# In models
validates :name, presence: { message: I18n.t('errors.blank') }

# With HTML (safe)
<%= t('terms_html', link: link_to(t('terms_link'), '/terms')) %>
4

Gérer la pluralisation

Rails I18n utilise les catégories de pluriel CLDR : zero, one, two, few, many, other. L'anglais n'a besoin que de one et other, mais d'autres langues nécessitent davantage de formes. Définissez les traductions au pluriel sous forme de clés YAML imbriquées, selon les catégories de nombre requises par vos langues cibles.

Plural forms
# In YAML:
en:
  cart:
    item_count:
      zero: "No items"
      one: "%{count} item"
      other: "%{count} items"

# Arabic (6 forms):
ar:
  cart:
    item_count:
      zero: "لا عناصر"
      one: "عنصر واحد"
      two: "عنصران"
      few: "%{count} عناصر"
      many: "%{count} عنصرًا"
      other: "%{count} عنصر"

# Usage in views:
<%= t('cart.item_count', count: @cart.items.size) %>
Rails lève une exception I18n::InvalidPluralizationData si une catégorie de pluriel requise est absente pour la locale active. Si votre locale russe ne définit que one et other (copiées depuis l'anglais), des nombres comme 2, 3 ou 4 provoqueront un plantage, car le russe nécessite une catégorie few. Définissez toujours toutes les catégories CLDR pour chaque langue.
5

Ajouter des chaînes de repli de locale

Le mécanisme intégré I18n.fallbacks de Rails ne fournit qu'un repli basique de la locale régionale vers la locale par défaut. Un utilisateur pt-BR confronté à une clé manquante voit l'anglais au lieu du pt-PT. rails-locale-chain ajoute des chaînes de fusion profonde configurables, afin que les utilisateurs régionaux voient toujours la traduction disponible la plus proche.

Lazy lookups
# Lazy lookups use the controller/action as scope
# app/views/products/index.html.erb
# Instead of t('products.index.title'), just use:
<h1><%= t('.title') %></h1>
<p><%= t('.description') %></p>

# Rails looks up: products.index.title and products.index.description

# config/locales/en.yml
en:
  products:
    index:
      title: "All Products"
      description: "Browse our catalog"
rails-locale-chain est fourni avec plus de 75 chaînes de repli intégrées, couvrant 11 familles de langues. Ajoutez-la à votre Gemfile, configurez-la dans un initializer, et les utilisateurs régionaux voient immédiatement les traductions de la locale parente au lieu des lacunes comblées par l'anglais.
6

Automatiser les traductions

Une fois votre configuration Rails I18n terminée, traduisez vos fichiers de locale YAML à l'aide de l'IA. i18n Agent prend en charge le YAML nativement : indiquez-lui votre fichier de locale source, et il génère toutes les langues cibles en préservant les clés imbriquées, les variables d'interpolation et les formes de pluriel.

config/initializers/locale_chain.rb
# Gemfile
gem 'rails-locale-chain'

# config/initializers/locale_chain.rb
Rails.application.config.i18n.fallbacks = {
  'pt-BR': ['pt', 'en'],
  'zh-Hant-TW': ['zh-Hant', 'zh', 'en'],
  'es-419': ['es', 'en'],
}

# The gem deep-merges translations across the chain
# pt-BR -> pt -> en
# Missing keys in pt-BR are filled from pt, then en
Traduisez de façon incrémentale : lorsque vous ajoutez de nouvelles clés, ne traduisez que le diff. Cela préserve les traductions existantes et évite de régénérer les chaînes inchangées.

Pièges courants

Erreurs InvalidPluralizationData

Rails plante avec I18n::InvalidPluralizationData lorsqu'une catégorie de pluriel CLDR requise est absente. Cela se produit le plus souvent lorsque les formes de pluriel anglaises (one/other) sont copiées vers des langues qui nécessitent davantage de catégories (le russe a besoin de few, l'arabe a besoin de zero/two/few/many). Installez rails-i18n pour obtenir des règles CLDR correctes et définissez toutes les catégories.

Recherches paresseuses en dehors des vues

Les recherches paresseuses (t('.key')) ne fonctionnent que dans les vues, où Rails connaît le contrôleur et l'action. Utiliser t('.key') dans un modèle, un mailer ou un service object renvoie une erreur de traduction manquante. Utilisez des clés complètes (t('users.show.key')) en dehors des vues.

Les erreurs de syntaxe YAML cassent toutes les traductions

Une seule erreur de syntaxe YAML (mauvaise indentation, caractères spéciaux non mis entre guillemets, tabulation au lieu d'espaces) empêche le chargement de tout le fichier de locale. Toutes les traductions de ce fichier renvoient alors des erreurs de clé manquante. Validez les fichiers YAML en CI à l'aide d'un linter, et mettez entre guillemets les chaînes contenant des deux-points, des crochets ou des caractères spéciaux en début de chaîne.

Essayez i18n Agent maintenant

Déposez votre fichier de traduction ici

JSON, YAML, PO, XML, CSV, Markdown, Properties

ou cliquez pour parcourir

Langues cibles

Aucune inscription requiseEstimation instantanée

FAQ Rails i18n