Translator

When to useCopy Anchor Link

• The user asks to translate text: an email, a menu, a sign, a phrase they want to say.
• The user may want to tweak the source, switch languages or compare phrasings.

When not to useCopy Anchor Link

• The user asks what a single word means in their own language. Answer in text.
• The text is a whole document. Translate it as a file.
• The agent doesn't have a translation from its translation tool yet. Get it first; never make up the target text.

How the agent should use itCopy Anchor Link

• The translation comes from the tool. target.text, alternatives and transliteration are data-bound: they come from the agent's translation tool, never from the browser. The component never translates anything itself.
• Pass the source text exactly as given, and set source.detected: true when the language was inferred, so the source pane shows a "Detected" badge.
• Set formality only for languages that distinguish it (Spanish, French, German, Japanese, Korean…), to the register used. The card then offers a Formal / Informal toggle.
• Add a transliteration for non-Latin targets when the user wants to say it aloud (romaji, pinyin).
• Keep notes to real usage differences, such as region or register, at most three. Use glossary for names and terms kept consistent (dish names, product terms).
• On translate, translate the returned text from from to to (with the formality, when present) and re-render the card with the new props. On choose, use that phrasing from then on.
• Lifecycle: a translation is a snapshot, so it needs none of expiresAt or fetchedAt. When the agent answers a translate request with a new card instead of re-rendering this one, mark the old call superseded by the new one.

InteractionCopy Anchor Link

The translator never locks: the user can keep editing and asking for new translations.

The language pickers lead the card (the pair is also its screen-reader heading). A short translation (80 characters or fewer) is shown large, since it's the answer itself. notes and glossary sit behind one collapsed "Notes" / "Glossary" disclosure, so the translation leads.

Reading order and pronunciationCopy Anchor Link

• The translation carries lang set to its language, so screen readers pronounce it correctly; the transliteration carries lang="ja-Latn" (and so on), and the source textarea carries the source language.
• dir comes from Intl.Locale text info (rtl for Arabic or Hebrew), or auto where the browser can't tell.
• Two panes sit side by side on wide cards and stack on narrow ones.

InstallationCopy Anchor Link

npx shadcn@latest add https://your-site.com/r/translator.json

UsageCopy Anchor Link

import { tool } from "ai"
import { translatorTool } from "@/components/genui/translator.schema"

const tools = {
  [translatorTool.name]: tool({
    description: translatorTool.description,
    inputSchema: translatorTool.inputSchema,
  }),
}

When the user edits and presses Translate, the agent receives:

{ action: "translate", text: "Hi Marta, …", from: "en", to: "es", formality: "informal" }

Translate it and re-render the same card with the new source and target (the card shows "Translating…" until the props change), or answer with a new card. Picking an alternative sends:

{ action: "choose", text: "駅はどちらですか？" }

With LangGraphCopy Anchor Link

Push it from a graph node with ui.push({ name: "translate_text", props: { toolCallId, ...args } }, { message }), and render the thread's UI messages with the Renderer. To answer a translate result in place, push again with the same id and the new props.

Restoring from historyCopy Anchor Link

Pass the last stored result as result. A translate result restores the edited text and languages with "Asked for a new translation."; a choose result restores the chosen alternative. It is never sent again, and the card stays usable.

<Translator
  {...part.input}
  result={part.state === "output-available" ? part.output : undefined}
/>

HelpersCopy Anchor Link

translator-utils.ts holds the pure logic, usable on the server: languageName (with a fallback when Intl.DisplayNames is missing), languageOptions, textDirection, charCount (graphemes), deriveView (out-of-date and swap detection), swapDraft and pickVoice.

SchemaCopy Anchor Link

Host props: status (streaming, ready, translating), onResult, result and className.

SourceCopy Anchor Link