trans-google-translate

A highly customizable, zero-dependency React package that seamlessly wraps Google Translate. It offers a headless React Hook for fully custom selector layouts, alongside high-quality pre-styled components (a Brutalist floating button and a clean dropdown).

Designed for production environments, Next.js (SSR), and Vite.

Features

• 🌐 Worldwide Compatibility: Supports 85+ global languages out of the box.
• 🪶 Zero Styling Dependencies: Default styles are applied via inline JS objects. Works instantly in any project (Tailwind, Vanilla CSS, CSS Modules, Styled Components, etc.) without post-build CSS configuration.
• ⚙️ Headless Core: A powerful React Hook (useGoogleTranslate) manages singleton script injection, reactive synchronization across multiple components, cookie purging, and MutationObservers to clean up native Google Translate iframe banners.
• 🎨 Fully Custom Render Props: Complete control over the HTML structure and styles via renderButton, renderDropdown, and custom flags (flagUrlTemplate).
• ⚡ Reload-less Transitions: Syncs translation updates directly through Google's native dropdown element without a page reload if initialized.
• 📦 Dual Output: Ship with both CommonJS (CJS) and ES Modules (ESM) outputs via tsup.

Installation

npm install trans-google-translate
# or
yarn add trans-google-translate
# or
pnpm add trans-google-translate

Usage

1. Default Floating Brutalist Selector

Drop it anywhere in your root layout. It loads the Google Translate script automatically, registers the observer, and provides a floating button in the bottom right corner.

import { GoogleTranslate } from "trans-google-translate";

export default function App() {
  return (
    <div>
      {/* Your application content */}
      <GoogleTranslate />
    </div>
  );
}

2. Standard Dropdown Selector

If you want a normal inline dropdown selector:

import { GoogleTranslateDropdown } from "trans-google-translate";

export default function Header() {
  return (
    <header>
      <Logo />
      <GoogleTranslateDropdown />
    </header>
  );
}

3. Headless Selector (Fully Custom)

Use the hook useGoogleTranslate to construct your own custom UI. Multiple hooks on the page will automatically sync their active language states.

import { useGoogleTranslate } from "trans-google-translate";

export function CustomSelector() {
  const { currentLanguage, changeLanguage, languages } = useGoogleTranslate({
    defaultLanguage: "fr", // Set default source language
  });

  return (
    <div className="custom-selector">
      <p>Active: {currentLanguage}</p>
      <div className="grid grid-cols-4 gap-2">
        {languages.map((lang) => (
          <button
            key={lang.value}
            onClick={() => changeLanguage(lang.value)}
            className={currentLanguage === lang.value ? "active" : ""}
          >
            {lang.label}
          </button>
        ))}
      </div>
    </div>
  );
}

API Reference

useGoogleTranslate(options?: UseGoogleTranslateOptions)

Options

| Option | Type | Default | Description | | :--- | :--- | :--- | :--- | | defaultLanguage | string | "en" | The source language of your website. | | languages | LanguageOption[] | Comprehensive list | Languages to display in selectors. | | onLanguageChange | (lang: string) => void | undefined | Callback fired when the active language changes. | | showTooltip | boolean | false | Show original Google Translate hover tooltips. | | cookieDomain | string | window.location.hostname | Domain for the googtrans cookie. | | storageKey | string | "google_translate_lang" | LocalStorage key to cache the translation state. |

Return Value (UseGoogleTranslateResult)

| Value | Type | Description | | :--- | :--- | :--- | | currentLanguage | string \| null | The current active language code (e.g., "fr"). | | isDefault | boolean | true if current language matches defaultLanguage. | | isInitialized | boolean | true if the Google Translate SDK has initialized. | | isLoading | boolean | true if the SDK script is currently loading. | | current | LanguageOption \| undefined | The active language option object. | | currentFlag | string \| null | Flag CDN image URL for the active language. | | changeLanguage | (lang: string) => void | Updates active language and performs translation. | | languages | LanguageOption[] | List of languages configured for the selector. |

<GoogleTranslate /> Props

| Prop | Type | Description | | :--- | :--- | :--- | | customLanguages | LanguageOption[] | Override the default global list. | | className | string | Custom CSS class for the root wrapper element. | | style | CSSProperties | Inline styles for the root wrapper element. | | buttonClassName | string | Custom CSS class for the trigger button. | | buttonStyle | CSSProperties | Inline styles for the trigger button. | | dropdownClassName | string | Custom CSS class for the dropdown menu container. | | dropdownStyle | CSSProperties | Inline styles for the dropdown menu container. | | options | UseGoogleTranslateOptions | Configuration options passed to useGoogleTranslate. | | flagUrlTemplate | (flagCode: string) => string | Custom function to generate flag image URLs. | | renderButton | (selected: LanguageOption \| undefined, isOpen: boolean, toggle: () => void) => ReactNode | Customize the trigger button. | | renderDropdown | (languages: LanguageOption[], currentLanguage: string \| null, selectLanguage: (lang: string) => void, isOpen: boolean) => ReactNode | Customize the dropdown list. |

<GoogleTranslateDropdown /> Props

| Prop | Type | Description | | :--- | :--- | :--- | | customLanguages | LanguageOption[] | Override the default global list. | | className | string | Custom CSS class for the select wrapper. | | style | CSSProperties | Inline styles for the select wrapper. | | selectClassName | string | Custom CSS class for the native select element. | | selectStyle | CSSProperties | Inline styles for the native select element. | | options | UseGoogleTranslateOptions | Configuration options passed to useGoogleTranslate. |

License

MIT © 2026