DTLi18n — Manuel de référence v1.1-46

Préface

Objet du manuel

Ce manuel décrit ce qu'est DTLi18n, la raison pour laquelle il a été créé et ce qu'il fait. Il constitue une référence fonctionnelle et d'architecture. Il ne décrit volontairement ni menu, ni commande, ni procédure d'utilisation pas à pas.

DTLi18n consulte, édite et fiabilise des catalogues de textes de localisation bilingues français/anglais, et assiste la mise en conformité i18n d'un projet Python : vérification des références entre code et catalogue, audit croisé avec correction des incohérences sûres, et conversion initiale d'un projet non internationalisé.

Audience visée

Le document s'adresse aux développeurs et mainteneurs de la suite NetDTL responsables des textes affichés à l'utilisateur, ainsi qu'à toute personne devant comprendre le comportement de DTLi18n avant de l'intégrer à un projet ou d'en interpréter les rapports.

Principes structurants

• Localité : catalogues, rapports et base d'apprentissage restent sur l'ordinateur, sans dépendance à un service distant.
• Prudence par défaut : toute opération qui modifie du code source ou un catalogue est précédée d'une prévisualisation et d'une confirmation, et accompagnée d'une sauvegarde.
• Automatisation limitée à ce qui est sûr : seules les corrections déterministes et sans ambiguïté sont appliquées automatiquement ; le reste est soumis à une décision explicite.
• Vérification après coup : toute migration ou conversion est suivie d'un contrôle de syntaxe et de résolution des références, dont le résultat figure dans un rapport.
• Non-réutilisation des numéros : le numéro d'une clé supprimée est retiré définitivement, jamais réattribué.
• Bilinguisme du contenu : chaque entrée de catalogue porte un texte français et un texte anglais ; l'interface de DTLi18n elle-même est en français.

Contexte

Origine du besoin

Un catalogue de textes bilingues entretenu à la main dérive avec le temps : des clés sont renommées ou supprimées côté code sans que le catalogue suive, des numéros de clé finissent par se dupliquer, des traductions restent vides, et il devient difficile de savoir avec certitude si une clé donnée est encore utilisée quelque part dans un projet de taille conséquente.

Le problème se pose différemment pour un projet qui n'a jamais été internationalisé : ses textes utilisateur sont codés en dur, mélangés à des chaînes techniques (journalisation, expressions régulières, noms de fichiers) qu'il ne faut pas traduire, et la conversion complète à la main est longue et risque d'introduire des erreurs de syntaxe ou des références vers des clés qui n'existent pas encore.

Problème traité

DTLi18n a été créé pour couvrir les deux moitiés de ce cycle de vie avec les mêmes garanties de sécurité : entretenir un catalogue existant en le gardant synchronisé avec le code qui l'utilise, et amorcer l'internationalisation d'un projet qui ne l'est pas encore, sans jamais laisser le projet dans un état où une référence pointe vers une clé absente ou où le code ne compile plus.

Architecture

Vue d'ensemble

DTLi18n s'articule autour de quatre familles de traitement : l'édition directe d'un catalogue, l'analyse des références entre code et catalogue, l'audit croisé d'un projet déjà internationalisé, et la conversion initiale d'un projet qui ne l'est pas. Ces quatre familles partagent le même mécanisme de sauvegarde, de prévisualisation et de rapport.

Composants

Organisation des fichiers

Modèle de données

Catalogue i18n

Un catalogue est un dictionnaire dont chaque clé est associée soit à un objet contenant un texte fr et un texte en, soit, dans les catalogues hérités, à une simple chaîne interprétée comme texte français avec un texte anglais vide. DTLi18n accepte ce dictionnaire sous forme de littéral Python ou de fichier JSON, et préserve le format d'origine à l'enregistrement.

Identification des clés

La convention reconnue par DTLi18n associe à chaque clé un préfixe alphabétique, un numéro et, facultativement, un libellé séparé par un tiret ou un souligné (par exemple t0001_nom_de_cle). Ce numéro sert de repère stable pour la navigation directe, la détection de doublons et la numérotation ; une clé qui ne respecte pas ce format reste éditable et consultable, mais ne possède pas de numéro de référence.

Registre des numéros retirés

Lorsqu'une clé est supprimée, son numéro est inscrit dans un registre permanent associé au catalogue. Ce numéro n'est plus jamais proposé par la numérotation, ce qui évite qu'un numéro déjà rencontré dans l'historique du projet, une sauvegarde ou un rapport antérieur, en vienne à désigner un texte différent.

Base d'apprentissage locale

DTLi18n conserve, dans une base locale, les décisions prises sur des chaînes de caractères ambiguës lors d'un audit ou d'une conversion. Ces décisions sont réutilisées lors des analyses suivantes pour proposer, avec un niveau de confiance explicite, une classification automatique de cas jugés similaires, sans jamais appliquer cette classification sans que l'utilisateur en ait le contrôle.

Fonctionnalités

Consultation et édition d'un catalogue

DTLi18n peut afficher l'intégralité d'un catalogue sans le modifier, ou l'ouvrir dans un éditeur qui présente chaque clé avec son texte français et anglais, permet de naviguer entrée par entrée ou par bloc, de rechercher un texte ou une clé, et de modifier le texte de chaque langue indépendamment. Une entrée peut être laissée inchangée, remplacée ou explicitement vidée.

Numérotation et migration des clés

DTLi18n peut renommer l'ensemble des clés d'un catalogue selon la convention numérotée, en choisissant un numéro de départ, un préfixe et une largeur de numérotation. Le renommage est répercuté dans toutes les références trouvées dans les fichiers source du projet. L'opération est précédée d'une prévisualisation complète du renommage et des statistiques associées, et refusée d'emblée si des doublons de numéro ou des erreurs de syntaxe existent déjà dans le projet.

Suppression sécurisée d'une clé

La suppression d'une clé est refusée tant que des références à cette clé subsistent dans les fichiers source du projet analysé. Une fois la suppression confirmée avec un motif, la clé est retirée du catalogue et son numéro inscrit dans le registre des numéros retirés, de façon permanente.

Vérification des références d'un projet

DTLi18n peut confronter un catalogue aux fichiers source d'un projet pour établir la liste des références vers une clé absente du catalogue, et la liste des clés du catalogue sans usage observable dans le code. Cette analyse distingue une référence directe et littérale d'un usage indirect ou propagé, et signale les appels dynamiques dont la clé effective ne peut pas être déterminée avec certitude ; l'absence de référence observable n'est pas présentée comme une preuve d'inutilisation.

Audit croisé d'un projet internationalisé

DTLi18n confronte les catalogues et les sources d'un projet déjà internationalisé pour détecter les incohérences — clés orphelines, références brisées, doublons de numéro, absence de mécanisme de sélection de langue réellement démontré — et associe à chacune un niveau de confiance. Les incohérences pour lesquelles une correction déterministe et sans ambiguïté existe peuvent être appliquées automatiquement après une confirmation unique, avec sauvegarde préalable. Les autres font l'objet de textes de remédiation destinés à être traités individuellement, en dehors de DTLi18n. Un audit avant correction et un audit après correction sont tous deux consignés dans le même rapport.

Conversion d'un projet non internationalisé

DTLi18n détecte les chaînes de caractères visibles à l'utilisateur codées en dur dans les fichiers Python d'un projet, et les classe en trois catégories : probablement traduisibles, probablement techniques, ou ambiguës. Chaque catégorie peut être incluse ou exclue en bloc, ou revue chaîne par chaîne. Les chaînes retenues reçoivent une clé proposée selon la convention numérotée, et servent à construire un nouveau catalogue ainsi que les modifications correspondantes des fichiers source, avec sauvegarde préalable et vérification finale de la syntaxe et de la résolution des références.

Score de maturité i18n

DTLi18n calcule, pour un projet, un score et un état global d'internationalisation, à partir de la détection effective de l'internationalisation, de la complétude des traductions françaises et anglaises, de la part des clés dont l'usage est observé dans le code, du nombre de chaînes encore codées en dur ou ambiguës, et de la présence démontrée d'un mécanisme de sélection de langue.

Référence interne

Modules internes

Robustesse et intégrité

• Toute modification d'un catalogue est précédée d'une copie de sauvegarde du fichier d'origine.
• Toute modification de fichiers source (numérotation, suppression, correction d'audit, conversion) est précédée d'une sauvegarde de chaque fichier concerné.
• La numérotation et la conversion sont refusées d'emblée en présence d'erreurs de syntaxe Python existantes dans le projet.
• La suppression d'une clé est refusée tant qu'une référence à cette clé subsiste dans le code source.
• Toute écriture de catalogue ou de code source passe par un fichier temporaire puis un remplacement, et le résultat est revalidé syntaxiquement avant d'être conservé.
• Des modifications de traduction non sauvegardées bloquent le lancement de la numérotation et de la suppression, pour éviter une perte de saisie.

Annexes

Limites connues

• Seules les clés respectant la convention préfixe + numéro possèdent un numéro de référence ; les autres restent éditables mais échappent à la navigation directe, à la détection de doublons et à la numérotation.
• La détection des références s'appuie sur l'analyse des appels à des fonctions nommées explicitement dans le code ; une clé atteinte uniquement par un appel entièrement dynamique et non résolu n'est pas comptée comme référencée.
• L'absence de référence observable pour une clé ne constitue pas une preuve qu'elle est inutilisée.
• L'audit n'applique automatiquement que les corrections explicitement qualifiées de sûres ; toute autre incohérence requiert un traitement individuel.
• La classification des chaînes candidates à la conversion est une heuristique assistée par la base d'apprentissage locale ; les cas ambigus requièrent une décision explicite, au moins la première fois qu'un motif est rencontré.
• DTLi18n ne traduit pas automatiquement un texte d'une langue vers l'autre.

Versions et schémas

Glossaire