Skip to content

Guide de traduction (i18n)

Copy of sumaris-app/.agents/rules/translations.md (rule written for AI coding agents, always applied). Do not edit here: run npm run site:sync-rules to update it.

Principes généraux

  • Utiliser la bibliothèque ngx-translate (via le pipe standalone TranslatePipe de @ngx-translate/core) — TranslateModule / TranslateModule.forChild() n'est plus utilisé dans ce projet.
  • Les fichiers de traduction se trouvent dans src/assets/i18n/.
  • Les deux langues supportées sont le Français (fr.json) et l'Anglais (en.json).
  • Toute nouvelle clé doit être ajoutée dans les deux fichiers.

Structure des fichiers JSON

Les fichiers suivent une structure hiérarchique basée sur les domaines fonctionnels :

  1. COMMON : Libellés génériques réutilisables (boutons, messages d'erreur communs, formats de date).
  2. TRIP : Tout ce qui concerne les marées de pêche.
    • TRIP.TABLE : En-têtes de tableau pour les marées.
    • TRIP.EDIT : Libellés des formulaires d'édition de marée.
  3. SAMPLE : Tout ce qui concerne les échantillons/individus.
    • SAMPLE.EDIT : Formulaires d'édition.
    • SAMPLE.TABLE : Tableaux.

Conventions de nommage des clés

  • Utiliser des majuscules avec des underscores (SNAKE_CASE).
  • Préfixer les boutons par BTN_ (ex: BTN_SAVE, BTN_ADD).
  • Préfixer les erreurs par ERROR. (ex: ERROR.FIELD_REQUIRED).
  • Utiliser le nom du composant comme préfixe i18n dans le code TypeScript (ex: TRIP.SAMPLE.EDIT.).

Utilisation dans le code

Dans les templates HTML

Utiliser le pipe translate ou translateContext : 

<ion-label>{{ 'COMMON.BTN_SAVE' | translate }}</ion-label>
<input [placeholder]="'TRIP.SAMPLE.EDIT.LABEL' | translateContext: i18nSuffix" />

Ne jamais utiliser la directive structurelle translate (<div translate>MY.KEY</div>) : cette syntaxe n'est plus supportée depuis @ngx-translate/core 18.0.0 (utilisé depuis la migration Angular 21) — l'élément affiche alors la clé brute au lieu du texte traduit. Utiliser systématiquement le pipe :

<!-- ❌ Ne plus utiliser (cassé depuis ngx-translate 18) -->
<div translate>MY.I18N_KEY</div>

<!-- ✅ Toujours utiliser -->
<div>{{ 'MY.I18N_KEY' | translate }}</div>

Pour migrer en masse d'anciens templates encore écrits avec la directive translate, utiliser la skill ngx-translate-directive-migration (voir .agents/skills/ngx-translate-directive-migration/SKILL.md).

Dans le code TypeScript

Injecter le TranslateService ou utiliser this.translateContext (si disponible via l'héritage) : 

this.translate.instant('COMMON.ERROR.MESSAGE');

Exemple (basé sur fr.json)

Pour ajouter un champ program dans l'édition d'un échantillon :

  1. Identifier le domaine : TRIP > SAMPLE > EDIT.
  2. Ajouter la clé dans fr.json : 
    "TRIP": {
  "SAMPLE": {
    "EDIT": {
      "PROGRAM": "Programme de collecte"
    }
  }
}
  3. Ajouter la clé correspondante dans en.json : 
    "TRIP": {
  "SAMPLE": {
    "EDIT": {
      "PROGRAM": "Data collection program"
    }
  }
}

Maintenance et automatisation

Pour synchroniser les clés entre les fichiers JSON et automatiser les traductions basées sur le glossaire métier, utilisez la skill i18n-management. Elle fournit des scripts Python pour :

  • Comparer les fichiers et identifier les clés manquantes ;
  • Fusionner et trier les clés selon l'ordre de fr.json ;
  • Traduire automatiquement les nouveaux termes via un dictionnaire métier.

Reportez-vous à la documentation de la skill dans .agents/skills/i18n-management/SKILL.md pour plus de détails.