LocalMode
Chrome AI

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

BlockDescriptionLinks
TranslatorChrome AI translation with automatic Transformers.js fallback across 24 offline Opus-MT pairsLive · Install: npx shadcn add @localmode/ui/blocks/writing-tools/translate

On this page