use-builtin-ai

Translate text on-device with Chrome's built-in Translator API.


Package	`@vizejs/composable/use-builtin-ai`
Own the source	`vize lib pull composable:use-builtin-ai`
Runtime exports	`useLanguageDetector`, `useSummarizer`, `useTranslator`
Gzip budget	3072 B

Usage

import { useLanguageDetector, useSummarizer, useTranslator } from "@vizejs/composable/use-builtin-ai";

Runtime contract

Utility	Category	Stability	SSR	Hydration	Cleanup	Targets	Host globals	Uses
`useTranslator`	i18n	experimental	deterministic-fallback	caller-managed	reactive-scope, caller	web, desktop	`AbortController`, `DOMException`, `window`	`tryOnScopeDispose`
`useLanguageDetector`	i18n	experimental	deterministic-fallback	caller-managed	reactive-scope, caller	web, desktop	`AbortController`, `DOMException`, `window`	`tryOnScopeDispose`
`useSummarizer`	system	experimental	deterministic-fallback	caller-managed	reactive-scope, caller	web, desktop	`AbortController`, `DOMException`, `window`	`tryOnScopeDispose`

API

`useTranslator`

Translate text on-device with Chrome's built-in Translator API. The session is created lazily by the first translate (or explicitly by create(), which browsers require inside a user gesture when the model must be downloaded); downloadProgress follows the download. Changing a language destroys the session. The session is destroyed and a pending creation aborted when the owning reactive scope stops; outside a scope call destroy(). Server rendering: nothing is created, supported is false and status is "unsupported". Inside a component supported turns true only after mounting, so hydration renders this server state first.

function useTranslator(options: UseTranslatorOptions): TranslatorControls

const translator = useTranslator({ sourceLanguage: "en", targetLanguage: "ja" });
const japanese = await translator.translate("Hello");

`useLanguageDetector`

Detect the language of text on-device with Chrome's built-in LanguageDetector API. Shares the lifecycle of useTranslator: lazy creation, download progress, destruction with the owning reactive scope. Server rendering: nothing is created, supported is false and status is "unsupported". Inside a component supported turns true only after mounting, so hydration renders this server state first.

function useLanguageDetector( options: UseLanguageDetectorOptions = {}, ): LanguageDetectorControls

const detector = useLanguageDetector();
const [best] = await detector.detect(input.value);

`useSummarizer`

Summarize text on-device with Chrome's built-in Summarizer API. Shares the lifecycle of useTranslator: lazy creation, download progress, destruction with the owning reactive scope; changing type, format, length or sharedContext destroys the session. Server rendering: nothing is created, supported is false and status is "unsupported". Inside a component supported turns true only after mounting, so hydration renders this server state first.

function useSummarizer(options: UseSummarizerOptions = {}): SummarizerControls

const summarizer = useSummarizer({ type: "tldr", length: "medium" });
for await (const chunk of summarizer.summarizeStreaming(article.value)) output.value += chunk;

Types

`BuiltinAiDownloadProgressEvent`

downloadprogress event: loaded is a fraction of total (usually 1).

Member	Type	Description
`loaded`	`number`	Downloaded amount.
`total`?	`number \| undefined`	Total amount (1 in current browsers).

`BuiltinAiMonitorLike`

Monitor handed to the monitor callback of create().

Member	Type	Description
`addEventListener`	`(type: "downloadprogress", listener: (event: BuiltinAiDownloadProgressEvent) => void) => void`	Subscribe to model download progress.

`BuiltinAiCreateMonitorOptions`

Options added by the composables to every create() call.

Member	Type	Description
`monitor`	`(monitor: BuiltinAiMonitorLike) => void`	Receives the download monitor.
`signal`	`AbortSignal`	Aborts creation when the session is destroyed.

`BuiltinAiSessionControls`

Common state and actions of every built-in AI composable.

Member	Type	Description
`supported`	`ComputedRef<boolean>`	Whether the API's global constructor is available.
`status`	`ComputedRef<BuiltinAiStatus>`	Session lifecycle.
`downloadProgress`	`Readonly<Ref<number>>`	Model download progress (0..1) during `create()`.
`error`	`Readonly<ShallowRef<unknown>>`	Most recent failure, cleared by the next successful call.
`availability`	`() => Promise<BuiltinAiAvailability>`	Ask whether the model for the current options is usable.
`create`	`() => Promise<boolean>`	Create the session (downloading the model when needed). Browsers require a user gesture for a download. Operations create it lazily.
`destroy`	`() => void`	Destroy the session and abort a pending creation. Repeated calls are safe.

`TranslatorLike`

Minimal Translator instance.

Member	Type	Description
`translate`	`(input: string) => Promise<string>`	Translate `input`.
`translateStreaming`	`(input: string) => BuiltinAiTextStream`	Translate `input`, streaming chunks.
`destroy`	`() => void`	Release the session.

`TranslatorLanguages`

Language pair of a translator.

Member	Type	Description
`sourceLanguage`	`string`	BCP 47 source language.
`targetLanguage`	`string`	BCP 47 target language.

`TranslatorHost`

Minimal global Translator class (static methods).

Member	Type	Description
`availability`	`(options: TranslatorLanguages) => Promise<BuiltinAiAvailability>`	Availability of a language pair.
`create`	`(options: TranslatorLanguages & BuiltinAiCreateMonitorOptions) => Promise<TranslatorLike>`	Create a translator.

`UseTranslatorOptions`

Options for useTranslator.

Member	Type	Description
`sourceLanguage`	`MaybeRefOrGetter<string>`	BCP 47 source language; a change destroys the current session.
`targetLanguage`	`MaybeRefOrGetter<string>`	BCP 47 target language; a change destroys the current session.
`host`?	`MaybeRef<TranslatorHost \| null \| undefined>`	`Translator` class. A ref (not a getter) because the host is a class.

`TranslatorControls`

State and actions returned by useTranslator.

Member	Type	Description
`supported`	`ComputedRef<boolean>`	Whether the API's global constructor is available.
`status`	`ComputedRef<BuiltinAiStatus>`	Session lifecycle.
`downloadProgress`	`Readonly<Ref<number>>`	Model download progress (0..1) during `create()`.
`error`	`Readonly<ShallowRef<unknown>>`	Most recent failure, cleared by the next successful call.
`availability`	`() => Promise<BuiltinAiAvailability>`	Ask whether the model for the current options is usable.
`create`	`() => Promise<boolean>`	Create the session (downloading the model when needed). Browsers require a user gesture for a download. Operations create it lazily.
`destroy`	`() => void`	Destroy the session and abort a pending creation. Repeated calls are safe.
`translate`	`(text: string) => Promise<string>`	Translate text, creating the session on first use. Rejects with a tagged `Error` when unsupported or with the host's failure.
`translateStreaming`	`(text: string) => AsyncIterable<string>`	Translate text as a stream of chunks.

`LanguageDetectionResult`

One candidate returned by LanguageDetector.detect.

Member	Type	Description
`detectedLanguage`	`string`	BCP 47 language tag (`"und"` for unknown).
`confidence`	`number`	Confidence between 0 and 1.

`LanguageDetectorLike`

Minimal LanguageDetector instance.

Member	Type	Description
`detect`	`(input: string) => Promise<readonly LanguageDetectionResult[]>`	Rank candidate languages for `input`.
`destroy`	`() => void`	Release the session.

`LanguageDetectorCreateOptions`

Creation options of a language detector.

Member	Type	Description
`expectedInputLanguages`?	`readonly string[]`	Languages the input is expected to be in.

`LanguageDetectorHost`

Minimal global LanguageDetector class (static methods).

Member	Type	Description
`availability`	`(options: LanguageDetectorCreateOptions) => Promise<BuiltinAiAvailability>`	Availability of the detector.
`create`	`(options: LanguageDetectorCreateOptions & BuiltinAiCreateMonitorOptions) => Promise<LanguageDetectorLike>`	Create a detector.

`UseLanguageDetectorOptions`

Options for useLanguageDetector.

Member	Type	Description
`expectedInputLanguages`?	`MaybeRefOrGetter<readonly string[] \| undefined>`	Languages the input is expected to be in; a change destroys the session.
`host`?	`MaybeRef<LanguageDetectorHost \| null \| undefined>`	`LanguageDetector` class.

`LanguageDetectorControls`

State and actions returned by useLanguageDetector.

Member	Type	Description
`supported`	`ComputedRef<boolean>`	Whether the API's global constructor is available.
`status`	`ComputedRef<BuiltinAiStatus>`	Session lifecycle.
`downloadProgress`	`Readonly<Ref<number>>`	Model download progress (0..1) during `create()`.
`error`	`Readonly<ShallowRef<unknown>>`	Most recent failure, cleared by the next successful call.
`availability`	`() => Promise<BuiltinAiAvailability>`	Ask whether the model for the current options is usable.
`create`	`() => Promise<boolean>`	Create the session (downloading the model when needed). Browsers require a user gesture for a download. Operations create it lazily.
`destroy`	`() => void`	Destroy the session and abort a pending creation. Repeated calls are safe.
`detect`	`(text: string) => Promise<readonly LanguageDetectionResult[]>`	Detect the language of text, creating the session on first use.

`SummarizerCreateOptions`

Creation options of a summarizer.

Member	Type	Description
`type`	`SummarizerType`	Summary kind.
`format`	`SummarizerFormat`	Output format.
`length`	`SummarizerLength`	Output length.
`sharedContext`?	`string`	Background shared by every summary.

`SummarizeCallOptions`

Per-call options of summarize.

Member	Type	Description
`context`?	`string`	Background for this input only.

`SummarizerLike`

Minimal Summarizer instance.

Member	Type	Description
`summarize`	`(input: string, options?: SummarizeCallOptions) => Promise<string>`	Summarize `input`.
`summarizeStreaming`	`(input: string, options?: SummarizeCallOptions) => BuiltinAiTextStream`	Summarize `input`, streaming chunks.
`destroy`	`() => void`	Release the session.

`SummarizerHost`

Minimal global Summarizer class (static methods).

Member	Type	Description
`availability`	`(options: SummarizerCreateOptions) => Promise<BuiltinAiAvailability>`	Availability of the summarizer.
`create`	`(options: SummarizerCreateOptions & BuiltinAiCreateMonitorOptions) => Promise<SummarizerLike>`	Create a summarizer.

`UseSummarizerOptions`

Options for useSummarizer.

Member	Type	Description
`type`?	`MaybeRefOrGetter<SummarizerType>`	Summary kind; a change destroys the session.
`format`?	`MaybeRefOrGetter<SummarizerFormat>`	Output format; a change destroys the session.
`length`?	`MaybeRefOrGetter<SummarizerLength>`	Output length; a change destroys the session.
`sharedContext`?	`MaybeRefOrGetter<string \| undefined>`	Background shared by every summary; a change destroys the session.
`host`?	`MaybeRef<SummarizerHost \| null \| undefined>`	`Summarizer` class.

`SummarizerControls`

State and actions returned by useSummarizer.

Member	Type	Description
`supported`	`ComputedRef<boolean>`	Whether the API's global constructor is available.
`status`	`ComputedRef<BuiltinAiStatus>`	Session lifecycle.
`downloadProgress`	`Readonly<Ref<number>>`	Model download progress (0..1) during `create()`.
`error`	`Readonly<ShallowRef<unknown>>`	Most recent failure, cleared by the next successful call.
`availability`	`() => Promise<BuiltinAiAvailability>`	Ask whether the model for the current options is usable.
`create`	`() => Promise<boolean>`	Create the session (downloading the model when needed). Browsers require a user gesture for a download. Operations create it lazily.
`destroy`	`() => void`	Destroy the session and abort a pending creation. Repeated calls are safe.
`summarize`	`(text: string, options?: SummarizeCallOptions) => Promise<string>`	Summarize text, creating the session on first use.
`summarizeStreaming`	`( text: string, options?: SummarizeCallOptions, ) => AsyncIterable<string>`	Summarize text as a stream of chunks.