Translation
Translate text using Chrome built-in Gemini Nano
Translation
Chrome AI provides on-device text translation via the built-in Translator API. Your app ships and fetches no model files — Chrome supplies a language pack per directed pair, downloading it once browser-wide on first use.
See it in action
The Translator block runs Chrome AI translation (with Transformers.js Opus-MT fallback across 24 offline pairs) live in the browser.
Basic Usage
import { translate } from '@localmode/core';
import { chromeAI } from '@localmode/chrome-ai';
const { translation } = await translate({
model: chromeAI.translator({ targetLanguage: 'es' }),
text: 'Hello, how are you?',
});
console.log(translation); // "Hola, ¿cómo estás?"Language Configuration
// English to German
const deTranslator = chromeAI.translator({
sourceLanguage: 'en',
targetLanguage: 'de',
});
// English to French
const frTranslator = chromeAI.translator({
sourceLanguage: 'en',
targetLanguage: 'fr',
});Override Language at Call Time
const translator = chromeAI.translator();
const { translation } = await translate({
model: translator,
text: 'Good morning',
sourceLanguage: 'en',
targetLanguage: 'ja',
});Batch Translation
import { translateMany } from '@localmode/core';
const { translations } = await translateMany({
model: chromeAI.translator({ targetLanguage: 'de' }),
texts: ['Hello', 'Goodbye', 'Thank you'],
});
console.log(translations); // ["Hallo", "Auf Wiedersehen", "Danke"]Model Availability & Download
Chrome downloads a separate language pack per directed pair, so availability must be re-checked whenever the pair changes:
// 'available' | 'downloadable' | 'downloading' | 'unavailable'
const state = await Translator.availability({ sourceLanguage: 'en', targetLanguage: 'fr' });When the pack is not present, chromeAI.translator() throws a TranslationError instead of
silently starting the download. Opt in with allowDownload, from a user activation:
const model = chromeAI.translator({
sourceLanguage: 'en',
targetLanguage: 'fr',
allowDownload: true,
onProgress: ({ loaded, total }) => console.log(loaded / total),
});useProviderFallback from @localmode/react probes translator availability per pair
(refreshChromeAvailability('translate', { source, target })) and exposes
requestChromeDownload for the click handler.
Errors
ChromeAITranslator throws a typed TranslationError from @localmode/core when
self.Translator is absent, when Chrome reports the pair unavailable, or when the pack
needs downloading and allowDownload was not set. Streaming and quota calls add the codes
chrome-ai-streaming-not-supported and chrome-ai-measure-not-supported (retryable: false)
and chrome-ai-translation-failed (Chrome's error as cause).
Streaming
doStreamTranslate() streams one translation through Chrome's translateStreaming(), each
chunk stamped with performance.now(); the last item carries timing (requestedAt,
firstChunkAt, endedAt, chunkCount, chars) and usage.
const model = chromeAI.translator({ sourceLanguage: 'en', targetLanguage: 'de' });
for await (const chunk of model.doStreamTranslate({ text: 'Good morning, everyone.' })) {
if (!chunk.done) output.textContent += chunk.text;
}Input Quota and Model Info
Per language pair (default: the settings pair):
const pair = { sourceLanguage: 'en', targetLanguage: 'de' };
await model.getInputQuota(pair); // number, or null if not exposed
await model.measureInputUsage('Hello', pair); // Chrome's own count
await model.getModelInfo(pair);
// { api: 'Translator', availabilityAtCreate, requestedOptions, sessionOptions,
// inputQuota, modelVersion: null, browser }Chrome 156 reports inputQuota as Infinity and measureInputUsage() as 0 for the Translator.
Chrome exposes no language-pack version to the page (modelVersion is null); read it from
chrome://components outside the page.
Session Caching
The Chrome AI translator caches sessions per language pair. Multiple translations with the same pair reuse the same session for efficiency.
const translator = chromeAI.translator();
// First call creates the en→es session
await translate({ model: translator, text: 'Hello', targetLanguage: 'es' });
// Second call reuses the cached session (instant)
await translate({ model: translator, text: 'Goodbye', targetLanguage: 'es' });
// Different pair creates a new session
await translate({ model: translator, text: 'Hello', targetLanguage: 'fr' });For full API reference, options, and result types, see the Core Translation guide.
Composed Block
| Block | Description | Links |
|---|---|---|
| Translator | Chrome AI translation with automatic Transformers.js fallback across 24 offline Opus-MT pairs | Live · Install: npx shadcn add @localmode/ui/blocks/writing-tools/translate |