Translator.translate() — Methode · JavaScript-Referenz

Signatur

Translator.prototype.translate(input, options)

Beschreibung

Die Methode translate() gehört zur Translator API, mit der der Browser Texte direkt auf dem Gerät übersetzt. Dafür nutzt er ein lokales Sprachmodell. Die Texte werden also nicht an einen externen Übersetzungsdienst geschickt. Das ist gut für den Datenschutz, funktioniert offline, sobald das Modell geladen ist, und verursacht keine API-Kosten.

Bevor Sie translate() aufrufen, erzeugen Sie mit Translator.create({ sourceLanguage, targetLanguage }) eine Instanz für ein festes Sprachpaar. Die Methode nimmt den vollständigen Text entgegen und erfüllt das zurückgegebene Promise erst, wenn die ganze Übersetzung fertig ist. Bei langen Texten, bei denen Teilergebnisse schon während der Übersetzung erscheinen sollen, ist translateStreaming() besser geeignet.

Typische Einsatzfälle sind Nutzerkommentare, Chat-Nachrichten, Produktbewertungen oder Supportanfragen, die in die Sprache des Nutzers übersetzt werden sollen. Mit Translator.availability() sollten Sie vorher prüfen, ob das Sprachpaar unterstützt wird und ob das Modell erst heruntergeladen werden muss.

Parameter

Name	Typ	Default	Beschreibung
$input Pflicht	string		Der zu übersetzende Text in der Quellsprache (`sourceLanguage`) der Instanz.
$options	object	{}	Optionales Konfigurationsobjekt.
$options.signal	AbortSignal		Ein `AbortSignal`, zum Beispiel von einem `AbortController`, mit dem Sie eine laufende Übersetzung abbrechen können. Das `Promise` wird dann mit einem `AbortError` zurückgewiesen.

Rückgabewert

Typ

Promise<string>

Beschreibung

Ein Promise, das mit dem übersetzten Text in der Zielsprache (targetLanguage) erfüllt wird. Mögliche Zurückweisungen: AbortError beim Abbruch, InvalidStateError, wenn das Dokument nicht aktiv ist oder die Instanz mit destroy() freigegeben wurde, QuotaExceededError, wenn der Text das inputQuota überschreitet, sowie NotAllowedError oder UnknownError bei sonstigen Fehlern.

Beispiele

Einfache Übersetzung Englisch → Deutsch

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

  const result = await translator.translate('Where is the train station?');
  console.log(result);

  // Instanz freigeben, wenn sie nicht mehr gebraucht wird
  translator.destroy();
} else {
  console.log('Translator API wird nicht unterstützt.');
}

Wo ist der Bahnhof?

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

const translateComment = async (text, from, to) => {
  const status = await Translator.availability({
    sourceLanguage: from,
    targetLanguage: to
  });

  if (status === 'unavailable') {
    throw new Error(`Sprachpaar ${from} → ${to} nicht verfügbar`);
  }

  const translator = await Translator.create({
    sourceLanguage: from,
    targetLanguage: to,
    monitor(m) {
      m.addEventListener('downloadprogress', (e) => {
        console.log(`Modell geladen: ${Math.round(e.loaded * 100)} %`);
      });
    }
  });

  return translator.translate(text);
};

// Muss bei nötigem Download durch eine Nutzeraktion ausgelöst werden
document.querySelector('#translate-btn').addEventListener('click', async () => {
  const output = document.querySelector('#output');
  output.textContent = await translateComment('Great product, fast delivery!', 'en', 'de');
});

Modell geladen: 100 %

Übersetzung mit Zeitlimit und Quota-Prüfung

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

const text = 'Vielen Dank für Ihre Bestellung.';

// Prüfen, ob der Text in das Eingabe-Kontingent passt
const usage = await translator.measureInputUsage(text);
if (usage > translator.inputQuota) {
  throw new Error('Text ist zu lang – bitte aufteilen.');
}

try {
  const fr = await translator.translate(text, {
    signal: AbortSignal.timeout(5000)
  });
  console.log(fr);
} catch (err) {
  if (err.name === 'TimeoutError' || err.name === 'AbortError') {
    console.warn('Übersetzung abgebrochen.');
  } else {
    console.error(err);
  }
}

Merci pour votre commande.

// Wichtig · Fallstricke

Browserunterstützung: Die Methode ist experimentell. Bisher gibt es sie nur in Chromium-Browsern auf dem Desktop (Chrome 138+). Prüfen Sie daher immer mit 'Translator' in self, ob sie verfügbar ist, und sehen Sie einen Rückfall vor, etwa eine serverseitige Übersetzung.
Sicherer Kontext und Berechtigungen: Die API funktioniert nur über HTTPS. In iframes muss die Permissions-Policy translator freigegeben sein. Muss das Modell erst geladen werden, verlangt Translator.create() eine Nutzeraktion, zum Beispiel einen Klick.
Festes Sprachpaar: Eine Instanz übersetzt immer nur zwischen den bei create() angegebenen Sprachen. Für andere Sprachen brauchen Sie eine neue Instanz. Ist die Quellsprache unbekannt, ermitteln Sie sie vorher mit der LanguageDetector API.
Lange Texte: Übersteigt der Text das inputQuota, wird das Promise mit QuotaExceededError zurückgewiesen. Teilen Sie lange Texte deshalb auf oder verwenden Sie translateStreaming().
Sicherheit: Behandeln Sie die Übersetzung wie jede andere nicht vertrauenswürdige Eingabe. Geben Sie sie mit textContent aus und nicht ungefiltert mit innerHTML, sonst droht XSS.
Ressourcen: Geben Sie nicht mehr benötigte Instanzen mit destroy() frei. Danach führt jeder Aufruf von translate() zu einem InvalidStateError.
Die Übersetzungen stammen aus einem Modell. Sie können daher ungenau sein, und für Fachtexte ist keine bestimmte Qualität garantiert.

Siehe auch

Translator Translator.create() Translator.availability() Translator.translateStreaming() Translator.measureInputUsage() Translator.destroy() LanguageDetector