Troubleshooting

The page stays in the source language#

Work through these in order; the first match is usually the cause.

Open the browser console and the Network tab. Is loader.js requested and does it return 200? A blocked request (ad blocker, CSP) means no translation.
Is manifest.json requested? A 404 means the site key is wrong, nothing is published yet, or data-base does not point to where the files are. Bundle URLs are <base>/v1/<siteKey>/manifest.json.
Signature or key problem. The loader refuses a manifest that is unsigned, signed by a key it does not know, or older than one it already accepted. Check that data-public-key is the current public key for this site. Listen for the loader's error event: its stage says where it failed.
Language file hash mismatch. A proxy or cache that rewrites JSON (minifiers, HTML injection) changes the bytes and the file is refused. Exclude /v1/ bundle paths from such features.
Unsupported browser. The loader needs Fetch, Promise, MutationObserver, TextEncoder and Ed25519 in Web Crypto.
The language was never published. Check the site's languages and run a publish job; see the job's error field.
The text is not in the bundle. A missing key means "show the source". Submit the strings and translate again. Text inside code, pre and translate="no" blocks is never translated.

Only some text is translated#

Text that appears after the page loads is picked up because the loader watches the DOM; text drawn into canvas or images is not reachable.
A string that contains a variable or inline markup the translator broke is rejected and the source stays. Review it in the editor: tags such as <1>...</1> and tokens such as ⟦p1⟧ must each appear exactly once.
Text rendered by a third-party widget in an iframe is out of reach.

Search engines do not show my translations#

That is expected with the script snippet. Read SEO and the script snippet.

Works for me, not for visitors#

The loader stores the visitor's choice and cached bundles in the browser. Test in a private window with an empty cache. Also check that your CDN or cache plugin is not caching a stale manifest.json for longer than its 60-second design.

WordPress#

Sync fails. Check the bundle address and that you ticked the permission to download. A failed sync keeps the previous copy, so the site keeps working.
Language URLs or hreflang missing. They come from the SEO module, not the core plugin.
After uninstall pages are untranslated. The plugin's script is gone; add the snippet.

Shopify#

Checkout is not translated by the loader. Expected, Shopify renders it. Use Shopify's languages for checkout.
A translation disappeared after editing in Shopify. Edits made in Shopify are protected from sync unless you enabled overwrite.

API#

Symptom	Cause
401	Key missing, revoked, expired, or sent in the query string
403	Key lacks the scope shown in the reference, or an origin is not allowed
402	A plan limit, the allowance or the licence blocks the action; the problem `type` and `detail` say which. Published bundles are unaffected. See Errors
404	Wrong id, or the resource belongs to another tenant
409	The same `Idempotency-Key` is still being processed; wait and retry
422	You reused an `Idempotency-Key` with a different body, or an import was rejected (read the `issues`; run with `--dry-run` first)
429	Back off for `Retry-After` seconds
Job `failed`	Read `error` on `GET /v1/jobs/{jobId}`

Never paste a secret key into a support request or an issue.

Webhooks#

Signature never matches. Verify against the raw request bytes (not re-serialised JSON), use the secret text exactly as shown (whsec_...), and check the five-minute timestamp window. During a secret rotation accept any v1 in the header. See Webhooks.
Deliveries stopped. A 410 answer disables an endpoint at once and 30 failures in a row disable it; re-enable with PATCH and {"enabled":true}. Check the delivery log.
The URL is refused. HTTPS, default port, public host name only; no credentials in the URL.