Next.js (Page Router)

​

Step 1 — Create your Website Configuration

• Name — A friendly name for your project (e.g., My website).
• Domain — Your production domain (e.g., example.com).
• Redis Cache URL (Secure) — A secure rediss:// connection string for caching translations. See Set up Redis with Upstash if you don’t have one.
• Translate from — The source language for your content.
• Translate to — One or more target languages.

​

Step 2 — Add the script in Next.js

import Script from "next/script";
import type { AppProps } from "next/app";

export default function MyApp({ Component, pageProps }: AppProps) {
  return (
    <>
      {/* Website Translate Script */}
      <Script
        src="https://storage.googleapis.com/website-translation-script/translator.js"
        data-api-key="your-api-key"
        strategy="afterInteractive"
      />
      <Component {...pageProps} />
    </>
  );
}

​

Optional — Manage the API key via environment variable

NEXT_PUBLIC_TRANSLATOR_API_KEY=your-api-key

<Script
  src="https://storage.googleapis.com/website-translation-script/translator.js"
  data-api-key={process.env.NEXT_PUBLIC_TRANSLATOR_API_KEY}
  strategy="afterInteractive"
/>

​

Step 3 — Deploy and verify

1. Deploy your Next.js app as usual (Vercel, Netlify, or your preferred platform).
2. Open your site in a browser and confirm that a translation dropdown appears automatically.
3. Switch languages and verify page text is translated without layout shifts or flashes.

​

Best practices for a great UX

• Warm the cache. After deployment, visit your key pages yourself and wait for the initial translation to complete so future visitors get instant translations.
• Keep phrases intact. Avoid splitting single words or short phrases into many tiny elements — translation accuracy is higher when the translator sees whole sentences.

​

Exclude content from translation

<div translate="no">BrandName</div>
<span class="notranslate">CodeSnippet()</span>

​

Style the translation dropdown

:root {
  /* Position */
  --tl-position: fixed;
  --tl-bottom: 24px;
  --tl-right: 24px;
  --tl-top: auto;
  --tl-left: auto;
  --tl-z-index: 9999;

  /* Appearance */
  --tl-bg: #333;
  --tl-bg-hover: #555;
  --tl-color: #fff;
  --tl-border: none;
  --tl-border-radius: 4px;
  --tl-box-shadow: 0 2px 10px rgba(0, 0, 0, 0.1);

  /* Typography */
  --tl-font-family: "Inter", sans-serif;
  --tl-font-size: 14px;
  --tl-font-weight: 500;
  --tl-line-height: 1;

  /* Spacing */
  --tl-padding: 12px 16px;
  --tl-margin: 0;
  --tl-min-width: 120px;
  --tl-width: auto;
  --tl-height: auto;

  /* Options */
  --tl-option-bg: #333;
  --tl-option-color: #fff;
  --tl-option-padding: 8px 12px;

  /* Loading state */
  --tl-loading-opacity: 0.7;
  --tl-loading-icon: "⟳";
  --tl-loading-margin: 8px;
  --tl-loading-duration: 1s;

  /* Focus */
  --tl-outline: 2px solid #007acc;
  --tl-outline-offset: 2px;

  /* Transition */
  --tl-transition: all 0.2s ease;
}

​

Troubleshooting

​

Security & configuration notes

• Only use the official script source: https://storage.googleapis.com/website-translation-script/translator.js.
• Prefer environment variables (NEXT_PUBLIC_TRANSLATOR_API_KEY) for manageability across environments.
• Use a secure Redis URL. Your Redis Cache URL must use rediss:// (TLS-encrypted) — never plain redis://.