Context Crawler : comprenez votre marque et votre code pour des traductions IA précises avec better-i18n

Comment better-i18n construit le contexte IA à partir de votre produit

La plupart des workflows de localisation commencent par une étape manuelle : quelqu'un tague les chaînes, exporte les fichiers, et espère que rien n'a été oublié. better-i18n adopte une approche différente. Le Context Crawler combine deux puissants modes d'analyse — le crawl de site web et le scan de dépôt — pour construire automatiquement un contexte riche qui rend les traductions IA considérablement plus précises.

Le résultat est un workflow où votre traducteur IA comprend votre marque, votre vocabulaire produit et votre stack technique avant de traduire la moindre chaîne.

Analyse de site web : découverte de marque propulsée par Firecrawl

Le mode d'analyse de site web du Context Crawler utilise l'API Firecrawl pour crawler et extraire systématiquement le contenu de toute URL que vous fournissez. Ce n'est pas un simple scraping HTML — Firecrawl gère les pages rendues en JavaScript, les SPAs et le contenu dynamique pour capturer ce que les utilisateurs voient réellement.

Comment fonctionne l'analyse de site web

1. Fournissez une URL — Entrez le site marketing de votre produit, sa documentation ou toute propriété web. Le crawler accepte toute URL accessible publiquement.
2. Extraction Firecrawl — L'API Firecrawl rend les pages, suit les liens internes et extrait le contenu structuré incluant les titres, le corps de texte, les libellés de navigation, les CTAs et les métadonnées.
3. Détection de terminologie — L'analyse IA identifie les termes répétés, le langage de marque, les noms de produit, les noms de fonctionnalité et le vocabulaire spécifique au domaine sur toutes les pages crawlées.
4. Proposition de candidats — Les termes détectés sont proposés comme candidats au glossaire avec des définitions suggérées, des notes de contexte et des données de fréquence. Chaque candidat inclut les URLs sources où il a été trouvé.

Ce que capture l'analyse de site web

• Terminologie de marque — Noms de produit, noms de fonctionnalité, libellés de niveaux de tarification et termes propres qui apparaissent de manière cohérente sur votre site
• Patterns de navigation — Libellés de menu, texte de fil d'Ariane et langage de CTA qui définissent le vocabulaire de votre produit
• Vocabulaire du domaine — Termes spécifiques à l'industrie utilisés par votre produit qui nécessitent une traduction précise et cohérente
• Signaux de ton et de voix — Si votre contenu est formel, décontracté, technique ou orienté marketing — un contexte qui aide l'IA à traduire avec le registre approprié

Cas d'usage de l'analyse de site web

• Mise en place d'un nouveau projet — Crawlez votre site marketing avant de démarrer la localisation pour bootstrapper un glossaire et un profil de contexte en quelques minutes plutôt qu'en quelques semaines
• Analyse concurrentielle — Crawlez les sites de concurrents sur les marchés cibles pour comprendre comment ils traduisent des concepts similaires, ce qui éclaire vos propres décisions de glossaire
• Audit de contenu — Recrawlez périodiquement pour détecter la nouvelle terminologie apparue depuis votre dernière mise à jour du glossaire

Analyse de dépôt : détection de framework et de terminologie

Le mode d'analyse de dépôt du Context Crawler se connecte à votre dépôt GitHub et effectue une analyse approfondie de votre codebase pour extraire le contexte pertinent pour la traduction.

Comment fonctionne l'analyse de dépôt

1. Connectez un dépôt GitHub — Fournissez l'URL du dépôt. Le crawler accède aux dépôts publics directement et aux dépôts privés via votre intégration GitHub.
2. Détection de framework — L'analyseur identifie votre stack technique : React, Next.js, Vue, Angular, Svelte, Flutter, React Native et autres. Cela détermine quels patterns i18n rechercher et comment parser votre code.
3. Reconnaissance des patterns i18n — Sur la base du framework détecté, l'analyseur trouve les appels de fonctions de traduction existants (t(), useTranslations(), $t(), tr(), etc.) et cartographie la façon dont votre projet structure ses traductions.
4. Extraction de terminologie — L'analyseur identifie les chaînes codées en dur, les noms de composants, les libellés de routes et autre texte visible par les utilisateurs qui représente le vocabulaire de votre produit.
5. Génération de profil de contexte — Toutes les découvertes sont compilées dans un profil de contexte qui inclut les frameworks détectés, l'utilisation de la bibliothèque i18n, la structure des namespaces et les candidats terminologiques.

Ce que détecte l'analyse de dépôt

• Framework et bibliothèque i18n — Détection automatique de votre stack pour que les traductions IA utilisent les bonnes conventions de formatage (ICU MessageFormat, interpolation i18next, Flutter ARB, etc.)
• Structure des namespaces — Comment votre projet organise les clés de traduction, afin que les nouvelles traductions suivent les mêmes patterns
• Terminologie existante — Termes déjà utilisés dans votre codebase, aidant à identifier ce qui doit être ajouté au glossaire
• Patterns de chaînes — Patterns courants dans vos chaînes visibles par les utilisateurs (formats de date, formats de nombre, approches de pluralisation) qui informent les règles de traduction

Détection de clés basée sur l'AST

Au-delà de la construction du contexte, la commande scan du CLI parse votre code source au niveau de l'arbre syntaxique, sans recourir à une correspondance regex fragile. Elle comprend nativement les patterns React JSX, useTranslations et getTranslations. Cela signifie qu'elle peut distinguer une chaîne visible par l'utilisateur comme <h1>Welcome back</h1> d'une chaîne technique comme className="flex items-center" sans faux positifs.

Ce qu'elle détecte :

• Texte JSX codé en dur — contenu comme <h1>Hello</h1> qui devrait être enveloppé dans des appels t()
• Attributs JSX codés en dur — attributs visibles par les utilisateurs comme <img alt="Company logo" />
• Chaînes de toast et de notification — appels comme toast.error("Something went wrong")
• Logique ternaire basée sur la locale — patterns comme locale === 'en' ? 'Hi' : 'Hola' qui indiquent une gestion manuelle de la locale
• Variables de chaînes — variables contenant du texte qui semble être visible par les utilisateurs

Ce qu'elle ignore intelligemment :

• Les noms de classes Tailwind et CSS
• Les URLs, chemins de fichiers et sources d'images
• Les entités HTML (&, ")
• Les constantes techniques en SCREAMING_CASE
• Les nombres et valeurs non textuelles

better-i18n scan              # Scanner le répertoire courant
better-i18n scan --dir ./src  # Scanner un répertoire spécifique
better-i18n scan --staged     # Uniquement les fichiers stagés (pour les hooks pre-commit)
better-i18n scan --ci         # Code de sortie 1 si des problèmes sont trouvés
better-i18n scan --format json # Sortie JSON pour les outils
better-i18n scan --verbose    # Sortie détaillée avec audit du scan

Résolution des namespaces

Le scanner utilise le suivi de la portée lexicale pour résoudre automatiquement les namespaces pour les composants client et serveur. C'est important car cela signifie que les clés détectées incluent leur chemin de namespace complet, pas seulement le nom de la clé.

Pour les composants client utilisant des hooks :

const t = useTranslations('hero');
return <h1>{t('title')}</h1>; // Détecté comme : hero.title

Pour les composants serveur utilisant des fonctions async :

const t = await getTranslations('welcome');
return <h1>{t('title')}</h1>; // Détecté comme : welcome.title

Le scanner gère également la forme objet (getTranslations({ locale, namespace: 'settings' })) et les traducteurs à portée racine où aucun namespace n'est fourni. Les namespaces dynamiques utilisant des variables ou des template literals sont signalés en mode --verbose et exclus des métriques pour éviter les faux positifs.

De l'analyse au glossaire : le pipeline complet

Les modes d'analyse de site web et de dépôt du Context Crawler alimentent directement le système de Gestion du glossaire :

1. Crawl — L'analyse de site web via Firecrawl extrait la terminologie de marque ; l'analyse de dépôt détecte le contexte du framework et les termes existants.
2. Proposition — Les termes détectés sont proposés comme candidats au glossaire avec le statut brouillon.
3. Révision — Votre équipe révise les termes proposés, en modifiant les définitions et les traductions selon les besoins.
4. Approbation — Les termes approuvés sont immédiatement appliqués dans la traduction IA et l'éditeur de révision.
5. Synchronisation — Les termes approuvés peuvent être synchronisés avec DeepL pour une application au niveau du fournisseur.

Ce pipeline signifie que vous pouvez passer de « nous n'avons pas de glossaire » à « nos traductions IA appliquent 200 termes de marque » en une seule après-midi.

Sync : comparer le local et le cloud

La commande sync comble l'écart entre ce que votre code utilise et ce qui existe dans better-i18n. Elle scanne votre codebase de la même façon que scan, puis interroge l'API better-i18n pour comparer les ensembles de clés.

La sortie est un rapport de comparaison clair :

• Manquant dans Remote — clés référencées dans votre code mais pas encore uploadées dans better-i18n. Ce sont des chaînes que vos utilisateurs pourraient voir non traduites.
• Inutilisé dans le code — clés qui existent dans better-i18n mais qui ne sont plus référencées nulle part dans votre source. Ce sont des candidates au nettoyage.

better-i18n sync              # Sortie en arbre groupé
better-i18n sync --summary    # Métriques de couverture de haut niveau uniquement
better-i18n sync --format json # Sortie JSON pour l'automatisation CI
better-i18n sync -d ./src     # Scanner un répertoire spécifique

La sortie en arbre groupe les clés par namespace, ce qui facilite la visualisation des parties de votre application qui ont des lacunes. Le flag --verbose fournit un journal d'audit approfondi incluant les vérifications d'invariants, les résumés de portée et les sondes de clés spécifiques.

Métriques de couverture

La commande sync fournit des métriques de couverture en pourcentage :

• Couverture Local vers Remote : Quel pourcentage de clés utilisées dans votre code existe dans better-i18n
• Utilisation Remote : Quel pourcentage de clés dans better-i18n est réellement utilisé dans votre code

Ces chiffres donnent à votre équipe une image claire de l'état des traductions à tout moment. Vous pouvez les consulter dans la sortie terminal ou les extraire de la sortie JSON pour des tableaux de bord et des rapports personnalisés.

Intégration CI

Les commandes scan et sync sont conçues pour s'exécuter dans des pipelines automatisés. Utilisez --ci avec scan pour faire échouer les builds lorsque des chaînes codées en dur sont détectées, et piped la sortie sync à travers jq pour conditionner les déploiements au nombre de clés manquantes.

# Exemple GitHub Actions
name: i18n Check
on: [push, pull_request]
jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npx @better-i18n/cli scan --ci
      - run: |
          npx @better-i18n/cli sync --format json \
            | jq -e '.comparison.missingCount == 0' > /dev/null || exit 1

Pour les hooks pre-commit, scannez uniquement les fichiers stagés pour garder le feedback rapide :

npx husky init
echo "npx @better-i18n/cli scan --staged --ci" > .husky/pre-commit

Ce que cela ne fait pas

Pour définir des attentes claires :

• Pas de capture de contexte visuel — le CLI fonctionne au niveau du code, pas de l'interface rendue. Il n'y a pas de captures d'écran ni d'aperçus visuels de l'endroit où les chaînes apparaissent.
• Pas de surveillance en temps réel — scan et sync sont exécutés à la demande ou dans des pipelines CI ; ce ne sont pas des observateurs de fond ou des observateurs du système de fichiers
• Pas de détection de traduction périmée — la commande sync montre les clés manquantes et inutilisées, mais ne détecte pas si une traduction existante est obsolète par rapport à un changement de texte source

Démarrer

Installez le CLI et lancez votre premier scan en moins d'une minute :

npm install -g @better-i18n/cli
better-i18n scan --dir ./src

Ensuite, connectez-vous à votre projet better-i18n et comparez avec le cloud :

better-i18n sync

Pour démarrer l'analyse de site web, visitez la section Contexte IA dans le tableau de bord de votre projet, entrez une URL et laissez Firecrawl extraire la terminologie de votre marque. Pour l'analyse de dépôt, connectez votre dépôt GitHub et laissez l'analyseur détecter votre framework et la terminologie existante.

Consultez la documentation complète du CLI pour les options de configuration, les règles de détection et l'utilisation avancée.

Prêt à automatiser votre contexte de traduction et la découverte de terminologie ? Créez votre compte et connectez votre premier projet — ou découvrez comment le système de Gestion du glossaire applique les termes découverts par le crawler.