Quick start

Use a public key (prefixed with pk_) from your JigsawStack dashboard — not a secret key (prefixed with sk_). The widget validates the key format on startup and will refuse to initialize if a secret key is detected. Public keys must have translation capabilities enabled.

Get an API key

You need a JigsawStack public key to authenticate the widget. See Getting your API key for step-by-step instructions on creating one with translation capabilities enabled.

Install the widget

Choose the installation method that fits your project.

npm install translation-widget

Or load directly from a CDN — place this tag just before the closing </body> tag in your HTML:

index.html

<script defer src="https://unpkg.com/translation-widget@latest/dist/index.min.js"></script>

Initialize the widget

Call TranslationWidget with your public key and configuration options.ESM (npm/yarn/pnpm):

app.ts

import TranslationWidget from "translation-widget";

TranslationWidget("YOUR_PUBLIC_KEY_HERE", {
  showUI: true,
  pageLanguage: "en",
  position: "top-right",
});

Script tag (HTML):Add an initialization script immediately after the CDN script tag:

index.html

<script defer src="https://unpkg.com/translation-widget@latest/dist/index.min.js"></script>
<script defer type="module">
  TranslationWidget("YOUR_PUBLIC_KEY_HERE", {
    pageLanguage: "en",
    position: "top-right",
    autoDetectLanguage: false,
    showUI: true,
  });
</script>

Replace "YOUR_PUBLIC_KEY_HERE" with your actual public key from the JigsawStack dashboard.

Done

The widget is now active. Visit your site and you will see the translation UI appear at the configured position (default: top-right). Users can select a language from the dropdown, and the widget will translate the page content, cache the result, and restore it on future visits.The widget automatically handles:

Language persistence across page reloads via localStorage
URL-based language loading via ?lang= query parameter
DOM updates and cache management

For framework-specific setup including React hooks, Next.js App Router client components, and Next.js Pages Router with the Script component, see the Integration Guides.

Introduction

Getting your API key

Get Started

Integration Guides

Configuration

Programmatic API

Advanced

Build docs developers (and LLMs) love