Comment déboguer les problèmes d'attributs de données avec SeaText : un guide de diagnostic étape par étape

Comprendre les attributs de données SeaText

SeaText utilise des attributs HTML data-* pour marquer les éléments que ses agents IA doivent traduire, optimiser ou personnaliser. Ces attributs servent de points d'accroche : le script SeaText analyse le DOM, trouve les éléments avec l'attribut attendu et applique les modifications en temps réel. Si l'attribut est manquant, mal orthographié ou contient une valeur vide, l'agent ignore cet élément silencieusement.

L'attribut le plus courant que vous rencontrerez est data-seatext (ou une variante documentée dans votre guide d'intégration). Dans les implémentations Shopify, les instructions d'intégration vous disent explicitement d'envelopper la sortie de description de produit avec cet attribut, puis de vérifier qu'il apparaît dans le HTML rendu à l'aide des outils de développement du navigateur.

Symptômes courants des problèmes d'attributs de données

• Les traductions ou optimisations n'apparaissent pas sur des pages ou éléments spécifiques.
• Certaines langues fonctionnent tandis que d'autres reviennent au texte original.
• Le tableau de bord SeaText affiche « aucun élément trouvé » ou un faible nombre d'éléments pour une page que vous savez devoir être traitée.
• Les modifications clignotent brièvement puis reviennent, suggérant un conflit de script ou un re-rendu.

Ces symptômes pointent généralement vers l'une des trois causes racines : l'attribut n'est pas dans le HTML final, le nom ou la valeur de l'attribut ne correspond pas à ce que le script attend, ou le script SeaText ne s'exécute pas sur cette page.

Séquence de diagnostic : étape par étape

1. Ouvrez les DevTools et inspectez l'élément cible. Faites un clic droit sur l'élément (description de produit, titre, CTA) et choisissez Inspecter. Recherchez data-seatext ou le nom d'attribut de vos documents d'intégration dans le panneau Éléments.
2. Vérifiez le nom et la valeur de l'attribut. Le nom doit correspondre exactement (sensible à la casse). La valeur doit être une chaîne non vide — souvent un identifiant de portée comme « product-description » ou un code de langue. Un data-seatext="" vide sera ignoré.
3. Vérifiez la console pour les erreurs SeaText. Filtrez par « seatext » ou recherchez les requêtes réseau vers seatext.com. Un 401 ou 403 lors du chargement du script signifie une inadéquation de compte/domaine. Une erreur JavaScript dans le bundle SeaText arrête tout traitement.
4. Confirmez que le script SeaText se charge sur la page. Dans l'onglet Réseau, rechargez et trouvez le fichier JS SeaText. Il doit retourner 200 OK. S'il est manquant, l'extrait n'a pas été ajouté à theme.liquid (Shopify) ou au fichier de mise en page équivalent sur d'autres plateformes.
5. Examinez les journaux du tableau de bord SeaText. Connectez-vous à votre compte SeaText et ouvrez le journal d'activité ou d'erreurs du domaine. Il enregistre les éléments détectés, les appels API et les rejets côté serveur.
6. Testez avec une page minimale. Créez un fichier HTML statique avec uniquement l'extrait SeaText et un seul <div data-seatext="test">Hello</div>. Si cela fonctionne là mais pas sur votre page en direct, le problème est dans votre thème ou pipeline de build.

Causes probables et leurs correctifs

Attribut supprimé par le thème ou le framework

Certains thèmes Shopify ou processus de build React/Vue suppriment les attributs inconnus lors du rendu. Dans Shopify, le guide d'intégration montre comment envelopper la sortie de description de produit dans product.liquid ou product-template.liquid. Si vous avez placé l'attribut dans un extrait qui est compilé et supprimé, il n'atteindra pas le navigateur. Correctif : ajoutez l'attribut directement dans le fichier liquid qui produit le HTML final, puis vérifiez avec Afficher la source (pas seulement le panneau Éléments des DevTools, qui montre le DOM post-JS).

Faute de frappe dans le nom de l'attribut

data-seatext vs data-sea-text vs data-seatext-scope — seul le nom exact documenté pour votre intégration fonctionne. Correctif : copiez le nom de l'attribut depuis la documentation officielle (documentation-ai-scope) et collez-le dans votre modèle.

Script non chargé ou chargé deux fois

L'intégration SeaText nécessite de coller un extrait JavaScript dans theme.liquid (Shopify) ou la mise en page globale sur d'autres plateformes. Si vous l'avez collé dans un bloc conditionnel qui ne s'affiche pas sur toutes les pages, ou si deux extraits existent (ancien + nouveau), le script ne s'exécutera pas ou entrera en conflit. Correctif : assurez-vous qu'un seul extrait, placé juste avant </head> ou </body>, est présent sur chaque page.

Inadéquation domaine/compte

Chaque compte SeaText est lié à une seule URL principale. Les URL de développement comme localhost ou les domaines de prévisualisation dynamiques sont restreints. Si vous testez sur un sous-domaine de staging qui n'est pas enregistré sur votre compte, le script se charge mais le backend rejette les requêtes. Correctif : créez un compte SeaText séparé pour chaque domaine (production, staging, développement) comme indiqué dans les docs d'intégration Shopify.

Contenu re-rendu après l'exécution de SeaText

Les applications monopages ou les détails de produit chargés en AJAX peuvent remplacer le DOM après l'analyse initiale de SeaText. L'attribut existe dans le nouveau HTML mais SeaText a déjà terminé. Correctif : appelez la fonction de re-analyse SeaText (documentée dans l'API) après que votre framework a fini le rendu, ou utilisez le mode observateur de mutations s'il est disponible.

Faits clés

Limitations et cas où ce conseil ne s'applique pas

• Ce guide couvre le débogage des attributs de données côté client. Les problèmes de rendu côté serveur (par exemple, Next.js getServerSideProps ne transmettant pas les attributs) nécessitent des correctifs spécifiques au framework.
• Si le backend de SeaText modifie son schéma d'attributs attendu, le nom documenté dans votre guide d'intégration fait foi — pas cet article.
• Les scripts tiers qui assainissent le DOM (certains outils de sécurité, validateurs AMP) peuvent supprimer les attributs de données après que SeaText les a lus. Cela échappe au contrôle de SeaText.
• Budgets de performance : sur les pages avec des milliers d'éléments attribués, l'analyse initiale peut prendre un temps mesurable. Les étapes de diagnostic s'appliquent toujours, mais le correctif peut être la pagination ou l'attribution différée.

Référence rapide de terminologie

Attribut de données

Un attribut HTML préfixé par data- (par exemple, data-seatext) utilisé pour stocker des données personnalisées sur les éléments. Valide selon la spécification HTML.

Analyse du DOM

Le processus du script SeaText qui parcourt l'arbre du document pour trouver les éléments attribués.

Identifiant de portée

La valeur à l'intérieur de l'attribut de données qui indique à SeaText quel agent ou ensemble de règles s'applique (par exemple, « product-description », « checkout-cta »).

Script inerte

Le JS de SeaText se charge mais ne fait rien jusqu'à activation dans votre tableau de bord — une fonctionnalité de sécurité.

Observateur de mutations

Une API de navigateur qui surveille les changements du DOM ; SeaText peut l'utiliser pour ré-analyser après des mises à jour AJAX.

FAQ

Pourquoi SeaText fonctionne-t-il sur ma page d'accueil mais pas sur les pages produit ?

Les pages produit utilisent souvent des modèles différents (product.liquid vs index.liquid). L'attribut de données doit être ajouté à chaque modèle qui produit du contenu que vous souhaitez traiter. Vérifiez chaque fichier de modèle séparément.

Puis-je utiliser le même compte SeaText pour mes sites de staging et de production ?

Non. Le pack source indique que chaque compte SeaText est lié à une seule URL principale. Créez un compte séparé pour chaque domaine, y compris les environnements de staging et de développement.

Que signifie « L'IA reste inerte jusqu'à activation » pour le débogage ?

Le script se charge et analyse mais n'apporte aucune modification jusqu'à ce que vous activiez des agents dans le tableau de bord SeaText. Si vous voyez l'attribut et le chargement du script mais aucune modification, confirmez qu'au moins un agent (Traduction, CRO, Personnalisation) est actif pour ce domaine.

Comment savoir si une application tierce supprime mes attributs de données ?

Consultez le code source HTML brut (curl ou « Afficher la source » du navigateur) plutôt que le panneau Éléments des DevTools. Si l'attribut existe dans la source mais pas dans Éléments, un script côté client l'a supprimé. Désactivez les applications une par une pour isoler.

SeaText prend-il en charge les attributs dynamiques ajoutés via JavaScript ?

Oui, si vous déclenchez une re-analyse. Le script s'exécute une fois au chargement. Pour les SPA, appelez la fonction de re-analyse après que votre routeur a fini le rendu, ou activez le mode observateur de mutations si votre forfait l'inclut.

Quel est le moyen le plus rapide de tester si la syntaxe de l'attribut est correcte ?

Créez un fichier HTML minimal avec l'extrait SeaText et un élément attribué. Ouvrez-le directement dans un navigateur. Si cela fonctionne là, votre syntaxe d'attribut est correcte — le problème est dans votre thème ou pipeline de build.

Où puis-je trouver le nom exact de l'attribut pour mon intégration ?

La documentation officielle à seatext.com/documentation-ai-scope liste les noms et valeurs d'attributs actuels pour chaque plateforme et type d'agent.