Public setup documentation

Connect once. Use the translation tools already built into NewTXT.

Choose one supported installation path and let NewTXT handle discovery, dynamic DOM translation, translated HTML generation, cache, and SEO delivery. Customer projects should not build a second translation runtime.

No custom translation engineStatic and dynamic contentServer-rendered HTML support

Start in the dashboard

The dashboard is the source of truth for keys, domains, target languages, generated installation values, and verification. Do not copy a key from another site or maintain a second configuration in customer code.

Create the site

Dashboard → Sites → New site

Enter the public source URL, choose the source language, select target languages, and choose the actual platform used by the site.

Use the generated install package

Dashboard → Sites → site → Installation

Copy the generated script or package instructions. This screen owns the correct public site key, server keys, verification action, and any required DNS records.

Configure widget behavior

Dashboard → Sites → site → Widget

Choose selector placement, URL mode, translation mode, visual settings, excluded paths, and optional inline container placement.

Verify the real website

Installation → Verify installation

Publish the integration, run verification, switch to a target language, and confirm both initial content and content loaded later by JavaScript.

One site, one installation path. Use the standalone JavaScript snippet, the Laravel package, or the WordPress plugin. Laravel and WordPress already output the shared widget runtime, so installing the standalone script again creates duplicate behavior.

Choose the integration that owns the page

The choice is based on how the source page is produced, not on which language is being added. All three paths use the same NewTXT account, translation memory, service APIs, and widget settings.

Universal browser installation

Static HTML and JavaScript sites

Install the dashboard-generated loader once. The same runtime handles content already present in HTML and content inserted later by a client application.

Use for: Static pages, site builders, React, Vue, custom SPAs, and sites without backend package access.

Language switcher rendering
Initial document translation
MutationObserver translation for later DOM updates
Browser cache and NewTXT dynamic translation requests

Open setup guide

Server-side package

PHP and Laravel sites

Install the Composer package when translated HTML, local application cache, SEO metadata, and deployment commands must participate in Laravel.

Use for: Blade-rendered sites, recipe or content services, and Laravel applications that need indexable translated responses.

Package-managed widget output
Signed server-to-server render requests
Local translated HTML cache and source hash invalidation
SEO metadata, translated sitemap, health, and prewarm tools

Open setup guide

Managed CMS plugin

WordPress sites

Install the NewTXT Translate plugin and connect the dashboard keys. The plugin owns widget output, translated paths, local snapshots, and operational tools.

Use for: WordPress sites where translation should work without editing theme files or building a custom plugin.

Hosted widget loader injection
Translated path handling and local database cache
Source and translation hash storage
Admin tools, WP-CLI prewarm, sync, and cache clearing

Open setup guide

JavaScript setup: static HTML and dynamic applications

The standalone loader is the universal integration. The dashboard generates the exact snippet with the correct public site key. No API key or private key belongs in browser code.

Copy the generated loader

Copy the snippet from the site Installation panel and place it once in the shared page layout. Replace the example only with the site key generated for this domain.

<script
  src="https://cdn.newtxt.io/widget/v1/loader.js"
  data-site-key="replace-with-dashboard-site-key"
  data-navigation-mode="redirect">
</script>

Choose fixed or inline placement

Fixed placement requires no page markup. For inline placement, copy the container ID shown in Widget settings into the layout before the loader runs.

<div id="language-widget-slot"></div>

Publish and verify

Publish the real domain and run Verify installation. The runtime translates initial HTML immediately and continues watching the current document body for later JavaScript updates and SPA navigation.

Laravel setup: translated responses without custom rendering code

The package is the adapter. It signs NewTXT requests, renders the shared widget, stores ready translated HTML, invalidates cache when source content changes, and exposes deployment tools. Do not also paste the standalone script.

Install and publish the package

Install the supported Composer package and publish its configuration.

composer require newtxt/newtxt-translate:^1.15
php artisan vendor:publish --tag=newtxt-config

Store dashboard credentials and select the source mode

Use server-only environment values from the site Installation panel. Use response for complete Blade/PHP HTML. Use crawler when Laravel serves an Inertia, Vue, React, or other client-rendered application shell.

NEWTXT_ENABLED=true
NEWTXT_PUBLIC_KEY=replace-with-dashboard-public-key
NEWTXT_API_KEY=replace-with-dashboard-api-key
NEWTXT_PRIVATE_KEY=replace-with-dashboard-private-key
NEWTXT_RENDER_SOURCE_MODE=response
NEWTXT_CALLBACK_ENABLED=false

Attach middleware only to public HTML routes

The middleware must not run on authenticated, admin, account, checkout, billing, API, or webhook routes.

Route::middleware(['web', 'newtxt.render'])->group(function () {
    Route::view('/about', 'pages.about');
    Route::view('/recipes', 'pages.recipes');
});

Render the package-managed switcher

Place the Blade directive in the public layout. The package outputs the shared loader, so this is the only widget installation on the site.

@newtxtWidget()

Run the built-in health check

Validate credentials, route attachment, account settings, storage access, and API connectivity without printing secrets.

php artisan newtxt:health --json

Which source mode should I use?

response

Use for Blade or PHP pages whose public response already contains the complete content. NewTXT replaces content in that response and creates a hash-aware translated cache without starting a browser renderer.

crawler

Use for Inertia, Vue, React, or another JavaScript application where the Laravel response is only a shell. NewTXT keeps the existing HTTP/Playwright-rendered DOM instead of replacing it with incomplete HTML.

Optional deployment warmup

Prewarm known public paths after a content deployment. This uses the existing service renderer and cache; it does not add a second translation engine to Laravel.

php artisan newtxt:prewarm --language=fr --path=/recipes

WordPress setup: plugin-managed translation delivery

The plugin keeps NewTXT integration inside WordPress-owned hooks, tables, settings, and WP-CLI commands. Theme files do not need a custom translation implementation.

Install the NewTXT Translate plugin

Install and activate the plugin package from WordPress → Plugins → Add New, or upload the plugin ZIP supplied for the site.

Connect the site keys

Open WordPress → NewTXT and enter the public key, API key, and private key from the dashboard Installation panel. Keep callback disabled unless a callback secret has been configured.

Pull settings and enable the switcher

Use the plugin admin tools to pull account settings. The plugin injects the hosted loader and owns translated path delivery, so no standalone script or theme shortcode is required.

Verify and optionally prewarm

Run installation verification from NewTXT, then use the built-in status and prewarm commands when the deployment workflow needs ready local snapshots.

wp newtxt status
wp newtxt prewarm --language=fr --path=/about
wp newtxt sync --language=fr --path=/about

What each built-in function is for

These capabilities belong to NewTXT or its supported adapters. They are not separate systems that must be recreated in the customer website.

Function	Purpose	How it is enabled
Site scanner	Finds public pages, extracts safe translatable content, and refreshes source snapshots.	Automatic after the site is connected. Playwright handles JavaScript-rendered DOM and can fall back to HTTP.
Widget runtime	Renders the language selector and translates browser-visible content.	Automatic for the standalone script, Laravel directive, and WordPress plugin.
Dynamic translation	Translates text and supported attributes added after the initial page load.	Automatic through MutationObserver. Do not add a second DOM observer in the customer project.
Translated page renderer	Creates complete translated HTML for localized routes and search crawlers.	Uses scanner snapshots for JavaScript sites or the completed application response for server-rendered PHP sites.
Rendered page cache	Avoids translating and rebuilding unchanged pages on every request.	Managed remotely by NewTXT and locally by Laravel or WordPress when their package integration is installed.
SEO routing and DNS	Publishes translated paths or language hosts with canonical and hreflang metadata.	Enable SEO mode in Widget settings and install the DNS records shown in the site installation package.
Prewarm	Builds ready translated cache entries before visitors or crawlers request them.	Optional deployment tool for Laravel and WordPress. It is not a replacement crawler or translation engine.
Signed callback	Lets NewTXT request allow-listed cache, prewarm, health, or translation sync actions.	Optional and disabled by default. Enable only after a server-only callback secret is configured.

Required

Site, registered domain, source language, at least one target language, one selected integration, and a successful installation verification.

Required for SEO routes

SEO translation mode, translated URL mode, complete ready page snapshots, and the DNS records shown by the dashboard when language hosts are used.

Optional operations

Prewarm, local hash sync, callbacks, inline widget placement, image translation, and scheduled cache maintenance.

Production verification checklist

A build or an HTTP 200 response alone does not prove the integration is connected. Verify the actual public domain and the selected delivery path.

The dashboard reports the selected integration as connected.
The widget is visible on a public page and uses the site key generated for that exact domain.
Switching language updates ordinary HTML content without customer-owned translation code.
On an SPA, content added after navigation is translated after the DOM settles.
SEO translated responses report X-NewTXT-Translation-Status: ready before they are published for indexing.
Private, authenticated, checkout, account, API, and webhook routes remain excluded.

Security and privacy boundaries

Public translation must remain separate from private application data and server credentials.

Public site key only

Only the public site key belongs in browser HTML. API, private, and callback keys stay in server environment variables, WordPress protected options, or a secret manager.

Public routes only

Do not translate authenticated dashboards, accounts, checkout, billing, APIs, webhooks, or pages containing personalized information.

Protected content blocks

Mark any public subtree that must not be processed with data-cservice-ignore. NewTXT omits it from snapshots, translation, and completeness counts.

Ready to connect a site?

Create the site in the dashboard, choose its real platform, and use the generated installation package. The service will provide the values and verification steps for that exact site.

Create account Ask a setup question