Aller au contenu

ADR-027 : Extraction de l'i18n vers forge-mvc-i18n

Statut

Acceptée

Amende ADR-004 (périmètre du core minimal) et prolonge ADR-021 et ADR-022 : poursuite du dégraissage du core vers des opt-ins.

Contexte

core/i18n/ (translator par catalogues JSON, locale par défaut et fallback, cache, exceptions) échoue au test de légitimité d'ADR-004 : « si je retire cette brique du core, une application Forge basique tourne-t-elle encore ? » → oui.
La traduction est un besoin fréquent mais n'est pas une primitive générale du framework, et core/i18n/ est autonome (sa seule dépendance core est core.forge pour les clés de configuration i18n_default_locale / i18n_fallback_locale, disponible via forge-mvc).

Le module relève donc d'un opt-in, comme stats, workflow, pivot ou mail.

Particularité, le couplage au générateur CRUD.
Contrairement à mail ou pivot, trans() est tissé dans le générateur CRUD du cœur : forge make:crud et les pages publiques émettent des templates qui appellent {{ trans(...) }} (crud.edit, common.save, crud.confirm_delete…).
Aujourd'hui le renderer Jinja du cœur expose toujours trans comme global.
Une extraction « en dur » casserait au rendu tout CRUD généré tant que forge-mvc-i18n n'est pas installé.

Décision

Le translator runtime core/i18n/ est extrait vers l'opt-in forge-mvc-i18n, et le cœur conserve un repli trans no-op.

Avant Après
core/i18n/<module>.py forge_mvc_i18n.<module> (API réexportée par forge_mvc_i18n)
from core.i18n import … from forge_mvc_i18n import …
renderer : trans = vraie fonction (toujours) renderer : trans = repli no-op ; l'opt-in l'enrichit
  • Repli no-op du noyau.
    Le renderer Jinja (integrations/jinja2/renderer.py) expose toujours un global trans (_default_trans) qui retourne la clé telle quelle.
    Les templates générés rendent donc sans erreur, traduction ou non.
    Quand forge-mvc-i18n est installé, le renderer remplace ce repli par la vraie fonction trans() chargeant les catalogues.
    C'est exactement le pattern déjà utilisé pour can() (RBAC fournit un défaut lambda: False, l'opt-in l'enrichit), deux lignes plus haut dans le même renderer.
  • Clés de configuration conservées dans le noyau.
    i18n_default_locale et i18n_fallback_locale restent dans le registre _DEFAULTS de core.forge, comme les clés mail_* après ADR-022 : le registre de configuration reste centralisé, seul le code migre.
  • CLI de scaffolding conservée dans le noyau.
    forge i18n:init et forge i18n:check (cli/assets/i18n.py) sont autonomes : ils créent et vérifient translations/fr.json sans importer le translator runtime.
    Ils relèvent de l'outillage de projet du CLI cœur et restent disponibles sans installer forge-mvc-i18n.
    Seul le translator runtime est extrait.

Pré-1.0 (convention bêta) : extraction sans alias déprécié dans le core.
Les anciens chemins core.i18n sont supprimés.

Conséquences

  • Nouveau paquet packages/forge-mvc-i18n/ (distribution PyPI séparée, dépend de forge-mvc).
  • Garde-fou d'extraction I18N-EXTRACT-001 : le core ne contient plus i18n, le paquet expose l'API publique, le renderer garde un repli no-op.
  • Tests i18n protégés par pytest.importorskip("forge_mvc_i18n") (core autonome, garde-fou TESTS-OPTIN-IMPORTORSKIP-001).
  • forge_mvc_i18n ajouté aux listes opt-in transverses (importorskip, core-only-contract, classifiers PyPI, sweep imports docs) + release-policy.md.
  • DX : un CRUD généré sans forge-mvc-i18n affiche les clés brutes (crud.edit) au lieu du libellé traduit, dégradé mais lisible, jamais cassé.

Suite

  • Publication PyPI de forge-mvc-i18n (alignée sur la version du core) lors de la prochaine release des opt-ins.