I18n

Environ 2 min

I18n

Présentation

La classe I18n fournit un système de traduction centralisé basé sur des fichiers JSON, conçu pour des environnements Node.js.
Elle repose sur un singleton, un mécanisme de cache optionnel, et une structure de données dédiée (TranslationMap) permettant la substitution dynamique de variables dans les chaînes traduites.

L’objectif principal est de :

charger une langue active,
accéder aux traductions via une API simple (get, has),
enrichir dynamiquement le dictionnaire avec des fichiers optionnels,
gérer proprement les logs et erreurs de chargement.

Architecture générale

Pattern : Singleton
Stockage interne : TranslationMap (extension de Map)
Source des traductions : fichiers JSON
Portée : serveur / Node.js
Support du templating : {{variable}}

Structure des fichiers


local/
├─ fr.json
├─ en.json
└─ ...

Des fichiers JSON supplémentaires peuvent être chargés dynamiquement (modules, plugins, features).

Dépendances

import fs from "fs";
import path from "path";
import { TranslationMap } from "./Class/CustomMaps/TranslationMap.js";

Singleton

Accès à l’instance

const i18n = I18n.getInstance();

Le constructeur est volontairement privé afin de garantir une instance unique dans toute l’application.

Propriétés statiques principales

Propriété	Description
`pathLocal`	Dossier racine des fichiers de langue
`TranslationMap`	Dictionnaire actif des traductions
`SaveLoad`	Active ou non le cache de langues
`TampSave`	Cache des langues déjà chargées
`OptionnalFiles`	Fichiers JSON additionnels par langue

Chargement d’une langue

`LoadLocal(local: string)`

Charge une langue principale depuis un fichier <local>.json.

Étapes internes

Vérification du cache (si activé)
Validation de l’existence du fichier
Lecture et parsing JSON
Création d’une nouvelle TranslationMap
Binding dynamique des méthodes
Chargement des fichiers optionnels associés
Mise en cache (optionnelle)

i18n.LoadLocal("fr");

Avertissement

Si le fichier de langue est introuvable ou invalide, la langue n’est pas chargée et un avertissement est émis.

Chargement de fichiers optionnels

Enregistrement

registerOptionnalFiles(
  ["./modules/shop/fr.json", "./modules/blog/fr.json"],
  "fr"
);

Associe des fichiers JSON supplémentaires à une langue donnée.

Chargement effectif

LoadOptionnalFiles(paths: string[])

Ignore les fichiers non JSON
Ignore les fichiers inexistants
Fusionne les clés valides dans la TranslationMap active
Écrase les clés existantes si doublon

API de traduction exposée

Ces méthodes sont dynamiquement liées après le chargement d’une langue.

`get`

get(
  key: string,
  args?: { [key: string]: any }
): string

Retourne la traduction associée à une clé.

i18n.get("hello_user", { name: "Jean" });

{
  "hello_user": "Bonjour {{name}}"
}

Résultat :

Bonjour Jean

Si la clé est absente :

{{hello_user}}

`has`

has(key: string): boolean

Vérifie l’existence d’une clé de traduction.

`replacesInText`

replacesInText(
  text: string,
  tags?: {
    [Tag: string]: { [key: string]: any }
  }
): string

Permet de traduire un texte libre contenant plusieurs clés.

i18n.replacesInText(
  "Titre : {{title}} – {{description}}",
  {
    title: { value: "Accueil" },
    description: {}
  }
);

Classe `TranslationMap`

Présentation

TranslationMap étend Map<string, string> et ajoute des fonctionnalités de templating intégré.

`get`

get(
  key: string,
  args?: { [key: string]: string }
): string

Retourne {{key}} si la traduction est absente
Remplace automatiquement les variables {{variable}}

`replacesInText`

replacesInText(
  text: string,
  ListeTag?: {
    [Tag: string]: { [key: string]: any }
  }
): string

Effectue une substitution globale sur un texte en utilisant les clés de traduction comme tags.

Journalisation

La classe utilise un ConsoleLogger dédié :

avertissements : fichiers manquants / invalides
erreurs : parsing JSON
logs informatifs : langue chargée, fichiers optionnels

Les messages eux-mêmes peuvent être localisés, car ils passent par i18n.get().

Bonnes pratiques

Charger la langue au démarrage de l’application
Centraliser les clés dans des fichiers cohérents
Préférer les fichiers optionnels pour les modules
Activer le cache (SaveLoad) en production
Toujours prévoir une clé de fallback

Limites connues

Fonctionne uniquement côté Node.js
Ne gère pas le pluriel ou les règles linguistiques avancées
Pas de fallback automatique vers une autre langue

Conclusion

La classe I18n fournit un système de traduction léger, extensible et orienté développeur, parfaitement adapté à des projets modulaires ou outillés. Combinée à TranslationMap, elle permet une gestion souple des chaînes localisées tout en restant simple à maintenir.