LanguageDetector.availability() — Methode · JavaScript-Referenz

Signatur

LanguageDetector.availability(options)

Beschreibung

Die statische Methode LanguageDetector.availability() gehört zur Language Detector API (Teil der eingebauten KI-APIs des Browsers). Sie liefert ein Promise, das mit einem von vier Zeichenketten-Werten erfüllt wird. So erfahren Sie, ob die Spracherkennung für die gewünschte Konfiguration überhaupt möglich ist und ob dafür vorher noch ein Modell heruntergeladen werden muss.

Mögliche Werte:

"unavailable" – Die Konfiguration wird nicht unterstützt (z. B. Gerät zu schwach, Sprache nicht unterstützt oder durch Richtlinie gesperrt).
"downloadable" – Unterstützt, das Modell muss aber erst heruntergeladen werden.
"downloading" – Unterstützt, der Download läuft bereits.
"available" – Unterstützt und sofort nutzbar.

Rufen Sie availability() vor LanguageDetector.create() auf, um Ihre Oberfläche passend zu gestalten: etwa eine Fortschrittsanzeige einzublenden, einen Button „Spracherkennung aktivieren“ anzubieten oder auf eine serverseitige Lösung auszuweichen. Die Methode selbst löst keinen Download aus und benötigt keine Nutzeraktivierung.

Über expectedInputLanguages geben Sie an, welche Sprachen Sie in den Eingabetexten erwarten. Der Browser kann daraufhin genauer beurteilen, ob sein Modell diese Sprachen zuverlässig erkennt.

Parameter

Name	Typ	Default	Beschreibung
$options	Object	{}	Konfigurationsobjekt, das dieselben Optionen beschreibt, die später an `LanguageDetector.create()` übergeben werden sollen.
$options.expectedInputLanguages	string[]		Liste von BCP-47-Sprachcodes (z. B. `["de", "en", "fr"]`), die in den zu analysierenden Texten erwartet werden.

Rückgabewert

Typ

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

Beschreibung

Ein Promise, das mit einem der vier Verfügbarkeitswerte erfüllt wird. Es wird z. B. mit einer InvalidStateError-DOMException abgelehnt, wenn das Dokument nicht vollständig aktiv ist. Bei ungültigen Sprachcodes kann ein RangeError auftreten.

Beispiele

Einfache Verfügbarkeitsprüfung mit Feature-Erkennung

const checkDetector = async () => {
  if (!('LanguageDetector' in self)) {
    console.log('Language Detector API wird nicht unterstützt.');
    return;
  }
  const status = await LanguageDetector.availability();
  console.log(`Status: ${status}`);
};

checkDetector();

Status: available

Erwartete Eingabesprachen prüfen

const status = await LanguageDetector.availability({
  expectedInputLanguages: ['de', 'en', 'fr']
});

if (status === 'unavailable') {
  console.warn('Deutsch/Englisch/Französisch werden lokal nicht erkannt – nutze Server-Fallback.');
} else {
  console.log(`Lokale Erkennung möglich (${status}).`);
}

Lokale Erkennung möglich (downloadable).

UI abhängig vom Status steuern und Download per Klick starten

const button = document.querySelector('#enable-detect');
const info = document.querySelector('#info');

const options = { expectedInputLanguages: ['de', 'en'] };
const status = await LanguageDetector.availability(options);

if (status === 'available') {
  const detector = await LanguageDetector.create(options);
  const [best] = await detector.detect('Guten Morgen, wie geht es dir?');
  info.textContent = `Erkannt: ${best.detectedLanguage} (${best.confidence.toFixed(2)})`;
} else if (status === 'downloadable' || status === 'downloading') {
  button.hidden = false;
  // create() darf den Download nur nach Nutzeraktivierung starten
  button.addEventListener('click', async () => {
    const detector = await LanguageDetector.create({
      ...options,
      monitor(m) {
        m.addEventListener('downloadprogress', (e) => {
          info.textContent = `Download: ${Math.round(e.loaded * 100)} %`;
        });
      }
    });
    info.textContent = 'Spracherkennung bereit.';
  }, { once: true });
} else {
  info.textContent = 'Spracherkennung auf diesem Gerät nicht verfügbar.';
}

// Wichtig · Fallstricke

Experimentell: Derzeit nur in Chromium-Browsern (Chrome/Edge ab Version 138, Desktop) verfügbar. Firefox und Safari unterstützen die API nicht. Prüfen Sie deshalb immer mit 'LanguageDetector' in self, bevor Sie sie verwenden.
Die API steht nur in sicheren Kontexten (HTTPS) zur Verfügung. In iframes kann sie durch die Permissions Policy language-detector gesperrt sein; das Ergebnis ist dann "unavailable" bzw. ein Fehler beim Aufruf von create().
Das Ergebnis ist nur eine Momentaufnahme: Aus "downloadable" kann jederzeit "available" werden, etwa wenn eine andere Seite das Modell geladen hat. Speichern Sie den Wert also nicht dauerhaft.
"downloadable" bzw. "downloading" bedeutet: Für create() ist eine vorübergehende Nutzeraktivierung (z. B. ein Klick) nötig, sonst wird der Aufruf abgelehnt.
Für den Datenschutz kann der Browser die Antwort absichtlich verallgemeinern (Schutz vor Fingerprinting). Verlassen Sie sich deshalb nicht darauf, dass "available" genau anzeigt, welche Modelle installiert sind.

Siehe auch

LanguageDetector LanguageDetector.create() LanguageDetector.prototype.detect() LanguageDetector.prototype.destroy() Translator.availability() Summarizer.availability() LanguageDetector.measureInputUsage()