@pnx-mixtape/mxds 0.1.0-rc.4 → 0.1.0-rc.6

package/src/Component/Translate/README.md

@@ -0,0 +1,285 @@
+# Translate
+
+A language switcher that drives Google's Website Translator widget from custom, accessible UI —
+built on `DropMenu`/`Popover` for the accessible trigger-button-and-menu behaviour, so this
+component only has to handle actually driving translation.
+
+**Unlike every other mxds component, Translate loads a third-party runtime script**
+(`translate.google.com/translate_a/element.js`) on first language change. This is Google's
+official, unversioned "Website Translator" widget, not an mxds-controlled dependency — mxds
+cannot guarantee its availability, behaviour, or continued existence. Consumers embedding
+Translate should be aware this introduces an external network dependency and a third-party
+script executing on their page. See "Google Translate quirks" below.
+
+---
+
+## CSS Import
+
+```css
+@import "@pnx-mixtape/mxds/src/Component/Translate/translate.css";
+@import "@pnx-mixtape/mxds/src/Component/Popover/popover.css";
+@import "@pnx-mixtape/mxds/src/Component/GlobalAlert/global-alert.css";
+```
+
+The notice (if you use one — see [Notice placement](#notice-placement)) reuses `GlobalAlert`'s
+classes directly, so its CSS is still needed even though the notice itself is built by
+`GoogleTranslateWidget`, not by including `GlobalAlert`.
+
+---
+
+## Twig
+
+```twig
+{% include '@mixtape/Component/Translate/translate.twig' with {
+  id: 'translate',
+  languages: [
+    { code: 'en', label: 'English' },
+    { code: 'fr', label: 'Français' },
+    { code: 'es', label: 'Español' },
+  ],
+  defaultLanguage: 'en',
+  noticeContent: 'Our website uses an automatic service to translate content. These translations should be used as a guide only.',
+  noticeBlockedContent: 'This page is only available in English.',
+} %}
+```
+
+**translate.twig props:**
+
+| Prop                   | Type                                | Default        | Description                                                                                                                                                                  |
+| ---------------------- | ----------------------------------- | -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `id`                   | `string`                            | `translate`    | Root id, used to wire the trigger/menu together                                                                                                                              |
+| `label`                | `string`                            | `Language`     | Trigger's accessible name                                                                                                                                                    |
+| `languages`            | `{ code: string, label: string }[]` | —              | The language list — **no built-in default**, pass your own                                                                                                                   |
+| `defaultLanguage`      | `string`                            | `en`           | The page's source language code                                                                                                                                              |
+| `blockedPaths`         | `string[]`                          | —              | Paths where translation is disallowed — `noticeBlockedContent` shows instead                                                                                                 |
+| `updateTriggerLabel`   | `boolean`                           | `true`         | Keep the trigger's visible code + `aria-label` in sync with the active language. Pass `false` to keep the trigger static instead, which some sites prefer                    |
+| `noticeContent`        | `string`                            | —              | Copy shown once a non-default language is active. **Entirely opt-in** — omit to never create a notice at all                                                                 |
+| `noticeBlockedContent` | `string`                            | —              | Copy shown instead, on a blocked path                                                                                                                                        |
+| `noticeAnchor`         | `string`                            | —              | CSS selector for where to insert the notice. Defaults to the top of `<body>` if omitted — see [Notice placement](#notice-placement) below                                    |
+| `noticePosition`       | `string`                            | —              | Insertion position relative to `noticeAnchor` (`beforebegin`/`afterbegin`/`beforeend`/`afterend`). Defaults to `afterend` when `noticeAnchor` is set, `afterbegin` otherwise |
+| `placement`            | `PopoverPlacementModifier`          | `bottom-start` | Menu position relative to the trigger                                                                                                                                        |
+| `scriptUrl`            | `string`                            | —              | Advanced override for Google's script URL (e.g. a self-hosted proxy)                                                                                                         |
+| `storageKey`           | `string`                            | `googtrans`    | Advanced override — risky to change, see "Google Translate quirks"                                                                                                           |
+| `attributes`           | `Attribute`                         | —              | Optional Drupal-style attributes object — `mx-translate` is always merged on top                                                                                             |
+
+Registers as `<mx-translate>`. Import the element to activate its behaviour:
+
+```js
+import "@pnx-mixtape/mxds/src/Component/Translate/Elements/Translate"
+```
+
+---
+
+## HTML + Web Component
+
+```html
+<mx-translate class="mx-translate" closeonclick data-default-language="en">
+  <button
+    id="translate-target"
+    type="button"
+    class="mx-translate__trigger mx-popover__trigger notranslate"
+    popovertarget="translate"
+    style="anchor-name: --translate"
+    data-label="Language"
+    aria-label="Language, EN"
+  >
+    <span class="mx-icon mx-icon--globe"></span>
+    <span class="mx-translate__code">EN</span>
+  </button>
+  <div
+    class="mx-popover mx-translate__menu notranslate"
+    id="translate"
+    style="position-anchor: --translate"
+    data-placement="bottom-start"
+    popover
+    role="menu"
+  >
+    <a
+      class="mx-translate__item"
+      href="?hl=fr"
+      lang="fr"
+      hreflang="fr"
+      role="menuitem"
+      data-language="fr"
+      >Français</a
+    >
+    <!-- ...one per language -->
+  </div>
+</mx-translate>
+```
+
+**`<mx-translate>` attributes:**
+
+| Attribute                     | Description                                                                                                                                                 |
+| ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `data-default-language`       | The page's source language code                                                                                                                             |
+| `data-blocked-paths`          | Comma-separated list of blocked path prefixes                                                                                                               |
+| `data-update-trigger-label`   | Keep the trigger's visible code + `aria-label` in sync with the active language. Defaults to `"true"` — set to `"false"` to keep the trigger static instead |
+| `data-notice-content`         | Copy shown once a non-default language is active. **Entirely opt-in** — omit to never create a notice                                                       |
+| `data-notice-blocked-content` | Copy shown instead, on a blocked path                                                                                                                       |
+| `data-notice-anchor`          | CSS selector for where to insert the notice — see [Notice placement](#notice-placement)                                                                     |
+| `data-notice-position`        | Insertion position relative to `data-notice-anchor`                                                                                                         |
+| `data-script-url`             | Advanced override for Google's script URL                                                                                                                   |
+| `data-storage-key`            | Advanced override for the `localStorage` key                                                                                                                |
+
+### Notice placement
+
+The notice isn't pre-rendered — it's created via JS, the first time a language is actually
+chosen, and inserted wherever `noticeAnchor`/`noticePosition` (or their React equivalents) point.
+This matters because **the notice doesn't have to live next to the trigger.** If `<mx-translate>`
+is placed in a page header, you usually don't want the notice crammed in there too — real
+deployments of this pattern vary: one site renders it directly below the header, another at the
+very top of the page, above everything else. Point `noticeAnchor` at whatever landmark makes
+sense for your layout (omit it entirely to default to the top of `<body>`, matching the simplest
+case of "always at the top of the page").
+
+If no `noticeContent` is given, no notice is ever created — it's an entirely optional feature,
+not something every consumer has to account for.
+
+**Styled as a `GlobalAlert`** (`mx-global-alert mx-global-alert--light`/`--critical`, plus
+`mx-page` for GlobalAlert's own full-bleed grid treatment) — a site-wide banner is the right fit
+for "this page is machine-translated," not a page-scoped `InPageAlert`. It's a **non-dismissible**
+variant: there's no close button and no `<mx-closable-alert>` wrapper, so it isn't backed by
+dismissal `localStorage` the way a real `GlobalAlert` usually is — it simply shows and hides
+itself as the active language/blocked-path state changes, same as everything else this component
+drives.
+
+**Keyboard nav, click-to-select, and light-dismiss are all inherited from `DropMenu`/`Popover`**
+— `<mx-translate>` extends `DropMenu`'s Web Component, so roving `ArrowUp`/`Down`/`Left`/`Right`
+focus (with wraparound), `Enter`/click to select, `Escape`/outside-click to close, and
+`aria-expanded`/`aria-controls` bookkeeping via the native Popover API all come from there for
+free. Translate's own `Elements/Translate.ts` only adds: driving `GoogleTranslateWidget` on
+selection, and setting/clearing `aria-current` on the chosen language link (something DropMenu's
+own selection bookkeeping only does for button-mode items, not `<a>` links like these).
+
+**Events:**
+
+```js
+document.querySelector("mx-translate").addEventListener("translate-language-change", e => {
+  console.log(e.detail.code) // the chosen language code
+})
+```
+
+`translate-open` / `translate-close` fire on menu open/close (React analogues of `onOpen`/
+`onClose`).
+
+---
+
+## React
+
+```tsx
+import { Translate } from "@pnx-mixtape/mxds/react"
+import { DEFAULT_LANGUAGES } from "@pnx-mixtape/mxds/src/Component/Translate/languages"
+
+;<Translate
+  id="translate"
+  languages={DEFAULT_LANGUAGES}
+  defaultLanguage="en"
+  noticeContent="Our website uses an automatic service to translate content. These translations should be used as a guide only."
+  noticeBlockedContent="This page is only available in English."
+  noticeAnchor="#site-header"
+  onLanguageChange={code => console.log(code)}
+/>
+```
+
+`DEFAULT_LANGUAGES` is an **opt-in** exported constant — `Translate` itself never defaults to it
+implicitly. Import it, or pass your own `languages` list.
+
+**`Translate` props:** same set as the Twig props above (camelCase), plus:
+
+| Prop                 | Type                     | Default | Description                                                                                     |
+| -------------------- | ------------------------ | ------- | ----------------------------------------------------------------------------------------------- |
+| `closeOnSelect`      | `boolean`                | `true`  | Closes the menu after a language is chosen                                                      |
+| `onOpen` / `onClose` | `() => void`             | —       | Called when the menu opens/closes                                                               |
+| `onLanguageChange`   | `(code: string) => void` | —       | Called when a language is chosen — analytics/telemetry hook, replaces a hardcoded tracking call |
+| `className`          | `string`                 | —       | Extra class on the root                                                                         |
+
+Note that `noticeContent`/`noticeBlockedContent` are plain `string`s here, not `ReactNode` — see
+[parity](#react--twig-parity) below for why.
+
+---
+
+### React ⇄ Twig parity
+
+- `closeOnSelect` has no Twig prop — the Web Component always closes on click (the `closeonclick`
+  attribute is hardcoded in `translate.twig`, matching `DropMenu`'s own attribute-driven
+  convention rather than being exposed as a template prop).
+- `onOpen`/`onClose`/`onLanguageChange` have no Twig props — Twig/HTML has no concept of a
+  function prop. The Web Component dispatches `translate-open`/`translate-close`/
+  `translate-language-change` `CustomEvent`s instead.
+- `noticeContent`/`noticeBlockedContent` are plain strings in **both** stacks, not `ReactNode` in
+  React — the shared `GoogleTranslateWidget` class builds the notice's DOM from an HTML template
+  string so it can insert the exact same markup at the configured anchor point regardless of
+  framework. This is the one place Translate trades away React's usual "pass rich JSX content"
+  flexibility for truly identical cross-stack behaviour (the notice isn't part of either
+  framework's own render tree — see [Notice placement](#notice-placement) above).
+- The React item list is built directly in JSX rather than composing `DropMenu`'s own
+  `DropMenuItem` — `DropMenuItem` only renders `<button>`, and a language switcher needs real
+  `<a href>` links (for progressive enhancement/crawlability) with `lang`/`hreflang` attributes
+  DropMenuItem doesn't support. Roving focus still comes from `react-aria`'s `useFocusManager`,
+  the same primitive DropMenuItem itself uses.
+
+---
+
+## Modifiers
+
+No BEM modifier classes.
+
+---
+
+## Accessibility
+
+- By default, the trigger's accessible name (`aria-label`) updates to reflect the active language
+  (e.g. `"Language: Français, FR"`) rather than staying static — pass `updateTriggerLabel={false}` to
+  keep it static instead, which some sites prefer.
+- The accessible name always includes the visible language code (e.g. `EN`) so it satisfies WCAG
+  2.5.3 Label in Name — speech-input users can activate the trigger by saying what they see.
+- Each language link gets `lang`/`hreflang` set to its own code, so screen readers pronounce each
+  language name using that language's own phonetics.
+- The active language gets `aria-current="true"`, cleared from the previously active one.
+- `notranslate` is applied to the trigger and menu so Google's own translator doesn't attempt to
+  translate the switcher's own UI.
+- `aria-expanded`, `aria-controls`, keyboard support (roving arrows, Enter, Escape), and focus
+  return to the trigger on close are all inherited from the native Popover API via `DropMenu`
+  — see its own README for the full contract.
+- The menu scrolls (`overflow-y: auto`, capped at `--translate-menu-max-block-size`) rather than
+  growing unbounded off-screen for a long language list.
+
+---
+
+## Customisation via CSS custom properties
+
+```css
+.mx-translate__menu {
+  --translate-menu-max-block-size: 60vh; /* menu scroll cap */
+}
+```
+
+Also inherits `Popover`'s own custom properties (`--popover-padding`, `--popover-background`,
+etc.) via the shared `.mx-popover` class.
+
+---
+
+## Google Translate quirks
+
+- **bfcache restore:** Google's translator instance doesn't survive the browser's back/forward
+  cache. `GoogleTranslateWidget` listens for `pageshow` and re-injects the script/re-applies the
+  active language when a page is restored from bfcache.
+- **`googtrans` storage key:** the active language is persisted to `localStorage` under the
+  literal key `googtrans`, in the exact format (`/<source>/<target>`) Google's own script reads —
+  this is intentional, so a page using Google's default banner elsewhere would interoperate.
+  Overriding `storageKey` breaks that interop; only do so if you specifically need to namespace
+  it away from Google's own script.
+- **One Google widget per page:** the underlying script and `TranslateElement` instance are
+  loaded/instantiated once globally (shared across multiple `Translate` instances on the same
+  page, e.g. a header and footer switcher) — Google's widget is inherently page-global, there's
+  no way to run two independent translation states on one page.
+- **The hidden `<select class="goog-te-combo">` populates its `<option>` list asynchronously**,
+  on Google's own timeline, after `TranslateElement` is constructed — the `<select>` element
+  itself can exist before the option for your target language does. Setting `.value` to a code
+  with no matching `<option>` yet is a silent DOM no-op (the browser just ignores it), so
+  `GoogleTranslateWidget` waits for the specific `<option>` to exist, not just the `<select>`,
+  before driving it. It also tracks the most recently requested language and drops the result of
+  an earlier, slower-resolving selection if a newer one has since superseded it — without this,
+  switching languages quickly (or switching again before the first selection's options finish
+  loading) could apply a stale value or fire an out-of-order `change` event.

package/src/Component/Translate/Translate.stories.ts

@@ -0,0 +1,87 @@
+import { Meta, StoryObj } from "@storybook/html-vite"
+import { expect, waitFor } from "storybook/test"
+import Component from "./translate.twig"
+import "./translate.css"
+import "./Elements/Translate"
+
+// Deps.
+import "../Popover/popover.css"
+import "../GlobalAlert/global-alert.css"
+
+const LANGUAGES = [
+  { code: "en", label: "English" },
+  { code: "fr", label: "Français" },
+  { code: "es", label: "Español" },
+]
+
+/**
+ * A language switcher that drives Google's Website Translator widget. It requires the
+ * `Translate` custom element javascript, and is built on `DropMenu`/`Popover` — their CSS must
+ * also be imported.
+ *
+ * Loading Google's own translation script (on first language change) is an unavoidable
+ * third-party network dependency — see the README's "Google Translate quirks" section.
+ */
+const meta: Meta<typeof Component> = {
+  tags: ["autodocs"],
+  component: Component,
+  args: {
+    id: "translate",
+    languages: LANGUAGES,
+    defaultLanguage: "en",
+    noticeContent:
+      "Our website uses an automatic service to translate content. These translations should be used as a guide only.",
+  },
+}
+
+export default meta
+type Story = StoryObj<typeof meta>
+
+export const Translate: Story = {
+  play: async ({ canvasElement, canvas, userEvent, step }) => {
+    // This story's own selection below persists to real localStorage (by design — see the
+    // README's "Google Translate quirks" section) — clear any stale value up front so this test
+    // (and a fresh view of the story) always starts from the real default state.
+    window.localStorage.removeItem("googtrans")
+
+    const trigger = canvas.getByRole("button", { name: /^Language\b/ })
+    const menu = canvasElement.querySelector("#translate") as HTMLElement
+    const french = await canvas.findByRole("menuitem", { name: "Français", hidden: true })
+    // The notice is created via JS on first use (not pre-rendered) and inserted at the
+    // configured anchor point — the top of <body> by default here — not necessarily inside
+    // canvasElement, since the whole point is that it doesn't have to live next to the trigger
+    // (e.g. trigger in the header, notice below it). Query the owner document, and only once
+    // it's actually been created.
+    const findNotice = (): HTMLElement | null =>
+      canvasElement.ownerDocument.querySelector("[data-translate-notice]")
+
+    await step("Menu starts closed; notice doesn't exist until a language is chosen", async () => {
+      await expect(menu.matches(":popover-open")).toBe(false)
+      await expect(findNotice()).toBeNull()
+    })
+
+    await step("Opens on trigger click, listing every language as a link", async () => {
+      await userEvent.click(trigger)
+      await waitFor(() => expect(menu.matches(":popover-open")).toBe(true))
+      await expect(french).toHaveAttribute("href", "?hl=fr")
+    })
+
+    await step(
+      "Choosing a language marks it current, updates the trigger, and shows the notice",
+      async () => {
+        await userEvent.click(french)
+        await waitFor(() => expect(french).toHaveAttribute("aria-current", "true"))
+        await expect(trigger).toHaveAttribute("aria-label", "Language: Français, FR")
+        await waitFor(() => expect(findNotice()).not.toHaveAttribute("hidden"))
+      },
+    )
+
+    await step("Restores original state", async () => {
+      await userEvent.click(trigger)
+      await waitFor(() => expect(menu.matches(":popover-open")).toBe(true))
+      await userEvent.click(canvas.getByRole("menuitem", { name: "English" }))
+      window.localStorage.removeItem("googtrans")
+      await userEvent.click(canvasElement)
+    })
+  },
+}

package/src/Component/Translate/Translate.stories.tsx

@@ -0,0 +1,77 @@
+import { Meta, StoryObj } from "@storybook/react-vite"
+import { expect, waitFor } from "storybook/test"
+import Component from "./Translate"
+import "./translate.css"
+import "../Popover/popover.css"
+import "../GlobalAlert/global-alert.css"
+import { Page } from "../../../.storybook-react/decorators"
+import { TranslateLanguage } from "./languages"
+
+const LANGUAGES: TranslateLanguage[] = [
+  { code: "en", label: "English" },
+  { code: "fr", label: "Français" },
+  { code: "es", label: "Español" },
+]
+
+const meta: Meta<typeof Component> = {
+  tags: ["autodocs"],
+  component: Component,
+  decorators: [Page],
+  args: {
+    id: "translate",
+    languages: LANGUAGES,
+    defaultLanguage: "en",
+    noticeContent:
+      "Our website uses an automatic service to translate content. These translations should be used as a guide only.",
+  },
+}
+
+export default meta
+
+export const Translate: StoryObj<typeof meta> = {
+  play: async ({ canvasElement, canvas, userEvent, step }) => {
+    // This story's own selection below persists to real localStorage (by design — see the
+    // README's "Google Translate quirks" section) — clear any stale value up front so this test
+    // (and a fresh view of the story) always starts from the real default state.
+    window.localStorage.removeItem("googtrans")
+
+    const trigger = canvas.getByRole("button", { name: /^Language\b/ })
+    const menu = canvasElement.querySelector("#translate") as HTMLElement
+    const french = await canvas.findByRole("menuitem", { name: "Français", hidden: true })
+    // The notice is created via JS on first use (not pre-rendered) and inserted at the
+    // configured anchor point — the top of <body> by default here — not necessarily inside
+    // canvasElement, since the whole point is that it doesn't have to live next to the trigger
+    // (e.g. trigger in the header, notice below it). Query the owner document, and only once
+    // it's actually been created.
+    const findNotice = (): HTMLElement | null =>
+      canvasElement.ownerDocument.querySelector("[data-translate-notice]")
+
+    await step("Menu starts closed; notice doesn't exist until a language is chosen", async () => {
+      await expect(menu.matches(":popover-open")).toBe(false)
+      await expect(findNotice()).toBeNull()
+    })
+
+    await step("Opens on trigger click, listing every language as a link", async () => {
+      await userEvent.click(trigger)
+      await waitFor(() => expect(menu.matches(":popover-open")).toBe(true))
+      await expect(french).toHaveAttribute("href", "?hl=fr")
+    })
+
+    await step(
+      "Choosing a language marks it current, updates the trigger, and shows the notice",
+      async () => {
+        await userEvent.click(french)
+        await waitFor(() => expect(french).toHaveAttribute("aria-current", "true"))
+        await expect(trigger).toHaveAttribute("aria-label", "Language: Français, FR")
+        await waitFor(() => expect(findNotice()).not.toHaveAttribute("hidden"))
+      },
+    )
+
+    await step("Restores original state", async () => {
+      await userEvent.click(trigger)
+      await waitFor(() => expect(menu.matches(":popover-open")).toBe(true))
+      await userEvent.click(canvas.getByRole("menuitem", { name: "English" }))
+      window.localStorage.removeItem("googtrans")
+    })
+  },
+}

package/src/Component/Translate/Translate.tsx

@@ -0,0 +1,213 @@
+import { JSX, KeyboardEvent, MouseEvent, useEffect, useId, useMemo, useRef } from "react"
+import { FocusScope, useFocusManager } from "react-aria"
+import classNames from "classnames"
+import { PopoverPlacementModifier } from "@pnx-mixtape/ids-shape"
+import Icon from "../../Atom/Icon/Icon"
+import { Icons } from "../../enums"
+import { GoogleTranslateWidget } from "../../Utility/utilities"
+import { TranslateLanguage } from "./languages"
+
+type TranslateItemsProps = {
+  languages: TranslateLanguage[]
+  onSelect: (code: string, event: MouseEvent<HTMLAnchorElement>) => void
+}
+
+const TranslateItems = ({ languages, onSelect }: TranslateItemsProps): JSX.Element => {
+  const focusManager = useFocusManager()
+
+  const handleKeyDown = (event: KeyboardEvent<HTMLAnchorElement>): void => {
+    switch (event.key) {
+      case "ArrowDown":
+      case "ArrowRight":
+        event.preventDefault()
+        focusManager?.focusNext({ wrap: true, tabbable: true })
+        break
+      case "ArrowUp":
+      case "ArrowLeft":
+        event.preventDefault()
+        focusManager?.focusPrevious({ wrap: true, tabbable: true })
+        break
+      default:
+        break
+    }
+  }
+
+  return (
+    <>
+      {languages.map(language => (
+        <a
+          key={language.code}
+          className="mx-translate__item"
+          href={`?hl=${language.code}`}
+          lang={language.code}
+          hrefLang={language.code}
+          role="menuitem"
+          data-language={language.code}
+          onClick={event => onSelect(language.code, event)}
+          onKeyDown={handleKeyDown}
+        >
+          {language.label}
+        </a>
+      ))}
+    </>
+  )
+}
+
+type TranslateProps = {
+  id?: string
+  label?: string
+  /** The language list — no built-in default, import `DEFAULT_LANGUAGES` from this component to opt into one. */
+  languages: TranslateLanguage[]
+  defaultLanguage?: string
+  /** Paths where translation is disallowed — the blocked notice shows instead. */
+  blockedPaths?: string[]
+  scriptUrl?: string
+  storageKey?: string
+  /**
+   * Updates the trigger's visible language code + `aria-label` to reflect the active language.
+   * On by default — pass `false` to keep the trigger static instead, which some sites prefer.
+   */
+  updateTriggerLabel?: boolean
+  /** Consumer-supplied copy shown once a non-default language is active — entirely opt-in, omit to never show a notice. */
+  noticeContent?: string
+  /** Consumer-supplied copy shown instead, on a blocked path. */
+  noticeBlockedContent?: string
+  /** Where to insert the notice. Defaults to the top of `<body>` if omitted — the notice doesn't have to live near this component, e.g. if the trigger is in the header. */
+  noticeAnchor?: string
+  /** Insertion position relative to `noticeAnchor`. Defaults to `afterend` when set, `afterbegin` otherwise. */
+  noticePosition?: InsertPosition
+  placement?: PopoverPlacementModifier
+  className?: string
+  /** Closes the menu after a language is chosen. */
+  closeOnSelect?: boolean
+  onOpen?: () => void
+  onClose?: () => void
+  onLanguageChange?: (code: string) => void
+}
+
+const Translate = ({
+  id,
+  label = "Language",
+  languages,
+  defaultLanguage = "en",
+  blockedPaths,
+  scriptUrl,
+  storageKey,
+  updateTriggerLabel = true,
+  noticeContent,
+  noticeBlockedContent,
+  noticeAnchor,
+  noticePosition,
+  placement = PopoverPlacementModifier.BOTTOM_START,
+  className,
+  closeOnSelect = true,
+  onOpen,
+  onClose,
+  onLanguageChange,
+}: TranslateProps): JSX.Element => {
+  const generatedId = useId()
+  const rootId = id ?? generatedId
+  const rootRef = useRef<HTMLDivElement>(null)
+  const popoverRef = useRef<HTMLDivElement>(null)
+  const widgetRef = useRef<GoogleTranslateWidget | null>(null)
+  const polyfillRef = useRef<any>(null)
+
+  const triggerStyle = useMemo(() => ({ anchorName: `--${rootId}` }), [rootId])
+  const popoverStyle = useMemo(() => ({ positionAnchor: `--${rootId}` }), [rootId])
+
+  useEffect(() => {
+    if (!rootRef.current) return undefined
+    const widget = new GoogleTranslateWidget(rootRef.current, {
+      defaultLanguage,
+      blockedPaths,
+      scriptUrl,
+      storageKey,
+      updateTriggerLabel,
+      notice: noticeContent
+        ? {
+            content: noticeContent,
+            blockedContent: noticeBlockedContent,
+            anchorSelector: noticeAnchor,
+            position: noticePosition,
+          }
+        : undefined,
+      onLanguageChange,
+    })
+    widget.init()
+    widgetRef.current = widget
+    return () => widget.destroy()
+    // oxlint-disable-next-line react-hooks/exhaustive-deps -- only re-runs on mount/unmount; config changes apply on the next setLanguage call
+  }, [])
+
+  useEffect(() => {
+    const popover = popoverRef.current
+    if (!popover) return undefined
+
+    const polyfill = async (): Promise<void> => {
+      if (
+        !("anchorName" in document.documentElement.style) ||
+        !("popover" in HTMLElement.prototype)
+      ) {
+        const { default: Polyfills } = await import("../Popover/polyfills")
+        polyfillRef.current = new Polyfills(popover)
+      }
+    }
+    polyfill().catch(() => {})
+
+    const controller = new AbortController()
+    popover.addEventListener(
+      "toggle",
+      (event: Event) => {
+        const { newState } = event as ToggleEvent
+        if (newState === "open") onOpen?.()
+        else onClose?.()
+      },
+      { signal: controller.signal },
+    )
+
+    return () => {
+      controller.abort()
+      polyfillRef.current?.destroy()
+    }
+  }, [onOpen, onClose])
+
+  const handleSelect = (code: string, event: MouseEvent<HTMLAnchorElement>): void => {
+    event.preventDefault()
+    widgetRef.current?.setLanguage(code)
+    if (closeOnSelect) popoverRef.current?.hidePopover()
+  }
+
+  return (
+    <div ref={rootRef} className={classNames("mx-translate", className)}>
+      <button
+        type="button"
+        id={`${rootId}-target`}
+        className="mx-translate__trigger mx-popover__trigger notranslate"
+        popoverTarget={rootId}
+        style={triggerStyle}
+        data-label={label}
+        aria-label={`${label}, ${defaultLanguage.toUpperCase()}`}
+      >
+        <Icon icon={Icons.GLOBE} />
+        <span className="mx-translate__code">{defaultLanguage.toUpperCase()}</span>
+      </button>
+      <div
+        ref={popoverRef}
+        id={rootId}
+        className="mx-popover mx-translate__menu notranslate"
+        aria-describedby={`${rootId}-target`}
+        aria-labelledby={`${rootId}-target`}
+        style={popoverStyle}
+        data-placement={placement}
+        popover=""
+        role="menu"
+      >
+        <FocusScope>
+          <TranslateItems languages={languages} onSelect={handleSelect} />
+        </FocusScope>
+      </div>
+    </div>
+  )
+}
+
+export default Translate