Translator.create() — Methode · JavaScript-Referenz

Signatur

Translator.create(options)

Beschreibung

Die statische Methode Translator.create() ist der Einstiegspunkt der Translator API, einer eingebauten KI-Schnittstelle des Browsers. Damit wird Text direkt auf dem Gerät übersetzt, ohne einen externen Übersetzungsdienst aufzurufen. Du gibst die Ausgangs- und die Zielsprache als BCP-47-Sprachcodes an (z. B. "en", "de", "ja") und bekommst ein Promise, das sich mit einem einsatzbereiten Translator-Objekt erfüllt.

Ist das Sprachmodell noch nicht lokal vorhanden, stößt create() den Download an. Über die Option monitor kannst du ein downloadprogress-Ereignis abonnieren und den Fortschritt anzeigen. Vorher solltest du mit Translator.availability() prüfen, ob das Sprachpaar "available", "downloadable", "downloading" oder "unavailable" ist. Ist ein Download nötig, muss create() nach einer Nutzeraktivierung aufgerufen werden, zum Beispiel in einem Klick-Handler.

Mit der erzeugten Instanz übersetzt du anschließend mit translate() oder, bei langen Texten, mit translateStreaming(). Wird die Instanz nicht mehr gebraucht, gibst du ihre Ressourcen mit destroy() frei. Ein laufender create()-Aufruf lässt sich über ein AbortSignal abbrechen.

Parameter

Name	Typ	Beschreibung
$options Pflicht	Object	Konfigurationsobjekt mit den folgenden Eigenschaften.
$options.sourceLanguage Pflicht	string	BCP-47-Sprachcode des Ausgangstexts, z. B. `"en"`.
$options.targetLanguage Pflicht	string	BCP-47-Sprachcode der Zielsprache, z. B. `"de"`.
$options.monitor	(monitor: CreateMonitor) => void	Callback, das ein `CreateMonitor`-Objekt erhält. Darauf lässt sich `downloadprogress` abonnieren (`event.loaded` liegt zwischen 0 und 1).
$options.signal	AbortSignal	Signal zum Abbrechen der Erstellung bzw. des Modell-Downloads.

Rückgabewert

Typ

Promise<Translator>

Beschreibung

Promise, das sich mit einer einsatzbereiten Translator-Instanz erfüllt. Es wird abgelehnt mit NotAllowedError (fehlende Nutzeraktivierung, Permissions Policy blockiert), NotSupportedError (Sprachpaar nicht unterstützt), AbortError (abgebrochen) oder OperationError/NetworkError (Download oder Initialisierung fehlgeschlagen).

Beispiele

Einfache Übersetzung mit Verfügbarkeitsprüfung

if ('Translator' in self) {
  const options = { sourceLanguage: 'en', targetLanguage: 'de' };
  const status = await Translator.availability(options);

  if (status === 'available') {
    const translator = await Translator.create(options);
    const result = await translator.translate('Where is the train station?');
    console.log(result);
    translator.destroy();
  } else {
    console.log('Status:', status);
  }
} else {
  console.log('Translator API wird nicht unterstützt');
}

Wo ist der Bahnhof?

Modell-Download mit Fortschrittsanzeige nach Klick

const button = document.querySelector('#translate');
const progress = document.querySelector('progress');

button.addEventListener('click', async () => {
  // Nutzeraktivierung ist nötig, falls das Modell geladen werden muss
  const translator = await Translator.create({
    sourceLanguage: 'en',
    targetLanguage: 'fr',
    monitor(m) {
      m.addEventListener('downloadprogress', (e) => {
        progress.value = e.loaded; // 0 … 1
        console.log(`Download: ${Math.round(e.loaded * 100)} %`);
      });
    }
  });
  console.log(await translator.translate('Good morning'));
});

Download: 0 % Download: 57 % Download: 100 % Bonjour

Erstellung mit Timeout abbrechen und Fehler behandeln

try {
  const translator = await Translator.create({
    sourceLanguage: 'de',
    targetLanguage: 'ja',
    signal: AbortSignal.timeout(30_000)
  });
  const stream = translator.translateStreaming('Ein sehr langer Artikeltext …');
  for await (const chunk of stream) {
    console.log(chunk);
  }
} catch (err) {
  if (err.name === 'NotSupportedError') {
    console.warn('Sprachpaar nicht unterstützt');
  } else if (err.name === 'TimeoutError' || err.name === 'AbortError') {
    console.warn('Erstellung abgebrochen');
  } else {
    console.error(err);
  }
}

// Wichtig · Fallstricke

Experimentell: Derzeit nur in Chromium-basierten Desktop-Browsern (Chrome/Edge ab etwa Version 138) verfügbar. Firefox und Safari unterstützen die API bisher nicht. Prüfe die Unterstützung immer mit 'Translator' in self und sieh eine Ausweichlösung vor, zum Beispiel einen serverseitigen Dienst.
Nur in sicheren Kontexten (HTTPS) verfügbar. Für iframes gilt die Permissions Policy translator. In fremden iframes musst du sie mit allow="translator" freigeben.
Bei den Zuständen "downloadable" oder "downloading" ist eine Nutzeraktivierung erforderlich. Ohne sie wird das Promise mit NotAllowedError abgelehnt.
Der erste Download kann groß sein und lange dauern. Zeig deshalb einen Fortschritt über monitor an und rufe create() nicht bei jedem Seitenaufruf vorsorglich auf.
Translator.availability() kann aus Datenschutzgründen "downloadable" melden, obwohl das Modell schon vorhanden ist. So wird Fingerprinting erschwert.
Pro Sprachpaar ist eine eigene Instanz nötig. Die Spracherkennung übernimmt die separate LanguageDetector-API.
Gib nicht mehr benötigte Instanzen mit destroy() frei, um Arbeitsspeicher zu sparen.

Siehe auch

Translator Translator.availability() Translator.prototype.translate() Translator.prototype.translateStreaming() Translator.prototype.destroy()