Translator.translateStreaming() — Methode · JavaScript-Referenz

Signatur

Translator.prototype.translateStreaming(input, options)

Beschreibung

translateStreaming() gehört zur Translator API, mit der Webseiten Texte direkt im Browser übersetzen können. Die Übersetzung läuft über ein lokales Modell auf dem Gerät. Der Text muss also nicht an einen externen Dienst gesendet werden. Anders als translate(), das auf die fertige Übersetzung wartet und sie als Promise zurückgibt, liefert translateStreaming() sofort einen ReadableStream. Aus diesem Stream kommen die übersetzten Textstücke, sobald das Modell sie erzeugt hat.

Die Methode eignet sich vor allem für längere Texte wie Artikel, Kommentare oder Chatverläufe. Nutzer sehen erste Ergebnisse früher, und die Oberfläche wirkt schneller. Bei kurzen Texten wie einzelnen Wörtern oder Beschriftungen ist translate() meist einfacher.

Voraussetzung ist eine Translator-Instanz, die du mit Translator.create({ sourceLanguage, targetLanguage }) erzeugst. Vorher solltest du mit Translator.availability() prüfen, ob das Sprachpaar unterstützt wird und ob das Modell erst heruntergeladen werden muss. In der aktuellen Umsetzung sind die Stücke inkrementell: Jedes Stück enthält nur neuen Text und wird an den bisherigen Text angehängt.

Parameter

Name	Typ	Default	Beschreibung
$input Pflicht	string		Der Text, der aus der `sourceLanguage` in die `targetLanguage` der Instanz übersetzt werden soll.
$options	object	{}	Optionales Objekt mit Einstellungen für diesen Aufruf.
$options.signal	AbortSignal		Signal eines `AbortController`, mit dem du eine laufende Übersetzung abbrechen kannst. Der Stream bricht dann mit einem `AbortError` ab.

Rückgabewert

Typ

ReadableStream<string>

Beschreibung

Ein ReadableStream, der die Übersetzung in Textstücken liefert. Du kannst ihn mit for await...of oder über getReader() auslesen. Fehler, etwa bei Abbruch oder zu langer Eingabe, treten beim Lesen aus dem Stream auf.

Beispiele

Artikel schrittweise übersetzen und anzeigen

const output = document.querySelector('#uebersetzung');

const translator = await Translator.create({
  sourceLanguage: 'en',
  targetLanguage: 'de'
});

const text = 'The Translator API lets web pages translate text on the device. No server round trip is needed.';
const stream = translator.translateStreaming(text);

output.textContent = '';
for await (const chunk of stream) {
  // Stücke sind inkrementell – einfach anhängen
  output.textContent += chunk;
}
console.log('Fertig:', output.textContent);

Fertig: Mit der Translator API können Webseiten Text auf dem Gerät übersetzen. Es ist kein Serveraufruf nötig.

Verfügbarkeit prüfen und Modell-Download überwachen

const opts = { sourceLanguage: 'en', targetLanguage: 'de' };

if (!('Translator' in self)) {
  console.log('Translator API nicht unterstützt');
} else {
  const status = await Translator.availability(opts);
  console.log('Status:', status); // 'available', 'downloadable', 'downloading', 'unavailable'

  if (status !== 'unavailable') {
    // Wenn ein Download nötig ist, muss create() durch eine Nutzeraktion (z. B. Klick) ausgelöst werden
    const translator = await Translator.create({
      ...opts,
      monitor(m) {
        m.addEventListener('downloadprogress', (e) => {
          console.log(`Download: ${Math.round(e.loaded * 100)} %`);
        });
      }
    });

    let result = '';
    for await (const chunk of translator.translateStreaming('Good morning!')) {
      result += chunk;
    }
    console.log(result);
  }
}

Status: available Guten Morgen!

Übersetzung per AbortController abbrechen

const translator = await Translator.create({ sourceLanguage: 'en', targetLanguage: 'de' });
const controller = new AbortController();

document.querySelector('#abbrechen')
  .addEventListener('click', () => controller.abort());

try {
  const stream = translator.translateStreaming(longEnglishText, {
    signal: controller.signal
  });
  for await (const chunk of stream) {
    document.querySelector('#out').append(chunk);
  }
} catch (err) {
  if (err.name === 'AbortError') {
    console.log('Übersetzung abgebrochen');
  } else {
    throw err;
  }
}

Übersetzung abgebrochen

Eingabelänge vorab prüfen

const translator = await Translator.create({ sourceLanguage: 'en', targetLanguage: 'de' });
const text = document.querySelector('textarea').value;

const usage = await translator.measureInputUsage(text);
if (usage > translator.inputQuota) {
  console.warn('Text zu lang – bitte in Abschnitte aufteilen');
} else {
  const reader = translator.translateStreaming(text).getReader();
  let result = '';
  while (true) {
    const { done, value } = await reader.read();
    if (done) break;
    result += value;
  }
  console.log(result);
}

// Wichtig · Fallstricke

Browser-Unterstützung: Die API ist experimentell und kein Baseline-Feature. Sie ist in Chromium-Browsern ab Version 138 auf dem Desktop verfügbar. Firefox und Safari unterstützen sie bisher nicht. Prüfe deshalb immer vorher mit 'Translator' in self.
Einschränkungen: Die API funktioniert nur in einem sicheren Kontext (HTTPS) und im Fenster-Kontext, nicht in Workern. In iframes muss die Permissions Policy translator sie erlauben.
Nutzeraktion für den Download: Wenn availability() den Wert 'downloadable' oder 'downloading' meldet, muss Translator.create() durch eine Nutzeraktion wie einen Klick ausgelöst werden.
Stücke nicht überschreiben: Die Stücke sind inkrementell. Hänge sie also mit += an, statt den bisherigen Text zu ersetzen.
Fehler treten im Stream auf: Umschließe die Lese-Schleife mit try/catch, nicht nur den Methodenaufruf. Typische Fehler sind:
- AbortError bei einem Abbruch über signal,
- QuotaExceededError, wenn die Eingabe größer als inputQuota ist,
- InvalidStateError, wenn das Dokument nicht aktiv ist oder destroy() bereits aufgerufen wurde.
Ressourcen freigeben: Die Modelle belegen viel Speicher. Rufe translator.destroy() auf, wenn du die Instanz nicht mehr brauchst.
Qualität: Die Übersetzung stammt von einem lokalen KI-Modell. Sie kann ungenau sein und kann sich zwischen Browser-Versionen unterscheiden. Für rechtlich verbindliche Texte ist sie nicht geeignet.
Sicherheit: Füge die übersetzten Stücke per textContent oder append() ein, nicht per innerHTML. Sonst kann HTML aus dem Eingabetext in der Ausgabe landen und ausgeführt werden (XSS-Risiko).

Siehe auch

Translator.translate() Translator.availability() Translator.create() Translator.destroy() Translator.measureInputUsage() FileSystemWritableFileStream.seek() TrustedHTML.toString()