Localisation Ruby on Rails avec l’API i18n

La CLI Lingo.dev traduit les fichiers YAML Rails config/locales via un moteur de localisation configuré. Rails intègre l’API i18n en natif : tout le texte traduisible de votre application vit dans des fichiers YAML par langue. Lingo.dev s’intègre à votre pipeline existant sans ajouter de dépendance à l’exécution.

Ce guide vous accompagne pas à pas dans la localisation complète d’une application Rails : configuration de la CLI, organisation des fichiers YAML par langue, changement de langue à la requête et automatisation des traductions avec GitHub Actions.

Comment fonctionne la localisation dans Rails#

Rails lit les traductions à partir des fichiers YAML situés dans config/locales/. Chaque fichier utilise un code de langue comme clé racine et contient des clés imbriquées qui reflètent les chemins de recherche utilisés par votre code avec I18n.t.

Dans chaque fichier YAML Rails, la première clé correspond au code de langue lui-même : en:, es:, fr:. Le bucket yaml-root-key de la CLI comprend cette structure : il retire le préfixe de langue avant d’envoyer le contenu à votre moteur de localisation, puis génère un fichier parallèle avec le code de langue cible comme nouvelle clé racine. Les clés imbriquées, les jetons d’interpolation %{name} et les catégories plurielles CLDR (zero/one/two/few/many/other) sont préservés.

Prérequis#

ruby -v
rails -v

node -v

<h1>Welcome</h1>

<h1><%= t(".welcome") %></h1>

Organiser les fichiers de traduction#

Rails charge automatiquement chaque fichier *.yml situé sous config/locales/. Gardez la langue source à côté de ses versions traduites afin que le répertoire fasse office de source unique de vérité :

config/locales/
  en.yml          # Source locale
  es.yml          # Generated by Lingo.dev
  fr.yml
  de.yml

Un fichier en.yml typique combine des chaînes simples, des espaces de noms imbriqués, l’interpolation %{name} et la pluralisation :

en:
  hello: "Hello"
  home:
    welcome: "Welcome, %{name}!"
    cta: "Get started"
  notifications:
    unread:
      zero: "No unread notifications"
      one: "1 unread notification"
      other: "%{count} unread notifications"
  errors:
    messages:
      blank: "can't be blank"

Configurer la CLI#

Créez un fichier i18n.json à la racine de votre projet. Déclarez un bucket yaml-root-key qui pointe vers les fichiers de langue :

{
  "$schema": "https://lingo.dev/schema/i18n.json",
  "version": "1.15",
  "locale": {
    "source": "en",
    "targets": ["es", "fr", "de"]
  },
  "buckets": {
    "yaml-root-key": {
      "include": ["config/locales/[locale].yml"]
    }
  }
}

L’espace réservé [locale] se résout en chaque code de langue configuré. Avec source: "en", la CLI lit config/locales/en.yml et écrit les fichiers traduits dans config/locales/es.yml, config/locales/fr.yml et config/locales/de.yml.

Rails charge sans problème mailers.en.yml, pages.en.yml et ainsi de suite, en parallèle de en.yml. Ajoutez des motifs supplémentaires au tableau include de votre bucket yaml-root-key :

{
  "buckets": {
    "yaml-root-key": {
      "include": [
        "config/locales/[locale].yml",
        "config/locales/mailers.[locale].yml",
        "config/locales/pages.[locale].yml"
      ]
    }
  }
}

Configurer Rails pour plusieurs langues#

Indiquez à Rails quelles langues sont disponibles et laquelle utiliser par défaut. Dans config/application.rb :

module YourApp
  class Application < Rails::Application
    config.i18n.available_locales = [:en, :es, :fr, :de]
    config.i18n.default_locale = :en
    config.i18n.fallbacks = [:en]
  end
end

Définissez la langue de la requête dans ApplicationController à partir d’un paramètre d’URL ou de l’en-tête Accept-Language :

class ApplicationController < ActionController::Base
  around_action :switch_locale

  private

  def switch_locale(&action)
    locale = params[:locale] || http_accept_locale || I18n.default_locale
    I18n.with_locale(locale, &action)
  end

  def http_accept_locale
    header = request.headers["Accept-Language"].to_s
    header.scan(/[a-z]{2}/).find { |l| I18n.available_locales.map(&:to_s).include?(l) }
  end

  def default_url_options
    { locale: I18n.locale }
  end
end

Afficher les traductions dans les vues#

Utilisez les helpers t et l dans vos templates ERB. Un point en début de clé la résout par rapport au chemin de la vue courante, ce qui permet de garder les clés de traduction au plus près des templates qui les utilisent :

<h1><%= t(".welcome", name: @user_name) %></h1>
<p><%= t("notifications.unread", count: @unread_count) %></p>
<%= link_to t(".cta"), signup_path, class: "btn-primary" %>

Ajoutez un sélecteur de langue à votre layout :

<nav>
  <% I18n.available_locales.each do |locale| %>
    <%= link_to locale.upcase, url_for(locale: locale) %>
  <% end %>
</nav>

Traduire en local#

Définissez votre clé API, puis lancez la CLI :

export LINGO_API_KEY="your-api-key"
npx lingo.dev@latest run

La CLI lit chaque fichier correspondant aux motifs de votre bucket, repère les entrées non traduites à l’aide du lockfile, traduit uniquement le delta via votre moteur de localisation, puis écrit le résultat dans chaque fichier de langue cible. La clé racine de langue, les espaces de noms imbriqués, les jetons d’interpolation au format %{name} et les catégories plurielles sont préservés : seul le texte traduisible est modifié.

Pour cibler une langue spécifique pendant le développement :

npx lingo.dev@latest run --target-locale es

Redémarrez le serveur Rails après la première exécution de traduction pour que les nouveaux fichiers YAML soient bien chargés :

bin/rails server

Rendez-vous sur /es pour voir le rendu en espagnol.

Pluriels#

Rails s’appuie sur les catégories plurielles CLDR : zero, one, two, few, many, other. Passez un argument count: à I18n.t et Rails sélectionnera la clé correspondante :

t("notifications.unread", count: 0)   # => "No unread notifications"
t("notifications.unread", count: 1)   # => "1 unread notification"
t("notifications.unread", count: 12)  # => "12 unread notifications"

La CLI traduit chaque variante de pluriel sur place. Si votre langue cible nécessite plus de catégories que le one/other de l’anglais, définissez-les dans votre fichier source en.yml.

Automatiser avec GitHub Actions#

Ajoutez un fichier de workflow à l’emplacement .github/workflows/translate.yml pour traduire à chaque push :

name: Translate
on:
  push:
    branches: [main]
permissions:
  contents: write
jobs:
  translate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Lingo.dev
        uses: lingodotdev/lingo.dev@main
        with:
          api-key: ${{ secrets.LINGODOTDEV_API_KEY }}

Enregistrez votre clé API sous le nom LINGODOTDEV_API_KEY dans Settings > Secrets and variables > Actions de votre dépôt GitHub.

Vérifier avant le déploiement#

Utilisez l’option --frozen comme garde-fou de déploiement pour vous assurer qu’aucun contenu non traduit ne parte en production. La CLI se termine avec un code de sortie non nul si des entrées doivent encore être traduites :

npx lingo.dev@latest run --frozen

Ajoutez cette étape CI séparément avant la précompilation de vos assets ou la construction de votre conteneur :

- name: Verify translations
  run: npx lingo.dev@latest run --frozen
- name: Precompile assets
  run: bundle exec rails assets:precompile

Étapes suivantes#