useTranslator

React adapter for @web-ai-sdk/translator. Auto-translates input from sourceLanguage to targetLanguage and re-runs whenever the inputs change. For the conceptual overview see Translator.

Before shipping, review the Production checklist for safe rendering, progress, reversible changes, and cache freshness.

To warm the session before the hook first runs, call prepareTranslator from the core package on user intent. See the Session lifecycle guide.

Live demo

Type in the source field. The demo debounces typing: translation runs 600 ms after you pause, not on every keystroke. Repeat inputs come from a ten-minute result cache; use “Fresh run” to bypass it.

Usage

import { useTranslator } from "@web-ai-sdk/translator/react";

export function Translation({ text }: { text: string }) {
  const { status, output } = useTranslator({
    input: text,
    sourceLanguage: "en",
    targetLanguage: "pt",
  });

  if (status === "unavailable") return null;
  return <p>{output}</p>;
}

The hook auto-runs whenever any input changes. Empty input or matching source/target keeps the hook in "idle".

State machine

idle ───► loading ───► streaming ───► done
                                        │
unavailable ◄── (no API)                │
                                        ▼
                             input empty ─► idle

• idle: hook mounted, input empty or sourceLanguage === targetLanguage.
• loading: translation in flight (~1-3s cold for a new language pair, sub-second warm).
• streaming: partial output arriving. output holds the cumulative translation and grows as chunks land.
• done: translation complete. output is the translated text or null.
• unavailable: API missing. Render nothing or a fallback.

Implementations without native translateStreaming() skip "streaming" and move straight to "done".

Caching

const { output, fromCache } = useTranslator({
  input: text,
  sourceLanguage: "en",
  targetLanguage: "pt",
  cache: "session",
});

fromCache is true when the cache served the result. Pass "session" / "local" for the matching web-storage shortcut, or any { get, set }-shaped object for a custom backend.

Built-in "session" / "local" entries expire after one hour by default. Pass cacheTtl (milliseconds) to change the TTL per call. Pass cacheRefresh: true to skip the read and replace the cached value after a successful run. Custom { get, set } caches own their expiry policy.

Aborting

The hook aborts any in-flight call when inputs change or the component unmounts. You don’t need to manage AbortController directly. The abort signal is forwarded to the native operation, so browsers that honor it stop translating promptly. Stale partial output from a cancelled run is never published.

Reference

import type { UseTranslatorOptions, UseTranslatorReturn, TranslatorStatus } from "@web-ai-sdk/translator/react";

type TranslatorStatus = "idle" | "loading" | "streaming" | "done" | "unavailable";

interface UseTranslatorOptions extends Omit<TranslateOptions, "onUpdate" | "signal"> {
  enabled?: boolean;       // default: true
  // Inherited from TranslateOptions:
  input: string;
  sourceLanguage: string;
  targetLanguage?: string;
  monitor?: (m: TranslatorMonitor) => void;
  cache?: "session" | "local" | { get, set };
  cacheKey?: string;
  cacheTtl?: number;       // built-in shortcut TTL in ms; default 1 hour
  cacheRefresh?: boolean;  // skip the cache read, write the fresh result
}

interface UseTranslatorReturn {
  status: TranslatorStatus;
  output: string | null;
  error: Error | null;
  fromCache: boolean;
}

declare const useTranslator: (options: UseTranslatorOptions) => UseTranslatorReturn;

Source: packages/translator/src/react/index.ts.