5. Traduire

Kewos ne contient aucune chaîne visible écrite en dur, ni côté serveur, ni côté interface. Tout passe par une clé et un fichier de traduction par langue.

Votre module suit la même règle. Sans lui, le moteur retombe sur les noms techniques du code : une colonne s’appelle published_year, une valeur s’affiche worn, un titre de section s’affiche section.work. Ce n’est pas cassé, c’est illisible.

Le fichier

i18n/en.json :

{
  "module.library": "Library",

  "model.library_title": "Catalogue",
  "model.library_copy": "Copies",
  "model.library_member": "Members",
  "model.library_loan": "Loans",

  "section.work": "The work",
  "section.reference": "Reference",

  "library_title.name": "Title",
  "library_title.author": "Author",
  "library_title.isbn": "ISBN",
  "library_title.published_year": "Published",
  "library_title.genre": "Genre",
  "library_title.genre.fiction": "Fiction",
  "library_title.genre.science": "Science",

  "library_loan.state": "State",
  "library_loan.state.out": "Out",
  "library_loan.state.returned": "Returned",
  "library_loan.state.lost": "Lost",

  "workflow.check_in": "Check in",
  "workflow.declare_lost": "Declare lost",

  "group.library_reader": "Reader",
  "group.library_librarian": "Librarian"
}

Puis i18n/fr.json avec exactement les mêmes clés et d’autres valeurs.

Les clés, une fois pour toutes

Forme	Ce que ça nomme
module.<module>	Le module dans le lanceur.
model.<modèle>	Le modèle dans les menus et les titres d’écran.
<modèle>.<champ>	Un champ, partout où il apparaît.
<modèle>.<champ>.<valeur>	Une valeur de sélection.
section.<clé>	Un titre de section de formulaire.
workflow.<transition>	Un bouton de transition d’état.
group.<groupe>	Un groupe de permissions.
<modèle>.dashboard.<clé>	Un indicateur ou un graphique de tableau de bord.

Ce que ça change

Les colonnes du kanban portent « Out », « Returned », « Lost » ; le module s’appelle « Library » ; les cartes disent « Member » et « Due back ». Vous n’avez touché à aucun écran : un fichier de correspondances, et tout se met en place.

Les autres langues

Ajoutez i18n/de.json, i18n/es.json avec les mêmes clés. La langue de l’utilisateur décide, et une clé absente d’un fichier retombe sur la langue par défaut.

Un test qui vaut son poids

Écrivez un test qui compare les jeux de clés de vos fichiers de langue et échoue si l’un en a une que l’autre n’a pas.

def test_locales_carry_the_same_keys() -> None:
    en = json.loads((I18N / "en.json").read_text())
    fr = json.loads((I18N / "fr.json").read_text())
    assert set(en) == set(fr)

Une clé oubliée dans un seul fichier ne lève aucune erreur : elle affiche silencieusement une autre langue à l’utilisateur, et personne ne le remarque avant un client mécontent.

Une clé absente s’affiche telle quelle

Pas d’erreur, pas de journal : la clé brute part à l’écran. C’est exactement ce qui est arrivé sur un bouton de transition de ce module, et la capture est à l’étape Les états.

Le deuxième dossier, celui des messages du serveur

i18n/ traduit l’interface : ce que le moteur affiche à partir de vos déclarations, les noms de champs, les valeurs, les boutons. Il ne traduit pas les phrases que votre code produit.

Un message d’erreur métier, l’objet d’un courriel, une mention sur un PDF : ceux-là passent par t("clé") côté serveur, et le serveur ne lit pas i18n/. Il lit un second dossier :

modules/library/
├── i18n/            <- l'interface (le moteur de vues)
│   ├── fr.json
│   └── en.json
└── translations/    <- vos messages, résolus par t()
    ├── fr.json
    └── en.json

translations/fr.json

{ "library.error.already_out": "Cet exemplaire est déjà sorti." }

raise BusinessRuleError(t("library.error.already_out"))

Poser la clé dans le mauvais dossier ne lève rien

Les deux dossiers ont la même forme, et rien ne prévient. Exécuté sur une instance :

clé dans translations/ : Cet exemplaire est déjà sorti.
clé dans i18n/         : library.error.wrong_place

La deuxième ligne est ce que voit l’utilisateur : la clé brute. Le serveur laisse une trace dans son journal (missing translation key ...), et c’est tout. Ce piège a coûté un aller-retour complet pendant l’écriture de ce parcours.

Même règle qu’au-dessus : les mêmes clés dans toutes les langues, et un test qui compare les jeux de clés.

Le même fichier, en KM

Un module KM porte ses traductions dans son fichier, un bloc par langue :

translate en {
  model.library_title  "Catalogue"
  library_title.name   "Title"
  library_title.genre.fiction "Fiction"
  section.work         "The work"
  workflow.check_in    "Check in"
}

translate fr {
  model.library_title  "Catalogue"
  library_title.name   "Titre"
  library_title.genre.fiction "Fiction"
  section.work         "L'œuvre"
  workflow.check_in    "Rendre"
}

Les clés sont exactement les mêmes, et la règle de l’étape ne bouge pas : une clé présente dans une langue et absente dans une autre est un défaut, quel que soit le format.

Et ensuite

Les droits.