Skip to main content
The JigsawStack Translation Widget adds multilingual support to any website in minutes — no backend required. Drop in a single script tag or install the npm package, initialize with your public key, and the widget handles the rest: scanning your DOM, translating content via JigsawStack’s AI engine, caching results in localStorage, and updating the page automatically.
The widget requires a public key from your JigsawStack dashboard. Make sure translation capabilities are enabled on the key before initializing the widget.

​
Key features

Drop-in installation — Add the widget to any site with a single <script> tag or one npm install. No build configuration or backend infrastructure required. 100+ languages — Translate your content to and from over 100 languages. The widget delegates all translations to JigsawStack’s contextual AI translation engine, which prioritizes meaning over literal word-for-word accuracy. Smart localStorage caching — Completed translations are stored in localStorage with a jss- prefix. Repeat visits load instantly without additional API calls, up to a cache limit of 1,000 entries per language. Automatic language detection — Set autoDetectLanguage: true and the widget reads the user’s browser language preference on load, then translates accordingly without any user interaction. URL-based language switching — Append ?lang=fr (or any language code) to any URL to pre-load the page in that language. This is useful for sharing links in a specific language or for server-side redirects. Programmatic API — Control translations from your own code using three global functions: window.translate() to switch language, window.resetTranslation() to revert or re-translate, and window.clearCache() to clear stored translations. Use these to build fully custom language selectors while disabling the default widget UI. Fully customizable CSS — Override any widget element by targeting its CSS classes in your own stylesheet. Use the built-in theme option to set baseColor and textColor, or write your own rules for complete control. Font size adjustment — Enable adjustFontSize: true to automatically scale down font sizes for translated text that is longer than the original, preventing overflow in constrained layouts. Font sizes scale logarithmically with a minimum of 12px and are restored when translation is reset. Works with HTML, React, and Next.js — The widget runs entirely in the browser and integrates with static HTML files, React applications, Next.js App Router, and Next.js Pages Router.

​
How it works

  1. Initialization — You call TranslationWidget(publicKey, config) with your JigsawStack public key and optional configuration. The widget injects its styles into the document <head> and mounts the UI element at the configured position.
  2. Language resolution — The widget determines which language to display using a priority order: a ?lang= URL parameter takes precedence, followed by the user’s previously selected language (stored in localStorage under the key jss-pref), and finally the pageLanguage default from your config.
  3. DOM scanning — The widget walks the DOM and collects all text nodes that contain translatable content, skipping script and style elements.
  4. Batched translation — Text is grouped into batches of up to 90 items and sent to the JigsawStack translation API, with a rate limit of 45 requests per second.
  5. Caching — Each translated string is stored in localStorage with an LZ-compressed cache entry containing the original text, its translation, and a timestamp.
  6. DOM update — The widget replaces text node content with the returned translations and stores the original text in a data-original-text attribute on each element so it can be restored later.

Quick start

Get translation running on your site in under 5 minutes.

Get your API key

Sign up for JigsawStack and generate a public key.

Build docs developers (and LLMs) love

Get started for freeTalk to us