better-i18n Doctor : Surveillance Automatisée de la Qualité des Traductions

better-i18n Doctor : Surveillance Automatisée de la Qualité des Traductions

Votre application est disponible en douze langues. Mais comment savoir que chaque écran, chaque message d'erreur, chaque infobulle a bien été traduit ? Comment savoir qu'un placeholder comme {count} en anglais n'a pas été accidentellement écrit {nombre} en français ? Comment savoir que les clés que vous avez supprimées du code il y a trois sprints ne se trouvent plus dans vos fichiers de traduction, ajoutant du désordre et de la confusion ?

La plupart des équipes découvrent les problèmes de traduction grâce aux utilisateurs. Un client à Tokyo voit une clé brute comme dashboard.welcome_message au lieu d'un message d'accueil. Un utilisateur allemand signale qu'un prix affiche {amount} au lieu du nombre réel. Un ingénieur QA compare manuellement des fichiers JSON et découvre que la traduction espagnole manque 47 clés ajoutées le mois dernier.

better-i18n Doctor est un contrôle automatisé de santé i18n qui analyse votre code et vos fichiers de traduction, identifie toutes les catégories de problèmes de traduction et produit un score de santé de 0 à 100. Il s'exécute localement via le CLI, s'intègre dans votre pipeline CI/CD et envoie les résultats à la plateforme better-i18n pour un suivi dans le temps.

Comment fonctionne le score de santé

Doctor produit un seul chiffre : un score de santé de 0 à 100. Ce score est une moyenne pondérée de quatre catégories, chacune évaluant une dimension différente de la qualité i18n.

Les quatre catégories

Coverage mesure si chaque clé utilisée dans votre code existe dans chaque fichier de langues cible. Une clé présente en anglais mais manquante en japonais est une lacune de couverture. La couverture est la source la plus courante de problèmes de traduction — de nouvelles fonctionnalités sont livrées avec des clés qui n'ont jamais été envoyées pour traduction, ou un développeur ajoute une clé à un namespace et oublie de l'ajouter aux autres.

Quality vérifie le contenu des traductions pour leur exactitude structurelle. Les incohérences de placeholders sont le principal problème — si la chaîne anglaise contient {count} et {name}, la traduction allemande doit contenir exactement les mêmes placeholders. Quality vérifie également les traductions vides (clés qui existent mais ont des valeurs vides), les traductions excessivement longues qui peuvent casser les mises en page, et les chaînes identiques à la langue source (ce qui peut indiquer du contenu non traduit copié depuis l'anglais).

Structure évalue l'organisation de vos fichiers de traduction. Elle vérifie les clés orphelines — des clés qui existent dans les fichiers de traduction mais ne sont jamais référencées dans le code source. Les clés orphelines s'accumulent lorsque des fonctionnalités sont supprimées mais que les fichiers de traduction ne sont pas nettoyés. Structure vérifie également la cohérence du nommage des clés, les doublons et l'organisation des namespaces.

Code utilise une analyse AST pour scanner votre code source à la recherche de chaînes codées en dur qui devraient être internationalisées. Il détecte les chaînes orientées utilisateur dans les composants JSX, les template literals passés aux fonctions d'interface et les constantes de chaîne utilisées dans les messages d'erreur ou les notifications. Cette catégorie détecte la source la plus courante de dette i18n : un développeur écrit <p>Loading...</p> au lieu de <p>{t('common.loading')}</p> parce que c'est plus rapide, avec l'intention de corriger plus tard. Doctor trouve ces chaînes avant qu'elles ne soient livrées.

Calcul du score

Chaque catégorie produit un sous-score de 0 à 100 basé sur le ratio de vérifications réussies par rapport au total. Le score de santé global est une moyenne pondérée :

La couverture est pondérée le plus fortement car les traductions manquantes ont l'impact utilisateur le plus direct — elles entraînent l'affichage de clés brutes ou de la langue de secours aux utilisateurs. L'analyse de code est pondérée le moins fortement car les chaînes codées en dur sont une dette technique qui ne casse pas immédiatement l'expérience utilisateur, bien qu'elles doivent être traitées avec le temps.

Seuil de réussite/échec

Un scan est marqué comme réussi lorsque le score global est de 80 ou plus et qu'il n'y a aucune erreur (par opposition aux avertissements). Les erreurs sont des problèmes qui affectent directement les utilisateurs — traductions manquantes pour des fonctionnalités complètes, incohérences de placeholders qui provoquent des erreurs d'exécution, ou clés référençant des namespaces inexistants. Les avertissements sont des problèmes qui devraient être corrigés mais ne cassent pas l'expérience utilisateur — clés orphelines, nommage incohérent ou chaînes codées en dur.

Vous pouvez configurer le seuil de réussite selon les standards de votre équipe :

bi18n doctor --threshold 90

Exécuter Doctor localement

Scan de base

Exécutez un contrôle de santé complet depuis la racine de votre projet :

bi18n doctor

Doctor découvre automatiquement vos fichiers de traduction en se basant sur votre configuration better-i18n.yml ou en détectant les structures de répertoires courantes (locales/, messages/, i18n/, lib/l10n/). Il scanne vos fichiers source pour l'utilisation des clés et effectue des références croisées pour produire le rapport de santé.

La sortie est un rapport structuré montrant le score global, les détails par catégorie et les résultats des règles individuelles :

i18n Doctor Report
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Overall Score: 87/100 ✓ PASSED

Coverage     92/100  ██████████████████░░  3 missing keys
Quality      85/100  █████████████████░░░  2 placeholder mismatches
Structure    78/100  ███████████████░░░░░  12 orphan keys
Code         90/100  ██████████████████░░  4 hardcoded strings

Errors: 0  Warnings: 21
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Scans ciblés

Ignorez les catégories qui ne sont pas pertinentes ou trop lentes pour vos besoins immédiats :

# Ignorer l'analyse de code (scan plus rapide)
bi18n doctor --skip-code

# Ignorer les vérifications de santé/qualité (uniquement couverture et structure)
bi18n doctor --skip-health

# Ignorer les vérifications de statut de sync
bi18n doctor --skip-sync

# Sortie verbose — afficher chaque résultat de règle, pas seulement les échecs
bi18n doctor --verbose

Commandes de vérification individuelles

Doctor regroupe plusieurs vérifications qui peuvent également être exécutées indépendamment :

# Vérifier les clés de traduction manquantes dans toutes les langues
bi18n check:missing

# Vérifier les clés orphelines non référencées dans le code source
bi18n check:unused

# Exécuter toutes les vérifications (équivalent à doctor sans l'analyse de code)
bi18n check

# Scanner le code source pour les chaînes codées en dur
bi18n scan

# Statut de sync — comparer les fichiers locaux avec l'état de la plateforme
bi18n sync --dry-run

Chaque commande produit une sortie ciblée pour son problème spécifique, ce qui est utile lorsque vous travaillez à corriger une catégorie particulière de problèmes.

Intégration CI/CD

GitHub Actions

Doctor est conçu pour s'exécuter comme une vérification CI sur chaque pull request. Le flag --ci produit des résultats dans un format que GitHub Actions comprend, générant des annotations en ligne sur les fichiers contenant des problèmes :

# .github/workflows/i18n-doctor.yml
name: i18n Health Check

on:
  pull_request:
    paths:
      - "locales/**"
      - "src/**"
      - "messages/**"

jobs:
  doctor:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup Bun
        uses: oven-sh/setup-bun@v2

      - name: Install dependencies
        run: bun install

      - name: Run i18n Doctor
        run: bunx @better-i18n/cli doctor --ci --threshold 80
        env:
          BETTER_I18N_API_KEY: ${{ secrets.BETTER_I18N_API_KEY }}

Lorsque le flag --ci est activé, Doctor :

• Quitte avec le code 1 si le scan échoue (score en dessous du seuil ou erreurs présentes), faisant échouer la vérification GitHub Actions
• Produit des annotations au format GitHub Actions, de sorte que les problèmes apparaissent comme des commentaires en ligne sur le diff de la PR
• Génère un résumé qui apparaît dans la sortie de la vérification GitHub Actions

Workflow GitHub Actions généré automatiquement

Si vous ne souhaitez pas écrire le fichier de workflow manuellement, better-i18n peut le créer pour vous. Dans le tableau de bord de la plateforme, naviguez vers Integrations puis GitHub Actions et cliquez sur Create Doctor Workflow. Cela crée une pull request sur votre dépôt avec un fichier de workflow préconfiguré adapté aux paramètres de votre projet.

Le workflow généré automatiquement inclut :

• Des filtres de chemins correspondant à vos emplacements de fichiers de traduction
• Votre seuil configuré
• Des instructions de configuration de clé API
• Une notification Slack optionnelle en cas d'échec

Envoi de rapports à la plateforme

Lorsque Doctor s'exécute avec le flag --report et une clé API, il soumet le rapport complet à la plateforme better-i18n :

bi18n doctor --report --api-key $BETTER_I18N_API_KEY

Le rapport inclut :

• Score et statut réussi/échoué
• Nombre d'erreurs et d'avertissements par catégorie
• Résultats des règles individuelles avec les clés et fichiers affectés
• Métadonnées : SHA du commit, nom de la branche, nombre de fichiers scannés, nombre de clés vérifiées, horodatage

Les rapports soumis à la plateforme sont stockés et affichés dans le tableau de bord du projet. Vous pouvez consulter les tendances de score dans le temps, comparer des rapports entre branches et suivre quelles catégories s'améliorent ou se dégradent.

Soumission de rapports CI

Dans les environnements CI, combinez --ci et --report pour valider la PR et soumettre le rapport :

- name: Run i18n Doctor
  run: bunx @better-i18n/cli doctor --ci --report --threshold 85
  env:
    BETTER_I18N_API_KEY: ${{ secrets.BETTER_I18N_API_KEY }}

Cela vous donne deux boucles de retour :

1. Immédiat : La vérification de PR réussit ou échoue, et les développeurs voient les annotations en ligne
2. Historique : Le rapport est stocké sur la plateforme pour l'analyse des tendances et la visibilité de l'équipe

Détails des règles

Doctor évalue un ensemble de règles dans chaque catégorie. Voici les règles les plus impactantes et ce qu'elles détectent.

Règles de Coverage

missing-keys : Pour chaque clé utilisée dans votre code source, vérifie si une traduction existe dans chaque fichier de langues cible. Les clés manquantes sont le problème i18n le plus courant et le plus visible pour l'utilisateur — elles entraînent l'affichage de noms de clés bruts ou de la langue de secours.

namespace-coverage : Vérifie que chaque namespace référencé dans votre code a des fichiers de traduction correspondants pour toutes les langues cibles. Un développeur peut ajouter t('checkout.confirm_order') mais le fichier namespace checkout n'existe pas pour le coréen.

Règles de Quality

placeholder-mismatch : Compare les placeholders entre les traductions source et cible. Si en: "Hello {name}, you have {count} items" existe, vérifie que la traduction de chaque autre langue contient exactement {name} et {count}. Des placeholders supplémentaires ou manquants provoquent des erreurs d'exécution ou affichent la syntaxe brute des placeholders.

empty-translation : Signale les clés qui existent dans une langue cible mais ont des valeurs vides. Les traductions vides résultent souvent de l'ajout de clés par programmation sans fournir de contenu traduit réel.

source-identical : Signale les traductions qui sont caractère pour caractère identiques à la langue source. Bien que certaines chaînes (noms de marques, URLs, termes techniques) soient légitimement identiques entre les langues, un grand nombre de chaînes identiques à la source indique généralement du contenu non traduit.

Règles de Structure

orphan-keys : Identifie les clés dans les fichiers de traduction qui ne sont référencées nulle part dans le code source. Les clés orphelines s'accumulent lorsque des fonctionnalités sont supprimées mais que les fichiers de traduction ne sont pas nettoyés. Elles gaspillent l'effort des traducteurs et créent de la confusion sur ce qui est activement utilisé.

duplicate-keys : Détecte la même clé définie plusieurs fois dans un seul fichier ou namespace. Les doublons provoquent un comportement imprévisible — le moteur de traduction utilise l'une d'elles, mais laquelle dépend des détails d'implémentation.

naming-consistency : Vérifie que les noms de clés suivent des patterns cohérents. Si la plupart des clés utilisent snake_case, une clé utilisant camelCase est signalée. Un nommage incohérent rend les clés plus difficiles à trouver et à maintenir.

Règles de Code

hardcoded-jsx : Utilise l'analyse AST pour détecter les littéraux de chaîne dans les éléments JSX. <h1>Welcome</h1> est signalé ; <h1>{t('welcome')}</h1> ne l'est pas. Cette règle comprend JSX et ignore les chaînes non orientées utilisateur comme les noms de classes CSS et les attributs de données.

hardcoded-template : Détecte les littéraux de chaîne passés aux fonctions qui produisent typiquement une sortie orientée utilisateur — notifications toast, boîtes de dialogue d'alerte, messages d'erreur. showToast("Operation successful") est signalé.

hardcoded-constant : Identifie les constantes de chaîne assignées à des variables avec des noms orientés utilisateur (comme errorMessage, label, title, placeholder) qui ne sont pas encapsulées dans des fonctions de traduction.

Tableau de bord de la plateforme

Les rapports soumis via --report sont visualisés dans le tableau de bord de la plateforme better-i18n.

Tendances de score

Un graphique de série temporelle montre votre score de santé dans le temps. Chaque point représente un rapport Doctor, tracé par date. Vous pouvez filtrer par branche pour voir la trajectoire de santé de main par rapport aux branches de fonctionnalités. La ligne de tendance facilite la visualisation de l'amélioration, de la stabilité ou de la dégradation de votre qualité i18n.

Détail par catégorie

Plongez dans chaque catégorie pour voir quelles règles réussissent et lesquelles échouent. Pour chaque règle en échec, vous pouvez voir les clés et fichiers spécifiques concernés. Cliquez sur une clé pour l'ouvrir dans l'éditeur de traduction ; cliquez sur un fichier pour le voir dans le contexte de votre dépôt.

Comparaison entre projets

Pour les organisations avec plusieurs projets, le tableau de bord affiche les scores de santé de tous les projets. C'est utile pour identifier quels projets nécessitent une attention i18n et pour définir des standards de qualité à l'échelle de l'organisation.

Alertes

Configurez des alertes pour être notifié lorsque votre score de santé tombe en dessous d'un seuil :

• Email : Digest hebdomadaire des changements de score de santé
• Slack : Notification instantanée lorsqu'un rapport échoue
• Webhook : Intégration personnalisée pour votre stack de surveillance

Exemples pratiques

Exemple 1 : Détecter les traductions manquantes avant une release

Votre équipe a ajouté un nouveau flux de paiement avec 30 nouvelles clés de traduction. Le développeur a ajouté toutes les clés dans le fichier anglais. Les traductions françaises et allemandes ont été demandées mais pas encore complétées. Sans Doctor, ces clés brutes seraient visibles par les utilisateurs français et allemands.

Avec Doctor dans CI :

Coverage     60/100  ████████████░░░░░░░░  30 missing keys (fr, de)

Error: 30 keys missing in target languages
  checkout.confirm_order — missing in: fr, de
  checkout.payment_method — missing in: fr, de
  checkout.shipping_address — missing in: fr, de
  ... (27 more)

Result: FAILED (score 60, threshold 80)

La PR est bloquée. Le développeur voit les annotations en ligne, demande les traductions, et la PR n'est fusionnée qu'une fois les traductions complètes.

Exemple 2 : Détecter les incohérences de placeholders

Un traducteur met à jour la traduction allemande d'une chaîne de notification. La source anglaise contient You have {count} new messages from {sender}. La traduction allemande utilise accidentellement {anzahl} au lieu de {count}.

Doctor le détecte :

Quality      75/100  ███████████████░░░░░  1 placeholder mismatch

Error: Placeholder mismatch in notifications.new_messages (de)
  Source placeholders: {count}, {sender}
  Target placeholders: {anzahl}, {sender}
  Missing: {count}
  Extra: {anzahl}

Exemple 3 : Nettoyer après la suppression d'une fonctionnalité

Votre équipe a supprimé le tableau de bord legacy il y a six mois. Le code est parti, mais les fichiers de traduction contiennent encore 85 clés sous le namespace legacy_dashboard. Les traducteurs mettent parfois à jour ces chaînes lors de passes de traduction en masse, gaspillant des efforts sur du contenu que personne ne voit.

Doctor trouve les clés orphelines :

Structure    65/100  █████████████░░░░░░░  85 orphan keys

Warning: 85 keys in namespace "legacy_dashboard" are not referenced in source code
  legacy_dashboard.welcome — not referenced
  legacy_dashboard.stats_header — not referenced
  legacy_dashboard.chart_title — not referenced
  ... (82 more)

Exemple 4 : Trouver les chaînes codées en dur

Un nouveau développeur rejoint l'équipe et écrit une fonctionnalité sans utiliser le système de traduction. Il code en dur toutes les chaînes directement dans JSX :

// Avant Doctor
<div>
  <h2>Account Settings</h2>
  <p>Manage your account preferences below.</p>
  <button>Save Changes</button>
</div>

Doctor signale chaque chaîne codée en dur :

Code         40/100  ████████░░░░░░░░░░░░  3 hardcoded strings

Warning: Hardcoded string in JSX element (src/pages/Settings.tsx:15)
  <h2>Account Settings</h2>
  Suggestion: <h2>{t('settings.account_title')}</h2>

Warning: Hardcoded string in JSX element (src/pages/Settings.tsx:16)
  <p>Manage your account preferences below.</p>

Warning: Hardcoded string in JSX element (src/pages/Settings.tsx:17)
  <button>Save Changes</button>

Comparaison avec les alternatives

Diff JSON manuel : Les équipes qui comparent manuellement les fichiers de traduction détectent les problèmes de couverture mais ratent tout le reste — incohérences de placeholders, clés orphelines, chaînes codées en dur. Les vérifications manuelles sont également sujettes aux erreurs et ne passent pas à l'échelle au-delà d'une poignée de langues.

Plugins ESLint i18n : Les règles de linting comme eslint-plugin-i18next détectent les chaînes codées en dur dans JSX mais ne vérifient pas la qualité des fichiers de traduction, la couverture dans les langues, ou les problèmes structurels. Doctor inclut l'analyse de code comme l'une des quatre catégories et couvre le spectre complet des problèmes i18n.

Phrase QPS (Quality Performance Score) : Phrase fournit un score de qualité de traduction, mais il se concentre sur la qualité linguistique (grammaire, terminologie) plutôt que sur la qualité technique (clés manquantes, incohérences de placeholders, clés orphelines). Doctor se concentre sur la dimension technique — les problèmes qui causent des erreurs d'exécution et des interfaces cassées.

Aucune vérification automatisée : De nombreuses équipes n'ont aucune vérification i18n automatisée. Les problèmes sont découverts par les utilisateurs ou les ingénieurs QA. Doctor fournit une couverture automatisée complète qui détecte les problèmes avant qu'ils n'atteignent tout environnement.

Foire aux questions

Combien de temps dure un scan Doctor ? Un scan typique d'un projet avec 10 000 clés, 8 langues et 200 fichiers source se termine en moins de 10 secondes. L'analyse de code (parsing AST) est la catégorie la plus lente — utilisez --skip-code pour des scans plus rapides lorsque vous n'avez besoin que de vérifications de couverture et de qualité.

Puis-je exécuter Doctor sans me connecter à la plateforme better-i18n ? Oui. Doctor s'exécute entièrement en local par défaut. Le flag --report est optionnel et n'est nécessaire que si vous souhaitez soumettre des résultats à la plateforme pour le suivi des tendances.

Quels frameworks l'analyse de code supporte-t-elle ? L'analyse de code supporte actuellement React (JSX/TSX), Vue (templates SFC) et les composants Svelte. Le support Angular est prévu. La détection du framework est automatique en fonction des dépendances de votre projet.

Puis-je ajouter des règles personnalisées ? Les règles personnalisées sont sur la feuille de route. Actuellement, vous pouvez configurer la sévérité des règles (erreur vs. avertissement) et désactiver des règles spécifiques qui ne sont pas pertinentes pour votre projet.

Doctor fonctionne-t-il avec les monorepos ? Oui. Doctor supporte le scan tenant compte des workspaces. Il détecte les limites des workspaces et scanne chaque package indépendamment, produisant un rapport par package et un score global agrégé.

Comment fonctionne la création du workflow GitHub Actions ? Dans le tableau de bord better-i18n, l'action Create Doctor Workflow utilise l'API GitHub pour créer une pull request sur votre dépôt avec un fichier .github/workflows/i18n-doctor.yml préconfiguré. Vous révisez et fusionnez la PR pour activer le workflow.

Commencez à surveiller votre santé i18n

Les problèmes de traduction doivent être détectés dans CI, pas par les utilisateurs. better-i18n Doctor offre à votre équipe un contrôle de santé continu et automatisé qui évalue chaque dimension de votre qualité i18n et bloque les traductions défectueuses avant qu'elles ne soient livrées.

Commencez votre essai gratuit et exécutez votre premier scan Doctor en moins de cinq minutes.