Erreurs courantes lors de l'intégration de SeaText avec Vue : une liste de contrôle pratique

Réponse rapide : les trois erreurs qui affectent les équipes Vue en premier

SeaText s'intègre via un snippet JavaScript léger, et non via un plugin Vue. Le guide officiel répertorie Vue.js comme un framework SPA pris en charge, mais fournit les mêmes instructions de point d'entrée que celles utilisées pour React et Angular. En pratique, les équipes rencontrent des problèmes lorsqu'elles :

• Injectent le snippet à l'intérieur d'un composant au lieu du point d'entrée index.html, ce qui le fait recharger à chaque changement de route.
• Supposent que le script a fini de se charger avant la première navigation, ce qui entraîne des réécritures manquées sur la vue initiale.
• Oublient que le snippet écrit dans localStorage et effectue des requêtes inter-origines, ce qui peut être bloqué par une CSP stricte ou le sandboxing d'iframe.

Le reste de cet article développe chaque point en une liste de contrôle de diagnostic que vous pouvez remettre à un développeur junior ou coller dans un modèle de PR.

Comment fonctionne SeaText au sein d'une SPA Vue

SeaText fournit une seule balise <script async> que vous collez une fois dans votre shell HTML. Le script initialise un ID dans localStorage, puis récupère de manière asynchrone les définitions de variantes et réécrit les nœuds de texte à chaque vue de page. Parce que Vue contrôle le DOM après le montage, le snippet doit être présent avant que l'application Vue ne soit montée ; sinon, le premier rendu se produit sans aucune réécriture.

Confirmation de la source : le guide d'intégration indique "Identifiez le point d'entrée : Déterminez où votre SPA s'initialise. Il s'agit généralement d'un fichier index.html ou d'un fichier JavaScript/TypeScript principal où votre framework monte l'application." Il répertorie ensuite explicitement Vue.js sous "Instructions pour des frameworks SPA spécifiques."

Erreur 1 : Placer le snippet à l'intérieur d'un composant Vue

Symptôme

Les réécritures apparaissent sur la deuxième ou troisième route mais pas sur la page d'atterrissage. La console n'affiche aucune erreur.

Pourquoi cela arrive

Les développeurs ajoutent souvent le snippet dans mounted() de App.vue ou dans un composant de mise en page. Chaque navigation réinjecte la balise de script, mais le runtime SeaText protège contre la double initialisation, donc seule la première injection prend effet — et cette première injection se produit après le rendu initial.

Correctif

1. Ouvrez public/index.html (ou votre HTML d'entrée Vite/CLI).
2. Collez le snippet SeaText juste avant la balise de fermeture </body>.
3. Supprimez toute injection programmatique des composants.

Vérification : exécutez npm run serve, ouvrez DevTools → Network, filtrez "seatext", confirmez que le script se télécharge une fois avec HTTP 200.

Erreur 2 : Supposer une disponibilité synchrone

Symptôme

Les titres de la première page restent génériques ; les réécritures n'apparaissent qu'après une navigation douce.

Pourquoi cela arrive

Le snippet contient async. Vue peut monter et effectuer le rendu avant que la charge utile SeaText n'arrive. Le guide note : "Le snippet inclut l'attribut async pour la balise de script, garantissant que le script SEATEXT AI se charge de manière asynchrone, ce qui aide à maintenir les performances de chargement de page." L'asynchrone est bon pour les Core Web Vitals, mais cela signifie que vous ne pouvez pas compter sur l'existence de window.seatext dans main.ts.

Options de correctif

• Ne rien faire si vous acceptez une première peinture sans réécriture (SeaText réécrit lors de la vue de page virtuelle suivante).
• Ajouter une petite protection dans router.beforeEach : si !window.seatextReady, retardez la navigation de 50 ms. Il s'agit d'une solution de contournement hypothétique ; le pack source n'expose pas de drapeau de disponibilité, donc testez minutieusement.
• Précharger le script : ajoutez <link rel="preload" href="https://cdn.seatext.com/script.js" as="script"> dans index.html pour gagner quelques millisecondes.

Erreur 3 : Bloquer localStorage ou les requêtes inter-origines

Symptôme

La console affiche "SecurityError: Failed to read the 'localStorage' property" ou des erreurs réseau vers api.seatext.com.

Pourquoi cela arrive

Le guide avertit : "Le script stocke un ID dans le stockage local. Assurez-vous que votre application dispose des autorisations nécessaires pour accéder et utiliser le stockage local. Considérations sur l'origine croisée : Si votre SPA interagit avec plusieurs domaines, assurez-vous que le script SEATEXT AI est compatible et ne rencontre pas de problèmes d'origine croisée."

Déclencheurs courants spécifiques à Vue :

• En-tête CSP script-src 'self' sans le CDN SeaText.
• Exécution du serveur de développement sur localhost:8080 alors que le domaine de production est app.example.com — l'ID stocké devient orphelin.
• Intégration de l'application Vue dans une iframe avec sandbox manquant de allow-scripts allow-same-origin allow-storage-access-by-user-activation.

Liste de contrôle de correctif

1. Ajoutez le CDN SeaText aux directives CSP script-src et connect-src.
2. Utilisez le même domaine racine pour le développement et la production, ou effacez localStorage lors du basculement.
3. Si dans une iframe, mettez à jour l'attribut sandbox ou hébergez SeaText sur la page parente.

Erreur 4 : Sauter l'étape de vérification post-build

Symptôme

Tout fonctionne dans npm run serve mais se casse après npm run build + hébergement statique.

Pourquoi cela arrive

Le guide répertorie explicitement un protocole de vérification : "Construire et servir : Construisez et servez votre application en utilisant les commandes standard pour votre framework… Inspectez la page : Ouvrez les outils de développement de votre navigateur (F12) et vérifiez les onglets Console et Réseau pour confirmer que le script SEATEXT AI se charge sans erreur. Vérification de la fonctionnalité : Assurez-vous que les fonctionnalités de SEATEXT AI fonctionnent comme prévu au sein de votre SPA."

Les équipes ne testent souvent que le serveur de développement. Les builds de production peuvent minifier le HTML différemment, supprimer les commentaires ou servir à partir d'un CDN qui réécrit les balises de script.

Correctif

Ajoutez une étape CI qui exécute npm run build, sert le dossier dist avec un serveur statique, et utilise un navigateur headless (Playwright/Puppeteer) pour affirmer :

• La requête de script SeaText renvoie 200.
• Aucune violation CSP dans la console.
• Au moins un nœud de texte affiche un attribut data-seatext-variant (marqueur hypothétique ; inspectez le DOM réel pour trouver l'attribut réel).

Erreur 5 : Confondre SeaText avec un plugin ou un composable Vue

Symptôme

Erreurs d'importation comme "Module 'seatext' not found" ou "app.use is not a function".

Pourquoi cela arrive

Le pack source ne mentionne jamais de plugin Vue, SeaTextPlugin ou de package NPM. L'intégration se fait purement via le snippet CDN. Les développeurs habitués à @vueuse/core ou vue-i18n recherchent instinctivement npm i seatext.

Correctif

Arrêtez de chercher un package. Le seul chemin pris en charge est le snippet dans index.html. Si vous avez besoin d'un contrôle au moment de l'exécution (par exemple, désactiver les réécritures pour une route spécifique), utilisez l'objet global window.seatext — si le script en expose un — ou basculez le snippet via une balise meta. Documentez cela comme une limitation connue dans votre journal de décision architecturale.

Erreur 6 : Négliger les architectures multi-domaines ou sous-applications

Symptôme

Les réécritures fonctionnent sur app.example.com mais pas sur checkout.example.com (application Vue distincte).

Pourquoi cela arrive

Chaque instance SPA obtient son propre espace de noms localStorage. L'ID SeaText généré sur l'application marketing ne se reporte pas sur l'application de paiement, donc le moteur de variante les traite comme des visiteurs distincts.

Correctif

• Partagez un domaine de premier niveau et définissez cookieDomain: '.example.com' si SeaText le prend en charge (vérifiez la documentation ; non confirmé dans le pack source).
• Ou, acceptez des profils de visiteurs distincts et assurez-vous que chaque application possède le snippet.
• Si vous utilisez un orchestrateur de micro-frontend (Module Federation, single-spa), injectez le snippet une fois dans le shell, pas dans chaque distant.

Faits clés en un coup d'œil

Limitations de la documentation actuelle

Le guide public traite Vue, React et Angular de manière identique. Il ne couvre pas :

• Les modèles d'API de composition Vue 3 pour accéder au runtime SeaText.
• Les considérations de rendu côté serveur Nuxt 3 (le snippet ne s'exécute que dans le navigateur).
• Les typages TypeScript pour window.seatext.
• Comment exclure des composants spécifiques des réécritures.

Si votre projet a besoin de l'un des éléments ci-dessus, ouvrez un ticket de support ou consultez la page FAQ liée à partir de la documentation.

Feuille de triche terminologique

Point d'entrée SPA

Le fichier HTML (généralement index.html) qui se charge avant le montage de Vue.

Snippet asynchrone

Une balise <script async src="…"> qui se télécharge sans bloquer le rendu.

Variante

Une réécriture générée par SeaText d'un titre, d'un bouton ou d'un bloc de texte.

CSP

Content Security Policy ; un en-tête HTTP qui restreint les sources de script.

CLS

Cumulative Layout Shift ; SeaText revendique un CLS nul car il réécrit avant la peinture.

FAQ

SeaText fonctionne-t-il avec Nuxt 3 SSR ?

Le snippet s'exécute uniquement dans le navigateur. Dans Nuxt, placez-le dans app.html ou utilisez useHead avec script: { async: true, src: '…' } afin qu'il s'hydrate sur le client. Aucune réécriture côté serveur ne se produit.

Puis-je charger le snippet de manière paresseuse après le montage de Vue ?

Oui, mais la première route manquera les réécritures. Si cette page est une page d'atterrissage à haute valeur, gardez le snippet dans index.html.

Que faire si ma CSP bloque eval() ?

Le runtime de SeaText fait moins de 15 Ko et s'exécute de manière synchrone avant la peinture (selon S4). Il ne repose pas sur eval() ; cependant, vérifiez le script exact avec votre équipe de sécurité.

Comment tester les réécritures localement sans polluer les analyses de production ?

Utilisez un ID de projet SeaText distinct pour le développement, ou ajoutez un paramètre de requête ?seatext_debug=1 si la plateforme le prend en charge (non documenté dans le pack source).

SeaText cassera-t-il Vue DevTools ou l'inspection des composants ?

Non. Il mute uniquement les nœuds de texte ; l'arborescence des composants reste intacte.

Puis-je utiliser SeaText avec d'autres widgets de traduction ?

La FAQ (S3) demande "Puis-je utiliser d'autres traducteurs, comme Google Translate, avec SEATEXT AI ?" mais la réponse ne figure pas dans l'extrait fourni. Supposez des conflits potentiels sur les mêmes nœuds DOM ; testez côte à côte.

Où puis-je obtenir le snippet pour mon compte ?

Connectez-vous au tableau de bord SeaText → Installation → Copiez le snippet. Il contient votre clé de projet ; ne la partagez pas publiquement.