Localiser une application Rails
Traduisez les fichiers YAML Rails à racine de langue et vérifiez la recherche des messages, l’interpolation, les formes de pluriel et la sélection de la langue des requêtes.
Rails donne déjà des noms stables aux messages grâce à t et I18n.t. Lingo.dev peut traduire le YAML associé à ces noms, tandis que Rails continue de gérer la recherche des messages, l’interpolation et la sélection de la langue. Commencez par un message de salutation et un nombre de notifications, puis vérifiez-les avec les mêmes fonctions utilitaires que l’application.
Placer les messages sources dans un fichier de langue Rails #
Créez ou complétez config/locales/en.yml :
en:
home:
index:
welcome: "Welcome, %{name}!"
cta: "Create an account"
notifications:
unread:
one: "One unread notification"
other: "%{count} unread notifications"Dans app/views/home/index.html.erb, le message de salutation peut utiliser une recherche relative à la vue :
<h1><%= t(".welcome", name: @user_name) %></h1>
<p><%= t("notifications.unread", count: @unread_count) %></p>Le chemin de la vue attribue à .welcome la clé complète home.index.welcome. Le code appelant fournit name et count ; la traduction doit conserver ces noms d’interpolation. Les clés de pluriel comme one et other identifient les branches et restent inchangées.
À mesure que vous étendez la couverture, déplacez les libellés de vues encore codés en dur, les textes des e-mails et les erreurs des modèles dans les espaces de noms de langue appropriés. Traduire un fichier n’a d’effet que sur le code qui charge ses messages.
Sélectionner le format YAML à racine de langue #
Rails lit la langue à la racine du YAML. Si vous renommez en.yml en es.yml tout en conservant en:, les messages restent définis en anglais. Utilisez le gestionnaire yaml-root-key pour traduire les valeurs et renommer la racine en une seule opération.
Installez et associez la CLI depuis la racine du projet :
npm install --global @lingo.dev/cli
lingo login
lingo init --source en --targets es,fr --files 'config/locales/en.yml' --yes
lingo linkConservez les identifiants de l’organisation et du moteur de localisation enregistrés dans .lingo/config.json. Renseignez son tableau files avec les entrées sources utilisées par votre projet :
[
{ "pattern": "config/locales/en.yml", "format": "yaml-root-key" },
{ "pattern": "config/locales/*.en.yml", "format": "yaml-root-key" }
]La deuxième entrée couvre les fichiers organisés par fonctionnalité, comme mailers.en.yml, sans sélectionner leurs équivalents traduits. Supprimez-la si le projet ne contient aucun fichier de ce type. Définissez explicitement le format : le YAML générique conserve toutes les racines, tandis que la détection par la CLI exige un choix explicite pour les sources YAML. YAML à racine de langue décrit l’exigence d’une structure de correspondance à racine unique et le fonctionnement de la reconstruction.
Traduire et inspecter les valeurs chargées #
Pour créer les fichiers cibles manquants, exécutez :
lingo push --backfill-missing --waitUne fois l’exécution terminée, ouvrez config/locales/es.yml et vérifiez que la racine est bien es:. Assurez-vous que les clés imbriquées et les noms d’interpolation correspondent à la source. Inspectez les éventuels commentaires, ancres et alias après la sérialisation. Une autre organisation des sources peut nécessiter un chemin cible explicite.
Chargez le résultat dans la console Rails ou dans les tests de l’application en sélectionnant explicitement la langue :
I18n.with_locale(:es) do
puts I18n.t("home.index.welcome", name: "Alex", raise: true)
[0, 1, 2, 20].each do |count|
puts I18n.t("notifications.unread", count: count, raise: true)
end
endConfigurez :en, :es et :fr comme langues disponibles avant cette vérification. L’exemple teste la recherche des messages et l’interpolation ; vérifiez que le texte exprime bien la salutation et le nombre de notifications attendus. Les langues cibles peuvent nécessiter des règles et des branches de pluriel allant au-delà des formes anglaises de la source. Effectuez la même vérification pour le français, ainsi que pour les espaces de noms d’envoi d’e-mails et de validation de l’application à mesure que vous les ajoutez.
Sélectionner la même langue pour les requêtes #
Déclarez les langues prises en charge et une langue par défaut dans la configuration Rails. Encadrez le traitement des requêtes avec I18n.with_locale en utilisant une valeur choisie parmi les langues prises en charge, afin que l’état de la langue ne se propage pas d’une requête à l’autre.
Pour les URL comme /es, configurez la portée des routes ainsi que le contrôleur qui lit params[:locale]. Conservez la langue dans les liens générés. Si l’application négocie aussi Accept-Language, analysez les coefficients de qualité et les codes régionaux plutôt que d’extraire une sous-chaîne de deux lettres. Le choix explicite de l’utilisateur doit être prioritaire lorsque l’application le permet.
Choisissez avec soin le comportement de repli. Le repli peut garder une page utilisable tout en masquant l’absence d’un message en espagnol ; vérifiez donc les entrées cibles requises sans vous appuyer sur ce mécanisme. Utilisez la fonction utilitaire l de Rails pour localiser les dates et les heures lorsque cela convient, plutôt que de traduire une date préformatée comme du texte.
Ouvrez une page dans la langue cible directement, puis via la navigation. Vérifiez que Rails sélectionne l’espace de noms cible, affiche les valeurs interpolées attendues et gère les textes plus longs. lingo check ne vérifie pas l’exhaustivité du YAML Rails ; gardez les contrôles de chargement et de rendu dans Rails, ainsi que la relecture linguistique, dans le processus d’acceptation.
Maintenir les traductions au fil des modifications de la source #
Conservez ensemble les fichiers sources, les traductions cibles acceptées, la configuration et .lingo/lock.json. Après avoir modifié un message, exécutez lingo push --wait pour traiter les changements courants, puis comparez le message modifié à un message voisin inchangé. Pour corriger précisément une formulation dont la source n’a pas changé, modifiez directement la cible : une opération limitée à une clé YAML peut réutiliser sa traduction existante. Pour régénérer les traductions après une modification des consignes, sauvegardez les traductions cibles acceptées avant de remplacer intégralement les fichiers du périmètre choisi, comme indiqué dans portées de traduction.
Si les corrections locales des cibles doivent être protégées contre les divergences, soumettez sans --wait, inspectez lingo pull --dry-run, puis récupérez le résultat dans le checkout ayant servi à la soumission. L’écriture en retour en mode attente ne bénéficie pas de cette nouvelle vérification des conflits. Les autres checkouts reçoivent les traductions committées via le système de gestion de versions. Consultez Préserver les traductions relues.
Une fois le cycle local opérationnel, choisissez la GitHub App ou l’automatisation CI. Effectuez les mêmes vérifications Rails sur les ressources générées avant de fusionner les modifications de traduction.