Translator.availability() — Methode · JavaScript-Referenz

Signatur

Translator.availability(options)

Beschreibung

Translator.availability() ist eine statische Methode der Translator-Schnittstelle (Translator and Language Detector APIs). Sie prüft, ob der Browser für ein bestimmtes Paar aus Ausgangs- und Zielsprache ein lokales KI-Übersetzungsmodell bereitstellen kann. Das Ergebnis ist ein Promise, das mit einer von vier Zeichenketten erfüllt wird.

"available": Das Modell ist installiert und sofort nutzbar.
"downloadable": Das Sprachpaar wird unterstützt, das Modell muss aber erst heruntergeladen werden.
"downloading": Der Download läuft gerade.
"unavailable": Das Sprachpaar wird auf diesem Gerät nicht unterstützt.

Verwende die Methode vor Translator.create(). So kannst du deine Oberfläche passend anpassen, etwa eine Download-Fortschrittsanzeige einblenden, eine Rückfalllösung über einen Server-Übersetzungsdienst nutzen oder die Übersetzungsfunktion ganz ausblenden. Die Abfrage selbst startet keinen Download.

Die Übersetzung läuft vollständig auf dem Gerät. Die Texte verlassen den Browser also nicht, was gut für den Datenschutz ist.

Parameter

Name	Typ	Beschreibung
$options Pflicht	Object	Konfigurationsobjekt, das die Übersetzung beschreibt.
$options.sourceLanguage Pflicht	string	BCP-47-Sprach-Tag der Ausgangssprache, z. B. `"en"`.
$options.targetLanguage Pflicht	string	BCP-47-Sprach-Tag der Zielsprache, z. B. `"de"`.

Rückgabewert

Typ

Promise<"available" | "downloadable" | "downloading" | "unavailable">

Beschreibung

Ein Promise, das mit einem Verfügbarkeitswert erfüllt wird. Es wird mit einem TypeError abgelehnt, wenn Pflichtoptionen fehlen oder ungültige Sprach-Tags übergeben werden, und mit einem InvalidStateError, wenn das Dokument nicht aktiv ist.

Beispiele

Verfügbarkeit eines Sprachpaars prüfen

if ('Translator' in self) {
  const status = await Translator.availability({
    sourceLanguage: 'en',
    targetLanguage: 'de',
  });
  console.log(`Englisch → Deutsch: ${status}`);
} else {
  console.log('Translator API wird nicht unterstützt');
}

Englisch → Deutsch: downloadable

Übersetzer je nach Status erzeugen, mit Download-Fortschritt

const getTranslator = async (sourceLanguage, targetLanguage) => {
  const status = await Translator.availability({ sourceLanguage, targetLanguage });

  if (status === 'unavailable') {
    return null; // Rückfall auf Server-Übersetzung
  }

  // create() muss bei 'downloadable' durch eine Nutzeraktion ausgelöst werden
  return Translator.create({
    sourceLanguage,
    targetLanguage,
    monitor(m) {
      m.addEventListener('downloadprogress', (e) => {
        console.log(`Download: ${Math.round(e.loaded * 100)} %`);
      });
    },
  });
};

document.querySelector('#uebersetzen').addEventListener('click', async () => {
  const translator = await getTranslator('en', 'de');
  if (!translator) return console.log('Sprachpaar nicht verfügbar');
  console.log(await translator.translate('Hello world!'));
});

Download: 100 % Hallo Welt!

Mehrere Zielsprachen gleichzeitig prüfen

const zielsprachen = ['de', 'fr', 'es', 'ja'];

const ergebnisse = await Promise.all(
  zielsprachen.map(async (targetLanguage) => [
    targetLanguage,
    await Translator.availability({ sourceLanguage: 'en', targetLanguage }),
  ])
);

console.table(Object.fromEntries(ergebnisse));

{ de: 'available', fr: 'downloadable', es: 'downloadable', ja: 'unavailable' }

// Wichtig · Fallstricke

Experimentell: Die API gibt es bisher nur in Chromium-basierten Desktop-Browsern (Chrome 138+). Sie funktioniert nur in sicheren Kontexten (HTTPS) und ist in Cross-Origin-iframes nur mit der Permissions Policy translator nutzbar. Prüfe die Unterstützung immer vorher mit 'Translator' in self.
Keine Garantie: "downloadable" bedeutet nicht, dass der Download sicher klappt. Es kann zum Beispiel an Speicherplatz oder Netzwerk scheitern. Behandle Fehler von create() deshalb trotzdem.
Nutzeraktion nötig: Ist das Modell noch nicht vorhanden, darf Translator.create() nur nach einer Nutzeraktion aufgerufen werden (transiente Aktivierung). availability() selbst braucht keine.
Fingerprinting: Um Nutzer schwerer identifizierbar zu machen, kann der Browser Ergebnisse vereinheitlichen, etwa "downloadable" melden, obwohl das Modell schon installiert ist.
Der Wert ist eine Momentaufnahme. Nach einem Download kann ein erneuter Aufruf ein anderes Ergebnis liefern.

Siehe auch

Translator Translator.create() Translator.prototype.translate() ViewTransition.waitUntil() Translator.destroy()