Install on a single-page app

Partly builtLast updated 2026-10-29

On this page

Steps
Route changes
Better for search
Security policy

Single-page apps and headless sites draw their text with JavaScript. The loader watches the page for changes, so it translates text after your app has drawn it.

Steps#

Add the script tag once, in the HTML shell of your app. Use async.
With a framework that renders on the server, load the script so that it runs after hydration. In Next.js use the Script component: afterInteractive is its default strategy, and Next.js passes extra attributes such as data-* to the script element (Next.js documentation, checked 2026-10-29). Next.js does not say how it treats the async attribute, because its strategy sets the timing. In Nuxt use useHead or app.head; in Astro use is:inline; in Gatsby use gatsby-ssr. These are the documented ways to add a script, but we have not run our loader in each of them: verify. Otherwise hydration can see text that differs from what the server sent.
Mark any element that your framework redraws often with translate="no", or it may overwrite the translation. See Mark content that must not be translated.

Route changes#

A route change in a single-page app does not reload the page. The loader sees the new elements and translates them. Language addresses such as /fr/... are not made by the loader. Your router must handle them.

Better for search#

A headless site can do much more than the script tag. Render a route for each language on the server, using the exported translations, and add hreflang tags. The framework kits do this at build time. Use the script tag only as the switcher and as a fallback.

Security policy#

If your site has a content security policy, add the loader address to the script rules and the file addresses to the connect rules. With a nonce-based policy, give the script tag your nonce. Next.js says a nonce needs pages rendered on request, so it cannot be used on a static export (checked 2026-10-29). On a static host the policy comes from the host's header settings. See Content security policy.