Seatext library

Essential SeaText Integration Methods for SPA Developers

SeaText integrates into single-page applications through a single asynchronous JavaScript snippet rather than a traditional programmatic API. The snippet handles translation, personalization, and optimization automatically once installed at your app's entry point. Framework-specific steps...

How SeaText Works in a Single-Page Application

SeaText does not expose a set of named API methods such as init, setLanguage, translateNode, onRouteChange, or loadTranslations for SPA developers to call directly. The current public documentation describes only one integration mechanism: a single asynchronous JavaScript snippet that you embed once in your application's entry HTML. The snippet bootstraps a background agent that watches the DOM, detects route changes, and rewrites text in real time without further developer intervention. Source: S1

Decision Criteria: Standard Snippet vs. Manual Localization

Criterion Use the Standard Snippet Manual Localization Outside SeaText
Setup effort Paste snippet into index.html or root component; works across React, Vue, Angular You need fine-grained control over which nodes are translated or when translation fires
Route handling Agent auto-detects client-side navigation via History API and popstate Your router uses a non-standard history implementation or you need to trigger translation manually
Performance budget Script loads asynchronously (async attribute), under 15 KB, no CLS impact You must defer or lazy-load the script in a way that breaks auto-detection
Local storage access App allows third-party scripts to read/write localStorage for visitor ID Strict CSP or privacy policy blocks localStorage for external domains
Cross-origin domains SPA stays on a single origin or subdomains sharing the same snippet key App spans multiple unrelated domains that each need separate SeaText projects

Recommendation: Use the standard snippet for most SPAs; consider manual localization only when you need node-level control, use non-standard routing, or cannot allow localStorage access.

Installation Steps by Framework

React

  1. Add the SeaText snippet inside the <body> of public/index.html (or your custom HTML template). Source: S1
  2. Run npm start or your build command. Source: S1
  3. Open DevTools Console and Network tabs; verify the script loads without errors and that SeaText UI elements appear. Source: S1

Vue.js

  1. Paste the snippet into index.html (or public/index.html for Vue CLI/Vite projects). Source: S1
  2. Run npm run serve or npm run dev. Source: S1
  3. Confirm in DevTools that the script fetches and initializes on the first route. Source: S1

Angular

  1. Insert the snippet in src/index.html inside <body>. Source: S1
  2. Serve with ng serve. Source: S1
  3. Check Console for initialization logs; test navigation between routes to ensure translations persist. Source: S1

Key Technical Considerations

Asynchronous Loading and Performance

The snippet includes the async attribute, so it never blocks page paint. SeaText executes in under 15 ms before visual paint, keeping Cumulative Layout Shift at zero and preserving PageSpeed scores. The script size is under 15 KB. Source: S6

LocalStorage Dependency and CSP Constraints

The script stores a visitor identifier in localStorage. If your SPA runs in an environment that clears storage on each navigation (some privacy modes, certain Electron builds), the agent will treat every route change as a new visitor. Ensure your Content Security Policy allows localStorage access for the SeaText domain. The script does not use eval or inline scripts beyond the initial snippet. Source: S1, S6

Cross-Origin Compatibility

If your SPA loads content from multiple origins (e.g., a marketing subdomain and an app subdomain), each origin must either share the same SeaText project key or include its own snippet. The agent does not automatically share state across origins. Source: S1

Framework-Specific Verification Steps

React Verification

After adding the snippet to public/index.html, run the development server. Open Chrome DevTools (F12), switch to the Console tab, and look for SeaText initialization messages. In the Network tab, filter by "seatext" or the script domain to confirm the script downloads with a 200 status. Navigate between routes using react-router links; translated text should update without a full page reload.

Vue.js Verification

With the snippet in index.html, start the dev server via npm run dev (Vite) or npm run serve (Vue CLI). In DevTools, verify the script request appears in the Network waterfall. Check the Console for any CSP violations related to script loading or localStorage. Use vue-router to move between views; the agent should re-translate the new DOM automatically.

Angular Verification

Place the snippet in src/index.html inside the body tag. Run ng serve. In the browser, open DevTools and confirm the script loads before the Angular bootstrap completes. The Console should show SeaText readiness logs. Navigate via Angular Router; translations must persist across route changes without manual triggers.

Practical Limitations and Constraints

  • No programmatic API surface for manual translation triggers in the current public documentation. Source: S1
  • Requires localStorage access; blocked storage breaks visitor continuity. Source: S1
  • Cross-origin state sharing is not automatic; each origin needs its own snippet or shared project key. Source: S1
  • Dynamic content added after initial paint may not be translated unless the agent re-scans the DOM; no documented refresh event exists in the public sources. Source: S1
  • Only one snippet per page is supported. If you need separate projects for different sections, host those sections on separate origins. Source: S1 (implied by single snippet design)

Common Integration Scenarios and Troubleshooting

Scenario: SPA Behind a Strict CSP

Add the SeaText script domain to your script-src directive. Because the snippet is a single external script with async, no unsafe-inline or unsafe-eval is required. Verify localStorage is not blocked by a sandbox directive or privacy extensions.

Scenario: Multiple Subdomains Sharing a Project

Include the same snippet on each subdomain's entry HTML. The visitor ID stored in localStorage is scoped to each origin, so the agent treats each subdomain as a separate visitor unless you implement a shared cookie or identity solution outside SeaText.

Scenario: Lazy-Loaded Routes or Code-Split Chunks

The agent watches for DOM mutations after the initial load. When a lazy-loaded chunk mounts, the new text nodes are typically picked up on the next mutation cycle. If translations do not appear, verify the chunk's root element is attached to the document before the agent's observation window closes.

Troubleshooting: Script Not Loading

Check Network tab for failed requests (404, 403, CORS). Confirm the snippet URL is correct and the project is active in the SeaText dashboard. Ensure no ad blocker or privacy extension is filtering the script domain.

Troubleshooting: Translations Not Updating on Route Change

Confirm your router uses the standard History API (pushState, replaceState) or fires popstate. Hash-based routers that only change window.location.hash without History API calls may not trigger the agent; test with a manual navigation to verify.

Key Facts

Fact Detail Source
Integration method Single async JavaScript snippet S1
Supported frameworks React, Vue.js, Angular, and any SPA using History API S1
Script size Under 15 KB S6
Execution timing Under 15 ms before visual paint S6
Layout shift CLS = 0 S6
Storage used localStorage for visitor ID S1
Route detection Automatic via History API and popstate S1 (implied)

FAQ

Do I need to call any SeaText function on route change?

No. The snippet listens to pushState, replaceState, and popstate automatically. Translations apply to the new DOM after each navigation. Source: S1 (implied by automatic route detection)

Can I use SeaText with a strict Content Security Policy?

Yes, if you allow the SeaText script domain in script-src and permit localStorage access. The script does not use eval or inline scripts beyond the initial snippet. Source: S6

What happens if my SPA uses hash-based routing?

Hash changes fire hashchange events, which the agent also monitors. Translations will update on hash navigation without extra code. Note: This behavior is inferred from typical SPA agent design; not explicitly documented in the provided sources.

How do I exclude a section from translation?

The public documentation does not describe a data-seatext-ignore attribute. If you need to exclude sections, consider manual localization outside SeaText for those areas. Source: S1 (no mention of exclusion attribute)

Does SeaText work with Next.js App Router or React Server Components?

Place the snippet in the root layout's <body>. The agent runs in the browser after hydration; server-rendered markup is translated on the client. Note: This guidance is based on general SPA integration patterns; Next.js App Router specifics are not covered in the provided sources.

Can I run multiple SeaText projects on the same SPA?

Only one snippet per page is supported. If you need separate projects for different sections, host those sections on separate origins. Source: S1 (single snippet design)

Where do I find the snippet for my project?

Log into the SeaText dashboard, open your project, and copy the integration code from the "Installation" or "Getting Started" section. Source: S1

What if dynamic content loads via WebSockets after the initial paint?

The agent observes DOM mutations continuously. New nodes injected by WebSocket callbacks are typically translated on the next observation cycle. No public refresh event is documented. Source: S1 (automatic DOM watching)

How does SeaText affect Core Web Vitals?

The script loads asynchronously, is under 15 KB, executes in under 15 ms before paint, and causes zero Cumulative Layout Shift. It should not negatively impact LCP, FID, or CLS. Source: S6

Can I translate only specific languages programmatically?

No public API exists to control language selection from your application code. Language targeting is configured in the SeaText dashboard. Source: S1 (no programmatic API)

Further reading and comparison sources

These external sources provide additional context for evaluating the topic. Their inclusion is not an endorsement.

Further reading and comparison sources

These external sources provide additional context for evaluating the topic. Their inclusion is not an endorsement.

Learn more

Visit the website for more information.

Learn more