Translator — Schnittstelle · JavaScript-Referenz

Signatur

interface Translator

Beschreibung

Das Translator-Interface gehört zur Translator and Language Detector API und ermöglicht Übersetzungen direkt im Browser mit einem lokal ausgeführten Sprachmodell. Die Texte verlassen das Gerät dabei nicht, es fallen keine Kosten für einen Übersetzungsdienst an und nach dem Laden des Modells funktioniert die Übersetzung auch offline.

Der Ablauf besteht immer aus drei Schritten:

Verfügbarkeit prüfen mit der statischen Methode Translator.availability({ sourceLanguage, targetLanguage }). Sie liefert "unavailable", "downloadable", "downloading" oder "available".
Instanz erzeugen mit Translator.create(options). Falls nötig, wird dabei das Sprachpaket heruntergeladen. Den Fortschritt kannst du über den monitor-Callback und das Ereignis downloadprogress verfolgen.
Übersetzen mit translate(text) (liefert ein Promise<string>) oder mit translateStreaming(text) (liefert einen ReadableStream für lange Texte).

Jede Instanz gilt für genau ein Sprachpaar. Die Eigenschaften sourceLanguage, targetLanguage und inputQuota sind schreibgeschützt. Mit measureInputUsage(text) prüfst du vorab, ob ein Text in das Kontingent passt. destroy() gibt die Ressourcen wieder frei. Wenn du die Ausgangssprache nicht kennst, ermittle sie vorher mit LanguageDetector.

Parameter

Name	Typ	Beschreibung
$options.sourceLanguage Pflicht	string	BCP-47-Sprachcode der Ausgangssprache, z. B. `"en"`. Wird an `Translator.create()` und `Translator.availability()` übergeben.
$options.targetLanguage Pflicht	string	BCP-47-Sprachcode der Zielsprache, z. B. `"de"`.
$options.monitor	(monitor: CreateMonitor) => void	Nur bei `create()`. Callback, der ein `CreateMonitor`-Objekt erhält. Darauf lässt sich `downloadprogress` abonnieren; `e.loaded` liegt zwischen 0 und 1.
$options.signal	AbortSignal	Bricht `create()`, `translate()` oder `translateStreaming()` ab.

Beispiele

Feature-Erkennung, Verfügbarkeit prüfen und Instanz erzeugen

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

if (!('Translator' in self)) {
  console.log('Translator API wird nicht unterstützt');
} else {
  const status = await Translator.availability(options);
  console.log('Status:', status);

  if (status !== 'unavailable') {
    // create() möglichst in einem Klick-Handler aufrufen (Nutzeraktivierung für Download)
    const translator = await Translator.create({
      ...options,
      monitor(m) {
        m.addEventListener('downloadprogress', (e) => {
          console.log(`Download: ${Math.round(e.loaded * 100)} %`);
        });
      }
    });
    console.log(translator.sourceLanguage, '→', translator.targetLanguage);
  }
}

Status: downloadable Download: 0 % Download: 100 % en → de

Text übersetzen per Button-Klick

const button = document.querySelector('#translate');
const input = document.querySelector('#source');
const output = document.querySelector('#result');

let translator;

button.addEventListener('click', async () => {
  translator ??= await Translator.create({
    sourceLanguage: 'en',
    targetLanguage: 'de'
  });
  output.textContent = await translator.translate(input.value);
});

(Eingabe "Good morning!" → Ausgabe "Guten Morgen!")

Lange Texte streamen und abbrechen

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

const text = document.querySelector('article').textContent;
const usage = await translator.measureInputUsage(text);

if (usage > translator.inputQuota) {
  console.warn('Text zu lang – bitte in Abschnitte aufteilen');
} else {
  const stream = translator.translateStreaming(text, { signal: controller.signal });
  let result = '';
  for await (const chunk of stream) {
    result += chunk;
  }
  console.log(result);
}

translator.destroy(); // Ressourcen freigeben

Unbekannte Ausgangssprache mit LanguageDetector kombinieren

const detector = await LanguageDetector.create();
const [best] = await detector.detect('¿Dónde está la estación?');

const translator = await Translator.create({
  sourceLanguage: best.detectedLanguage, // 'es'
  targetLanguage: 'de'
});
console.log(await translator.translate('¿Dónde está la estación?'));

Wo ist der Bahnhof?

// Wichtig · Fallstricke

Experimentell: Die API ist bisher nur in Chrome/Edge (Desktop, ab Version 138) verfügbar. Firefox und Safari unterstützen sie nicht. Prüfe deshalb immer mit 'Translator' in self und halte einen Ersatz bereit, etwa einen Server-Übersetzungsdienst.
Sicherer Kontext erforderlich: Die API funktioniert nur über HTTPS oder localhost. Sie wird über die Berechtigungsrichtlinie translator gesteuert und ist standardmäßig nur im Hauptdokument und in Iframes gleichen Ursprungs erlaubt. Fremde Iframes brauchen allow="translator".
Nutzeraktivierung: Lautet der Status "downloadable" oder "downloading", muss create() nach einer Nutzerinteraktion aufgerufen werden, zum Beispiel in einem Klick-Handler. Sonst wird das Promise abgelehnt (NotAllowedError).
Datenschutz: Der Browser kann die Verfügbarkeit von Sprachpaaren absichtlich ungenau melden, damit sich Nutzer nicht über installierte Sprachpakete identifizieren lassen (Fingerprinting).
Qualität und Grenzen: Maschinelle Übersetzungen können Fehler enthalten. Bei Texten mit rechtlicher Bedeutung solltest du nicht allein darauf vertrauen. Texte, die über inputQuota liegen, führen zu einem QuotaExceededError.
Rufe destroy() auf, wenn du die Instanz nicht mehr brauchst. Danach wird jeder weitere Aufruf abgelehnt.

Siehe auch

Translator.create() Translator.availability() Translator.prototype.translate() CSSTranslate Navigator