CyberTrainGuidesInternationalisation

Internationalisation

Des textes traduits à la manière de Rails : des dictionnaires dans config/locales/*.yml, t et l dans les templates, les contrôleurs et les modèles, une locale par requête, et des dictionnaires anglais et japonais fournis pour les messages de validation, les dates, les nombres et les écrans d’authentification.

Dictionnaires

Un dictionnaire est un fichier YAML sous config/locales/ (sous-répertoires compris) dont la première clé est une locale : en, ja, pt-BR. cybertrain new écrit config/locales/en.yml ; ajoutez un fichier par langue et listez les langues dans config/app.rb.

config/locales/ja.yml (extrait, examples/blog)yaml
ja:
  activerecord:
    models:
      article: "記事"
    attributes:
      article:
        title: "タイトル"
        body: "本文"
  articles:
    index:
      title: "記事"
      count:
        other: "%{number}件の記事"
config/app.rbruby
Cybertrain.configure do |c|
  c.i18n_available_locales = [:en, :ja]
end

spin run gen lit chaque *.yml sous config/locales/ et les compile dans gen/locales.rb : le programme porte ses textes et ne lit aucun YAML à l’exécution. Le serveur de développement le régénère quand un dictionnaire change, et spin run gen -- --check le signale comme périmé. Les fichiers sont lus dans l’ordre de leurs chemins, et une clé d’un fichier plus tardif remplace la même clé d’un fichier antérieur. Une clé qui est un mapping dans un fichier et un texte ou une liste dans un autre arrête gen, qui nomme les deux fichiers et leurs lignes.

Le YAML que lit gen

gen lit le YAML avec un lecteur à lui, qui accepte ce qu’utilisent les dictionnaires et refuse le reste en indiquant le fichier et la ligne :

  • Accepté : les mappings imbriqués ; les valeurs simples, entre 'apostrophes' ou entre "guillemets" sur une ligne (\n, \t, \", \\, \uXXXX) ; les blocs | et > ; les listes de valeurs, en éléments de bloc (y compris à l’indentation de leur clé, comme les écrit rails-i18n) ou en [a, b] ; les commentaires, un --- initial, un BOM et les fins de ligne CRLF ; ~, null ou rien pour un texte vide.
  • Chaque valeur est gardée comme texte : 3 est "3", no est "no", :year est ":year".
  • Refusé : les ancres et les alias, les tags, un second document, les mappings {a: b}, les clés entre guillemets, une clé en double, une tabulation dans l’indentation, un élément de liste qui n’est pas une valeur, une première clé qui n’est pas un nom de locale, et une valeur simple ou entre guillemets qui continue sur la ligne suivante (écrivez-la avec | ou >).

Chercher un texte

t dans un template, t dans un contrôleur et I18n.t partout ailleurs renvoient le texte d’une clé dans la locale courante :

ruby
I18n.t("greeting", name: "Ann")            # "Hello, %{name}" => "Hello, Ann"
I18n.t("nope", default: "Nothing")         # une String, ou un Symbol qui nomme une autre clé
I18n.t("greeting", name: "Ann", locale: :ja)
I18n.translate_list("date.abbr_day_names") # => ["Sun", "Mon", ...]

Toute option autre que default:, count:, count_text: et locale: remplit le %{name} de son nom ; %% est un % littéral, donc %%{x} donne %{x}, et un %{x} sans valeur lève I18n::MissingInterpolationArgument. Une clé introuvable dans la locale courante est cherchée dans la locale par défaut. Les listes, comme les noms des jours et des mois, viennent de I18n.translate_list, puisque t renvoie toujours une String.

Nombres et pluriels

count: (un Integer) choisit une forme sous la clé et remplit %{count} : zero pour 0 quand la clé en a une, sinon la catégorie de la locale, sinon other.

Langue Catégories
Anglais, et toute langue absente de ce tableau one pour 1, sinon other
Français one pour 0 et 1, many pour un multiple non nul de 1 000 000, sinon other
Russe one (1, 21, 101), few (2 à 4, 22 à 24), sinon many
Japonais, chinois other

Une locale régionale suit la règle de sa langue (pt-BR celle de pt). count_text: remplit %{count} avec une String sans choisir de forme, comme le font les messages de numericality avec leurs bornes.

Recherche paresseuse

Une clé qui commence par . est relative. Dans un template, elle est lue sous le chemin du template lui-même, comme dans Rails :

Template t(".title") lit
app/views/posts/index.html.erb posts.index.title
app/views/posts/new.html.erb, y compris quand create le rend posts.new.title
app/views/posts/_form.html.erb posts.form.title
app/views/layouts/application.html.erb layouts.application.title
app/views/__components/card_component.html.erb card_component.title
app/views/mail/_password_reset.html.erb mail.password_reset.title

Dans un contrôleur, t(".created") dans Admin::PostsController#create lit admin.posts.create.created.

Du HTML dans un texte

Une clé qui se termine par _html (ou .html) est du HTML : le template l’écrit tel quel, et échappe chaque valeur qu’on y insère (une valeur SafeString reste telle quelle). Tout autre texte est échappé.

erb
<%= t(".intro_html", name: @user.name) %>   <%# "Hello <b>%{name}</b>": the name is escaped, <b> is not %>

Dates et heures

l dans un template et I18n.l formatent un Time ou une Date avec les time.formats ou date.formats de la locale :

ruby
I18n.l(Time.utc(2026, 11, 10, 9, 5), format: :long)                  # => "November 10, 2026 09:05"
I18n.l(Date.new(2026, 11, 10), locale: :ja)                          # => "2026/11/10"
I18n.l(Time.utc(2026, 11, 10, 9, 5), format: "%a %p", locale: :ja)   # => "火 午前"

format: est un nom de format (:default s’il n’est pas donné, :short, :long ou tout autre que contiennent les dictionnaires) ou un motif. %a %A %b %B prennent les noms des jours et des mois du dictionnaire, %p %P ses time.am / time.pm (aussi avec ^, %^B) ; le reste relève de strftime, formaté directive par directive comme le fait time_tag (une directive inconnue lève une exception). Une directive de nom avec un autre drapeau ou une largeur (%-A, %10B, %#b) relève aussi de strftime et affiche donc le nom anglais ; les formats de rails-i18n n’en utilisent aucune. Un nom de format qu’aucun dictionnaire ne contient lève I18n::MissingTranslationData. Un Time est montré dans le fuseau de l’application, ou dans un autre avec zone: "America/New_York" (Fuseaux horaires).

Choisir la locale

Chaque requête commence dans la locale par défaut (config.i18n_default_locale, :en, ou CYBERTRAIN_I18N_DEFAULT_LOCALE). Une application la change dans un before_action, comme le fait examples/blog : un paramètre ?locale=, ensuite gardé dans un cookie, sinon le cookie, sinon l’Accept-Language du navigateur.

app/controllers/application_controller.rb (extrait, examples/blog)ruby
class ApplicationController < Cybertrain::Controller
  before_action :set_locale

  private

  def set_locale
    param = params[:locale]
    if I18n.locale_available?(param)
      I18n.locale = param
      cookies[:locale] = param.to_s
      return nil
    end

    stored = cookies[:locale]
    if I18n.locale_available?(stored)
      I18n.locale = stored
      return nil
    end

    I18n.locale = request.preferred_locale(I18n.available_locales)
    nil
  end
end
  • I18n.locale appartient au thread qui sert la requête, si bien que des requêtes servies en même temps gardent chacune la leur ; le framework la remet à la valeur par défaut avant chaque requête et chaque action, et avant chaque job et chaque tâche planifiée qu’un thread de travail exécute, si bien qu’un job qui la change (un avis dans la langue de son utilisateur) laisse le job suivant de ce thread à la valeur par défaut. I18n.with_locale dit la même chose dans un bloc.
  • I18n.locale = value prend un Symbol ou une String et n’accepte qu’un nom de config.i18n_available_locales (la seule locale par défaut quand la liste est vide) ; tout autre lève I18n::InvalidLocale. Elle compare des noms et ne transforme jamais le texte de la requête en Symbol, donc un paramètre peut être passé tel quel une fois que I18n.locale_available? a dit oui.
  • request.preferred_locale(available) lit Accept-Language par q-value, puis par ordre, fait correspondre une étiquette complète avant sa langue (ja-JP donne :ja) et renvoie un élément de available, ou la locale par défaut si rien ne correspond.
  • I18n.with_locale(:ja) { ... } exécute un bloc dans une autre locale et remet la précédente, même quand le bloc lève une exception : un courriel à un utilisateur dans sa langue, par exemple.

Un courriel construit dans une requête, ou une diffusion rendue là, est dans la locale de cette requête.

Modèles et messages de validation

Un message de validation est cherché quand le validateur s’exécute, dans la locale courante, selon les clés de Rails : activerecord.errors.models.<model>.attributes.<attr>.<type>, activerecord.errors.models.<model>.<type>, activerecord.errors.messages.<type>, errors.attributes.<attr>.<type>, puis errors.messages.<type>, où sont les textes fournis. Un message: sur la ligne de validation l’emporte toujours. Un texte peut utiliser %{attribute}, %{model}, %{count} et, comme dans Rails, %{value}, la valeur de l’attribut ("%{value} is already taken").

errors.full_messages joint le nom de l’attribut et le message avec errors.format ("%{attribute} %{message}" ; le japonais n’écrit pas d’espace), et un message sur :base est seul. Le nom de l’attribut est Post.human_attribute_name(:title), que gen écrit pour chaque modèle : activerecord.attributes.post.title, sinon l’attribut rendu lisible (author_id donne "Author"). I18n.human_model_name("post") lit activerecord.models.post (sa forme one: quand il a des formes plurielles), sinon le dernier segment de la clé rendu lisible ("admin/post" donne "Post"). Il n’y a pas de Post.model_name.human.

Le form builder lit les mêmes noms : f.label :title est helpers.label.<portée du formulaire>.title, sinon human_attribute_name, et f.submit est helpers.submit.create ou update avec le nom du modèle (en anglais "Create Article" ; le japonais de rails-i18n est "登録する", sans le nom).

Les helpers qui suivent la locale

  • Les helpers de nombres d’un template lisent le number.* de la locale : les séparateurs, l’unité et le format de number_to_currency (en japonais "1,234円"), et les unités de number_to_human et number_to_human_size. Une option donnée dans l’appel l’emporte. Un réglage que ni la locale courante ni la locale par défaut ne contient est l’anglais, comme les helpers de Rails reviennent à leurs valeurs par défaut : une application dont la locale par défaut n’a pas de clés number.* affiche toujours 1,234.5 et $12.50, jamais un nombre sans ses séparateurs. Cybertrain::NumberHelper appelé depuis Ruby garde les valeurs par défaut anglaises.
  • time_tag avec un nom de format, ou sans format:, passe par l ; une String de motif garde les noms anglais de strftime.
  • time_ago_in_words et distance_of_time_in_words lisent datetime.distance_in_words ("2分").
  • pluralize n’utilise l’inflecteur anglais que lorsque la locale est l’anglais ; ailleurs le mot reste tel quel, sauf si un pluriel est donné.
  • Les liens de paginate, la page des jobs et le bouton d’envoi sans modèle lisent des clés cybertrain.*, qu’une application peut surcharger comme toute autre.

Clés manquantes

Une clé introuvable dans la locale courante comme dans la locale par défaut renvoie :

Où Hors production (développement, test, préproduction) Production
I18n.t, le t d’un contrôleur "translation missing: ja.foo.bar" "Bar", le dernier segment rendu lisible
le t d’un template <span class="translation_missing" title="translation missing: ja.foo.bar">Bar</span> Bar

config.i18n_raise_on_missing = true lève à la place I18n::MissingTranslationData, partout ; un default: répond toujours d’abord. examples/blog l’active dans ses tests (c.i18n_raise_on_missing = true if c.test?), si bien qu’une clé absente des deux dictionnaires fait échouer un test au lieu d’afficher un marqueur.

Les dictionnaires fournis

Le framework fournit des dictionnaires anglais et japonais (cybertrain/locales/en.yml et ja.yml) : les clés de rails-i18n pour ce qu’utilise le framework (messages de validation, date, time, datetime.distance_in_words, number, helpers.submit, errors.template), ses propres clés sous cybertrain., et tous les textes des écrans qu’écrit cybertrain generate authentication (sessions.new.title, passwords.create.sent, les clés des courriels, activerecord.attributes.user).

La clé d’une application surcharge la clé fournie du même nom, dans cette locale. Les formes plurielles fusionnent : une application qui n’écrit que datetime.distance_in_words.x_days.zero: "today" garde les one et other fournis. Pour changer le titre de la page de connexion, ou traduire les écrans dans une troisième langue, écrivez leurs clés dans config/locales/. Dans une locale sans dictionnaire fourni, une clé que l’application n’a pas se rabat sur le texte de la locale par défaut (l’anglais fourni quand la locale par défaut est en).