Comment ça fonctionne

@lingo.dev/compiler transforme votre application React en une application multilingue au moment de la compilation grâce à une analyse intelligente du code et à la traduction assistée par IA.

Transformation au moment de la compilation

Les bibliothèques i18n traditionnelles (i18next, react-intl) fonctionnent à l'exécution : elles chargent les traductions, interpolent les valeurs et formatent les messages pendant que votre application s'exécute. Cela ajoute de la taille au bundle, une surcharge à l'exécution et de la complexité.

@lingo.dev/compiler fonctionne différemment : il transforme votre code pendant le processus de compilation. Vos composants React restent propres et les traductions sont pré-compilées dans des bundles optimisés.

Résultat : Aucune surcharge à l'exécution, des bundles plus petits et aucune gestion manuelle des clés de traduction.

Le processus

1. Analyse AST

Le compilateur utilise Babel pour analyser votre code React en un arbre de syntaxe abstraite (AST). Il parcourt votre JSX en identifiant le contenu traduisible :

  • Nœuds de texte (<p>Hello</p>)
  • Attributs de chaîne (<img alt="Logo" />)
  • Texte dans les expressions de template (<p>Hello {name}</p>)

Le compilateur comprend les limites des composants React et maintient les informations contextuelles pour des traductions précises. Les identifiants techniques, les extraits de code et les éléments non traduisibles sont automatiquement filtrés.

2. Extraction du contenu

Pour chaque chaîne traduisible, le compilateur :

  • Génère un identifiant stable basé sur un hash
  • Préserve le contexte du composant (fichier, emplacement, éléments environnants)
  • Extrait la structure de texte enrichi (gère les éléments imbriqués comme <strong> et <em>)
  • Maintient les espaces réservés d'interpolation

Ces métadonnées sont stockées dans .lingo/metadata.json — un fichier versionné qui suit tout le contenu traduisible de votre application.

3. Génération de traduction

Pendant le développement, le serveur de traduction gère la traduction à la demande :

  • Mode pseudotraducteur (par défaut) : génère instantanément de fausses traductions — utile pour voir ce qui est traduit sans frais d'API
  • Mode traduction réelle : appelle votre fournisseur LLM configuré (moteur Lingo.dev ou LLM direct)

Le service de traduction est sans état et gère les échecs partiels avec élégance : si certaines traductions échouent, les traductions en cache sont toujours utilisées.

4. Injection de code

Le compilateur injecte des recherches de traduction dans votre JSX :

// Your source code
<p>Hello {name}</p>

// Transformed code (simplified)
<p>{t('abc123', { name })}</p>

La fonction t() est optimisée et injectée automatiquement. Elle effectue des recherches basées sur le hachage dans des dictionnaires de traduction préchargés.

5. Optimisation du bundle

Au moment de la compilation :

  • Des bundles par locale sont créés
  • Seules les traductions utilisées sont incluses
  • L'élimination du code mort supprime les traductions inutilisées
  • Les dictionnaires sont tree-shaken par composant

Workflow de développement

Mode développement

{
  dev: {
    usePseudotranslator: true,
  }
}

Lorsque vous exécutez npm run dev :

  1. Le compilateur démarre un serveur de traduction (trouve automatiquement les ports 60000-60099)
  2. Votre application envoie des requêtes au serveur pour les traductions
  3. Le pseudotranslator génère instantanément de fausses traductions
  4. Les traductions sont mises en cache dans .lingo/metadata.json
  5. Le HMR fonctionne normalement : l'état est préservé

Le widget de développement (s'il est activé) vous permet de modifier les traductions dans le navigateur et de voir les changements en temps réel.

Mode production

{
  buildMode: "cache-only",
}

Lorsque vous exécutez npm run build :

  1. Aucun serveur de traduction ne démarre
  2. Seules les traductions en cache de .lingo/metadata.json sont utilisées
  3. Si des traductions sont manquantes, la compilation échoue avec un message d'erreur clair
  4. Aucun appel API n'est effectué : aucune clé API n'est nécessaire

Pourquoi uniquement le cache ? En production, vous voulez des compilations déterministes. Les traductions doivent être générées en CI (où vous avez les clés API), pas pendant les compilations de production.

Workflow recommandé

Développement local :

  • Utilisez le pseudotranslator
  • Boucle de feedback rapide
  • Aucun coût d'API

CI/CD :

{
  buildMode: "translate",
  dev: {
    usePseudotranslator: false,
  }
}
  • Générez de vraies traductions
  • Exécutez une fois par déploiement
  • Commitez les modifications de .lingo/

Build de production :

{
  buildMode: "cache-only",
}
  • Utilise des traductions pré-générées
  • Aucune clé API requise
  • Builds rapides et déterministes

Architecture

Le compilateur est organisé autour d'une séparation claire des responsabilités :

Gestionnaire de métadonnées

  • Opérations CRUD pour .lingo/metadata.json
  • Thread-safe avec verrouillage de fichiers
  • Identifiants basés sur des hash pour les traductions

Service de traduction

  • Orchestre le workflow de traduction
  • Gère la stratégie de cache
  • Gère les échecs partiels
  • Retourne à la fois les traductions réussies et les erreurs

Traducteurs (sans état)

  • Pseudotraducteur : traductions factices instantanées
  • Traducteur LCP : intégration du moteur Lingo.dev
  • Traducteurs LLM : intégration directe des fournisseurs
  • Pas de cache intégré — la couche service gère cela

Serveur de traduction

  • Serveur HTTP pour le développement
  • Support WebSocket pour les mises à jour en temps réel du widget
  • Gestion automatique des ports
  • Traitement des requêtes par lots

Consultez la documentation de l'architecture du code source pour les détails d'implémentation.

Intégration de framework

Next.js

Le compilateur s'intègre via le wrapper withLingo() :

  • Supporte à la fois Webpack et Turbopack
  • Fonctionne avec les React Server Components
  • Configuration asynchrone pour le chargement paresseux des plugins
  • Routage automatique basé sur les locales (si configuré)

Vite

Le compilateur s'intègre via lingoCompilerPlugin :

  • Basé sur Unplugin (fonctionne avec Vite, Webpack, Rollup)
  • Support HMR complet
  • Intégration efficace du serveur de développement
  • Génération automatique de modules virtuels

Questions fréquentes

Est-ce que cela fonctionne avec les Server Components ? Oui. Dans Next.js, le compilateur transforme à la fois les Server et Client Components. Les recherches de traductions fonctionnent de manière isomorphe.

Qu'en est-il du code splitting ? Les traductions sont automatiquement divisées avec vos composants. Chaque chunk inclut uniquement les traductions dont il a besoin.

Comment les traductions sont-elles mises en cache ? Toutes les traductions sont stockées dans .lingo/metadata.json. Ce fichier est versionné et agit comme votre cache de traductions. Le compilateur utilise des hash de contenu — seul le texte nouveau ou modifié déclenche une re-traduction.

Que se passe-t-il si une traduction échoue ? Le service renvoie des résultats partiels. Les traductions réussies sont mises en cache et utilisées, tandis que les erreurs sont enregistrées avec le contexte pour le débogage. Votre application ne plante pas — elle revient aux traductions en cache ou au texte source.

Puis-je voir le code transformé ? Oui. Dans la sortie de votre build, recherchez les fichiers transformés. Les transformations sont minimales — juste des appels de fonction t() avec des recherches basées sur le hachage.

Prochaines étapes