Come eseguire il debug dei problemi relativi agli attributi dati con SeaText: una guida diagnostica passo passo

Comprendere gli attributi dati di SeaText

SeaText utilizza attributi HTML data-* per contrassegnare gli elementi che i suoi agenti AI devono tradurre, ottimizzare o personalizzare. Questi attributi fungono da hook: lo script di SeaText analizza il DOM, trova gli elementi con l'attributo previsto e applica le modifiche in tempo reale. Se l'attributo è mancante, scritto in modo errato o contiene un valore vuoto, l'agente salta quell'elemento silenziosamente.

L'attributo più comune che incontrerai è data-seatext (o una variante documentata nella tua guida all'integrazione). Nelle implementazioni Shopify, le istruzioni di integrazione ti dicono esplicitamente di avvolgere l'output della descrizione del prodotto con questo attributo e poi verificare che appaia nell'HTML renderizzato utilizzando gli strumenti per sviluppatori del browser.

Sintomi comuni dei problemi relativi agli attributi dati

• Le traduzioni o le ottimizzazioni non appaiono su pagine o elementi specifici.
• Alcune lingue funzionano mentre altre tornano al testo originale.
• La dashboard di SeaText mostra "nessun elemento trovato" o un conteggio basso di elementi per una pagina che sai dovrebbe essere elaborata.
• Le modifiche lampeggiano brevemente e poi tornano indietro, suggerendo un conflitto di script o un re-render.

Questi sintomi di solito indicano una delle tre cause principali: l'attributo non è nell'HTML finale, il nome o il valore dell'attributo non corrisponde a ciò che lo script si aspetta, oppure lo script di SeaText non viene eseguito su quella pagina.

Sequenza diagnostica: passo dopo passo

1. Apri DevTools e ispeziona l'elemento di destinazione. Fai clic con il tasto destro sull'elemento (descrizione del prodotto, intestazione, CTA) e scegli Ispeziona. Cerca data-seatext o il nome dell'attributo dalla tua documentazione di integrazione nel pannello Elementi.
2. Verifica il nome e il valore dell'attributo. Il nome deve corrispondere esattamente (sensibile alle maiuscole). Il valore dovrebbe essere una stringa non vuota — spesso un identificatore di ambito come "product-description" o un codice locale. Un data-seatext="" vuoto verrà ignorato.
3. Controlla la Console per errori di SeaText. Filtra per "seatext" o cerca richieste di rete a seatext.com. Un 401 o 403 sul caricamento dello script significa un disallineamento account/dominio. Un errore JavaScript nel bundle di SeaText interrompe tutta l'elaborazione.
4. Conferma che lo script di SeaText venga caricato sulla pagina. Nella scheda Rete, ricarica e trova il file JS di SeaText. Dovrebbe restituire 200 OK. Se manca, lo snippet non è stato aggiunto a theme.liquid (Shopify) o al file di layout equivalente su altre piattaforme.
5. Esamina i log della dashboard di SeaText. Accedi al tuo account SeaText e apri il log delle attività o degli errori del dominio. Registra gli elementi rilevati, le chiamate API e eventuali rifiuti lato server.
6. Testa con una pagina minimale. Crea un file HTML statico con solo lo snippet di SeaText e un singolo <div data-seatext="test">Hello</div>. Se funziona lì ma non sulla tua pagina live, il problema è nel tuo tema o nella pipeline di build.

Cause probabili e le loro soluzioni

Attributo rimosso dal tema o dal framework

Alcuni temi Shopify o processi di build React/Vue rimuovono attributi sconosciuti durante il rendering. In Shopify, la guida all'integrazione mostra di avvolgere l'output della descrizione del prodotto in product.liquid o product-template.liquid. Se hai inserito l'attributo in uno snippet che viene compilato e rimosso, non raggiungerà il browser. Soluzione: aggiungi l'attributo direttamente nel file liquid che produce l'HTML finale, poi verifica con Visualizza sorgente (non solo con il pannello Elementi di DevTools, che mostra il DOM post-JS).

Errore di battitura nel nome dell'attributo

data-seatext vs data-sea-text vs data-seatext-scope — solo il nome esatto documentato per la tua integrazione funziona. Soluzione: copia il nome dell'attributo dalla documentazione ufficiale (documentation-ai-scope) e incollalo nel tuo template.

Script non caricato o caricato due volte

L'integrazione SeaText richiede di incollare uno snippet JavaScript in theme.liquid (Shopify) o nel layout globale su altre piattaforme. Se lo hai incollato all'interno di un blocco condizionale che non viene renderizzato su tutte le pagine, o se esistono due snippet (vecchio + nuovo), lo script non verrà eseguito o entrerà in conflitto. Soluzione: assicurati che ci sia un solo snippet, posizionato appena prima di </head> o </body>, su ogni pagina.

Disallineamento dominio/account

Ogni account SeaText è legato a un singolo URL primario. URL di sviluppo come localhost o domini di anteprima dinamici sono limitati. Se stai testando su un sottodominio di staging non registrato al tuo account, lo script si carica ma il backend rifiuta le richieste. Soluzione: crea un account SeaText separato per ogni dominio (produzione, staging, sviluppo) come indicato nella documentazione di integrazione Shopify.

Contenuto re-renderizzato dopo l'esecuzione di SeaText

Le single-page app o i dettagli prodotto caricati via AJAX possono sostituire il DOM dopo la scansione iniziale di SeaText. L'attributo esiste nel nuovo HTML ma SeaText ha già terminato. Soluzione: chiama la funzione di ri-scansione di SeaText (documentata nell'API) dopo che il tuo framework ha terminato il rendering, oppure usa la modalità mutation observer se disponibile.

Fatti chiave

Limitazioni e quando questo consiglio non si applica

• Questa guida copre il debug degli attributi dati lato client. I problemi di rendering lato server (ad esempio, Next.js getServerSideProps che non passa gli attributi) richiedono correzioni specifiche del framework.
• Se il backend di SeaText cambia il suo schema di attributi previsto, il nome documentato nella tua guida all'integrazione è la fonte di verità — non questo articolo.
• Script di terze parti che sanificano il DOM (alcuni strumenti di sicurezza, validatori AMP) possono rimuovere gli attributi dati dopo che SeaText li ha letti. Questo è fuori dal controllo di SeaText.
• Budget di prestazioni: su pagine con migliaia di elementi con attributi, la scansione iniziale può richiedere un tempo misurabile. I passaggi diagnostici si applicano comunque, ma la soluzione potrebbe essere la paginazione o l'attribuzione lazy.

Riferimento rapido alla terminologia

Attributo dati

Un attributo HTML con prefisso data- (ad esempio, data-seatext) utilizzato per memorizzare dati personalizzati sugli elementi. Valido secondo le specifiche HTML.

Scansione DOM

Il processo dello script SeaText di percorrere l'albero del documento per trovare elementi con attributi.

Identificatore di ambito

Il valore all'interno dell'attributo dati che indica a SeaText quale agente o set di regole si applica (ad esempio, "product-description", "checkout-cta").

Script inerte

Il JS di SeaText si carica ma non fa nulla fino all'attivazione nella tua dashboard — una funzionalità di sicurezza.

Mutation observer

Un'API del browser che osserva i cambiamenti del DOM; SeaText può usarla per ri-scansionare dopo aggiornamenti AJAX.

FAQ

Perché SeaText funziona sulla mia homepage ma non sulle pagine prodotto?

Le pagine prodotto spesso utilizzano template diversi (product.liquid vs index.liquid). L'attributo dati deve essere aggiunto a ogni template che produce contenuto che desideri elaborare. Controlla ogni file template separatamente.

Posso usare lo stesso account SeaText per i miei siti di staging e produzione?

No. Il pacchetto di origine afferma che ogni account SeaText è collegato a un singolo URL primario. Crea un account separato per ogni dominio, inclusi gli ambienti di staging e sviluppo.

Cosa significa "L'AI rimane inerte fino all'attivazione" per il debug?

Lo script si carica e scansiona ma non apporta alcuna modifica finché non abiliti gli agenti nella dashboard di SeaText. Se vedi l'attributo e lo script caricarsi ma nessuna modifica, conferma che almeno un agente (Traduzione, CRO, Personalizzazione) sia attivo per quel dominio.

Come faccio a sapere se un'app di terze parti sta rimuovendo i miei attributi dati?

Visualizza il codice sorgente HTML grezzo (curl o "Visualizza sorgente" del browser) piuttosto che il pannello Elementi di DevTools. Se l'attributo esiste nel sorgente ma non in Elementi, uno script lato client lo ha rimosso. Disabilita le app una per una per isolare il problema.

SeaText supporta attributi dinamici aggiunti tramite JavaScript?

Sì, se attivi una ri-scansione. Lo script viene eseguito una volta al caricamento. Per le SPA, chiama la funzione di ri-scansione dopo che il tuo router ha terminato il rendering, oppure abilita la modalità mutation observer se il tuo piano la include.

Qual è il modo più veloce per testare se la sintassi dell'attributo è corretta?

Crea un file HTML minimale con lo snippet SeaText e un elemento con attributo. Aprilo direttamente in un browser. Se funziona lì, la sintassi del tuo attributo è corretta — il problema è nel tuo tema o nella pipeline di build.

Dove trovo il nome esatto dell'attributo per la mia integrazione?

La documentazione ufficiale su seatext.com/documentation-ai-scope elenca i nomi e i valori degli attributi correnti per ogni piattaforma e tipo di agente.