DTLi18n — Guide utilisateur v1.1-46

Préface

Objet du guide

Ce guide explique comment utiliser DTLi18n pour consulter et éditer un catalogue de textes bilingues français/anglais, le faire migrer vers une convention de clés numérotées, vérifier et auditer l'internationalisation d'un projet Python, et convertir un projet qui ne l'est pas encore. Il couvre le menu principal, l'éditeur interactif, les options en ligne de commande et un ensemble de scénarios courants.

Pour la description fonctionnelle de l'outil, la raison pour laquelle il a été créé et le détail de son fonctionnement interne, consultez le Manuel de référence DTLi18n.

Audience visée

Ce guide s'adresse aux développeurs et mainteneurs qui utilisent DTLi18n au quotidien pour maintenir un catalogue de textes ou faire progresser l'internationalisation d'un projet Python de la suite NetDTL.

Rappel : qu'est-ce que DTLi18n

DTLi18n consulte, édite et fiabilise des catalogues de textes de localisation bilingues, 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é. Ce rappel est volontairement bref ; le pourquoi et le fonctionnement interne sont développés dans le manuel de référence.

Prise en main

Lancement

DTLi18n se lance de trois façons :

• Sans argument : ouvre le menu principal, décrit ci-dessous.
• Avec le chemin d'un fichier i18n (DTLi18n chemin/vers/catalogue.py) : ouvre directement l'éditeur sur ce fichier.
• Avec le chemin d'un dossier de projet (DTLi18n chemin/vers/projet) : analyse directement le projet et propose une conversion s'il n'est pas internationalisé.

L'option --mode précise l'action à effectuer sur le chemin donné ; elle est détaillée dans Mode non interactif.

Convention de clé

DTLi18n reconnaît les clés au format t0001_nom_de_cle : un préfixe, un numéro, et facultativement un libellé. Ce numéro permet l'accès direct par G, la détection de doublons et la numérotation automatique. Une clé qui ne suit pas ce format reste consultable et modifiable, mais ne bénéficie pas de ces fonctions.

Ouvrir un fichier sans clés numérotées

Si le fichier i18n sélectionné pour édition ne contient aucune clé au format numéroté, DTLi18n n'ouvre pas l'éditeur directement. Il affiche la convention conseillée, un exemple de renommage basé sur la première clé du fichier, et propose deux issues : T pour lancer l'assistant de numérotation (voir Numéroter les clés), ou Q pour quitter sans modification.

Menu principal

Le menu principal propose cinq modes, plus la sortie :

1. Lister les textes d'un fichier i18n

Ouvre un sélecteur de fichier, puis affiche l'intégralité du catalogue choisi — clé, texte français et texte anglais de chaque entrée — sans le modifier, avec une pause toutes les 20 entrées. Utile pour parcourir ou exporter visuellement un catalogue sans risque de le modifier par erreur.

2. Éditer un fichier i18n

Ouvre un sélecteur de fichier, puis ouvre le catalogue choisi dans l'éditeur interactif décrit dans Commandes de l'éditeur. Si le fichier ne contient aucune clé numérotée, l'avertissement décrit dans Ouvrir un fichier sans clés numérotées s'affiche d'abord.

3. Vérifier l'internationalisation d'un projet

Ouvre un sélecteur de dossier, puis analyse le projet choisi : détection de l'état i18n, complétude des traductions, part des clés dont l'usage est observé dans le code, chaînes encore codées en dur, score et état global de maturité. Si le projet est déjà internationalisé, le résultat s'affiche et l'outil revient au menu. S'il ne l'est pas, DTLi18n demande s'il faut préparer une conversion FR/EN ; répondre par l'affirmative enchaîne directement sur le mode 5.

4. Auditer un projet internationalisé

Ouvre un sélecteur de dossier, puis confronte les catalogues et les sources du projet choisi pour détecter les incohérences : clés orphelines, références brisées, doublons, absence de sélection de langue démontrée. Un audit initial est affiché ; si des corrections sûres existent, DTLi18n propose de les appliquer après confirmation unique, avec sauvegarde. Un second audit après correction est alors affiché, et un rapport JSON avant/après est écrit à la racine du projet. Les incohérences restantes peuvent donner lieu à des prompts de remédiation, copiables dans le presse-papiers pour un traitement individuel hors de DTLi18n.

5. Convertir un projet non internationalisé

Ouvre un sélecteur de dossier, puis détecte les chaînes visibles à l'utilisateur codées en dur dans le projet choisi et les classe en trois catégories : probablement traduisibles, probablement techniques, ambiguës. Pour chaque catégorie, DTLi18n propose de l'inclure en bloc, de l'exclure en bloc, ou de revoir chaque chaîne individuellement ; les chaînes ambiguës sont revues individuellement par défaut. Une synthèse complète est affichée avant toute écriture ; après confirmation, DTLi18n crée un nouveau catalogue, modifie les fichiers source concernés, sauvegarde chaque fichier modifié et écrit un rapport de conversion.

Commandes de l'éditeur

Une fois un catalogue ouvert (mode 2, ou fichier passé en ligne de commande), DTLi18n affiche l'entrée courante — sa clé, son texte français et son texte anglais — ainsi que la ligne de commandes suivante :

Navigation

↑ et ↓ déplacent d'une entrée ; PgUp/PgDn déplacent de dix entrées ; Home et End vont à la première et à la dernière entrée du catalogue.

Modifier une entrée (Entrée ou E)

Affiche le texte français et anglais actuels de la clé courante et invite à saisir un nouveau texte pour chaque langue. Laisser le champ vide conserve le texte existant ; saisir =vide l'efface. La modification n'est conservée qu'en mémoire tant qu'elle n'a pas été sauvegardée avec S.

Rechercher (/) et aller à un numéro ou une clé (G)

/ recherche un numéro, une clé exacte, ou un texte français ou anglais contenant la saisie, en parcourant le catalogue à partir de l'entrée courante ; N répète la dernière recherche. G accède directement à une entrée par son numéro (sous les formes 42, 042 ou t042) ou par sa clé complète. Un numéro ou une clé peut aussi être saisi directement à l'invite de commande pour un accès immédiat.

Doublons (D) et traductions manquantes (M)

D liste les numéros de clé utilisés plusieurs fois dans le catalogue ouvert. M liste les clés dont le texte français ou anglais est vide, jusqu'à 200 entrées.

Clés non référencées (R)

Demande le dossier racine du projet, l'analyse, puis liste les clés du catalogue qu'aucune référence trouvée dans le code n'utilise. Cette vérification est plus simple que celle du mode V : elle ne distingue pas les usages indirects ou dynamiques.

Vérifier le projet (V)

Demande le dossier racine du projet, puis effectue une analyse plus fine que R : références trouvées, clés référencées dans le code mais absentes du catalogue, et clés sans usage observable en distinguant les usages directs des usages indirects ou par appel dynamique non résolu. S'il existe des clés sans usage observable, DTLi18n propose de les lister à l'écran (L) ou de les exporter dans un fichier texte à la racine du projet (E).

Numéroter les clés (T)

Lance l'assistant de numérotation : bilan des clés déjà numérotées et non numérotées, choix du numéro de départ (proposé automatiquement après le plus grand numéro existant, y compris les numéros retirés), du préfixe et de la largeur de numérotation, puis demande le dossier racine du projet. Une prévisualisation complète du renommage est affichée avant toute confirmation. L'assistant est bloqué si des modifications ne sont pas encore sauvegardées, si des doublons de numéro existent, ou si le projet contient des erreurs de syntaxe Python.

Supprimer une clé (X)

Analyse d'abord les références à la clé courante dans le projet ; si des références subsistent, la suppression est refusée et leur emplacement est affiché. Sans référence restante, DTLi18n demande un motif de suppression puis une confirmation explicite. Une fois confirmée, la clé est retirée du catalogue et son numéro inscrit définitivement dans le registre des numéros retirés.

Sauvegarder (S) et quitter (Q)

S enregistre le catalogue sur disque, après avoir conservé une copie de l'ancienne version dans backup/. Q termine l'édition ; si des modifications ne sont pas sauvegardées, DTLi18n demande de sauvegarder, d'abandonner les modifications, ou d'annuler la sortie.

Mode non interactif

Vue d'ensemble

DTLi18n accepte un chemin en argument et une option --mode pour exécuter directement une action, sans passer par le menu principal.

• Chemin d'un fichier, sans --mode ou avec --mode edit : ouvre l'éditeur, comme le mode 2.
• Chemin d'un fichier avec --mode list : liste le catalogue sans le modifier, comme le mode 1.
• Chemin d'un dossier, sans --mode ou avec --mode verify : analyse le projet, comme le mode 3.
• Chemin d'un dossier avec --mode convert : analyse le projet et propose directement la conversion sans redemander confirmation préalable, comme le mode 5.
• Chemin d'un dossier avec --mode audit : audit croisé, comme le mode 4.

--version affiche uniquement le numéro de version de DTLi18n.

Aide-mémoire des options en ligne de commande

Scénarios courants

Corriger rapidement une traduction existante

1. Lancez DTLi18n chemin/vers/catalogue.py pour ouvrir directement l'éditeur.
2. Appuyez sur / et saisissez un extrait du texte ou la clé à corriger.
3. Appuyez sur E, saisissez le nouveau texte pour la ou les langues concernées.
4. Appuyez sur S pour sauvegarder.

Faire migrer un catalogue historique vers la convention numérotée

1. Ouvrez le catalogue en édition. Si aucune clé n'est numérotée, DTLi18n affiche directement l'avertissement décrit dans Ouvrir un fichier sans clés numérotées.
2. Appuyez sur T pour lancer l'assistant de numérotation.
3. Validez le numéro de départ, le préfixe et la largeur proposés, ou ajustez-les.
4. Indiquez le dossier racine du projet dont les références doivent être mises à jour.
5. Relisez la prévisualisation, puis confirmez.

Supprimer une clé obsolète en toute sécurité

1. Sauvegardez toute modification en cours avec S : la suppression est bloquée sinon.
2. Placez-vous sur la clé à supprimer, puis appuyez sur X.
3. Si des références subsistent dans le projet, supprimez-les d'abord dans le code source, puis relancez X.
4. Indiquez un motif, puis confirmez la suppression.

Vérifier qu'aucune clé n'a été oubliée après un développement

Deux niveaux de vérification sont disponibles : R pour une liste rapide des clés sans référence trouvée, ou V pour une analyse plus fine distinguant les usages directs, indirects et dynamiques, avec possibilité d'exporter le résultat.

1. Dans l'éditeur du catalogue concerné, appuyez sur V.
2. Indiquez le dossier racine du projet si ce n'est pas déjà celui proposé par défaut.
3. Examinez les références vers une clé absente, le cas échéant, en priorité : elles indiquent un texte utilisé dans le code mais non défini dans le catalogue.
4. Pour les clés sans usage observable, appuyez sur L pour les lister ou E pour les exporter avant de décider d'une suppression.

Auditer un projet i18n existant et appliquer les corrections sûres

1. Depuis le menu principal, choisissez 4 et sélectionnez le dossier du projet.
2. Consultez l'audit initial : incohérences détectées, niveau de confiance de chacune, état du sélecteur de langue.
3. Si des corrections sûres sont proposées, répondez par l'affirmative pour les appliquer ; une sauvegarde est créée automatiquement.
4. Consultez l'audit après correction, puis le rapport JSON écrit à la racine du projet.
5. Pour les incohérences restantes, copiez un prompt de remédiation dans le presse-papiers afin de le traiter individuellement.

Internationaliser un projet français pour la première fois

1. Depuis le menu principal, choisissez 5 et sélectionnez le dossier du projet, ou 3 puis répondez par l'affirmative à la proposition de conversion.
2. Pour chaque catégorie de chaînes détectées, décidez d'une inclusion en bloc, d'une exclusion en bloc, ou d'une revue individuelle ; les chaînes ambiguës sont revues une par une par défaut.
3. Relisez la synthèse globale avant écriture : catalogue à créer, nombre de chaînes incluses par catégorie, fichiers concernés.
4. Confirmez pour déclencher l'écriture du nouveau catalogue, la modification des fichiers source et la création du rapport de conversion.

Messages et blocages

Situations bloquantes courantes

Annexes

Aide-mémoire du menu principal

Aide-mémoire des commandes de l'éditeur

Emplacement des fichiers