LanguageDetector.detect() — Methode · JavaScript-Referenz

Signatur

LanguageDetector.prototype.detect(input, options)

Beschreibung

Die Methode detect() einer LanguageDetector-Instanz analysiert einen Text mit einem im Browser integrierten, lokal ausgeführten KI-Modell. Sie gibt ein Promise zurück, das mit einem Array von Ergebnisobjekten erfüllt wird. Jedes Objekt enthält die Eigenschaften detectedLanguage (ein BCP-47-Sprachcode wie "de" oder "en") und confidence (eine Zahl zwischen 0 und 1).

Die Ergebnisse sind absteigend nach Konfidenz sortiert. Das erste Element ist also die wahrscheinlichste Sprache. Die Konfidenzwerte ergeben zusammen etwa 1. Den letzten Eintrag bildet in der Regel "und" (undetermined, also „nicht bestimmbar“). Er steht für den Anteil, der keiner Sprache sicher zugeordnet werden kann.

Typische Anwendungsfälle sind: vor einer Übersetzung mit der Translator-API die Ausgangssprache bestimmen, Nutzerbeiträge nach Sprache einordnen oder weiterleiten und die passende Rechtschreibprüfung oder Sprachausgabe auswählen. Weil das Modell auf dem Gerät läuft, verlassen die Daten den Browser nicht.

Bevor du detect() aufrufen kannst, brauchst du eine Instanz über LanguageDetector.create(). Beim ersten Aufruf muss das Modell unter Umständen erst heruntergeladen werden. Prüfe deshalb vorher mit LanguageDetector.availability(), ob es verfügbar ist.

Parameter

Name	Typ	Default	Beschreibung
$input Pflicht	string		Der Text, dessen Sprache erkannt werden soll. Je länger der Text ist, desto verlässlicher ist das Ergebnis in der Regel.
$options	object	{}	Optionales Konfigurationsobjekt.
$options.signal	AbortSignal		Ein `AbortSignal`, mit dem du die laufende Erkennung abbrechen kannst. Das Promise wird dann mit einem `AbortError` abgelehnt.

Rückgabewert

Typ

Promise<Array<{detectedLanguage: string, confidence: number}>>

Beschreibung

Ein Promise, das mit einem nach confidence absteigend sortierten Array von Ergebnisobjekten erfüllt wird. detectedLanguage ist ein BCP-47-Sprachcode (bzw. "und"), confidence ist ein Wert zwischen 0 und 1.

Beispiele

Wahrscheinlichste Sprache eines Textes ermitteln

if ('LanguageDetector' in self) {
  const detector = await LanguageDetector.create();
  const results = await detector.detect('Guten Morgen, wie geht es dir heute?');

  const [top] = results;
  console.log(`${top.detectedLanguage} (${(top.confidence * 100).toFixed(1)} %)`);
} else {
  console.log('Language Detector API wird nicht unterstützt.');
}

de (99.2 %)

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

const availability = await LanguageDetector.availability();

if (availability === 'unavailable') {
  console.log('Spracherkennung auf diesem Gerät nicht möglich.');
} else {
  const detector = await LanguageDetector.create({
    expectedInputLanguages: ['de', 'en', 'fr'],
    monitor(m) {
      m.addEventListener('downloadprogress', (e) => {
        console.log(`Download: ${Math.round(e.loaded * 100)} %`);
      });
    }
  });

  const results = await detector.detect('Bonjour tout le monde');
  // Nur Ergebnisse mit ausreichender Konfidenz anzeigen, "und" ausfiltern
  const relevant = results.filter(
    (r) => r.detectedLanguage !== 'und' && r.confidence > 0.1
  );
  console.log(relevant);
}

[{ detectedLanguage: "fr", confidence: 0.97 }]

Erkennung mit Timeout abbrechen

const detector = await LanguageDetector.create();
const controller = new AbortController();
const timer = setTimeout(() => controller.abort(), 2000);

try {
  const text = document.querySelector('#kommentar').value;
  const [top] = await detector.detect(text, { signal: controller.signal });
  document.documentElement.lang ||= top.detectedLanguage;
  console.log('Erkannt:', top.detectedLanguage);
} catch (err) {
  if (err.name === 'AbortError') {
    console.warn('Spracherkennung abgebrochen (Timeout).');
  } else {
    throw err;
  }
} finally {
  clearTimeout(timer);
}

Erkannt: en

Ausgangssprache für eine Übersetzung bestimmen

const detector = await LanguageDetector.create();
const text = 'Where is the nearest train station?';
const [{ detectedLanguage, confidence }] = await detector.detect(text);

if (confidence > 0.7 && 'Translator' in self) {
  const translator = await Translator.create({
    sourceLanguage: detectedLanguage,
    targetLanguage: 'de'
  });
  console.log(await translator.translate(text));
}

Wo ist der nächste Bahnhof?

// Wichtig · Fallstricke

Kompatibilität: Experimentelle API, die derzeit nur Chromium-Browser auf dem Desktop unterstützen (Chrome 138+, Edge). Firefox und Safari unterstützen sie nicht. Nutze immer eine Feature-Erkennung wie 'LanguageDetector' in self. Die API steht nur in sicheren Kontexten (HTTPS) zur Verfügung. In iframes muss die Permissions-Policy language-detector sie erlauben.
Kurze Texte: Bei einzelnen Wörtern oder sehr kurzen Sätzen ist die Erkennung unzuverlässig, und die Konfidenzwerte sind niedrig. Werte deshalb immer confidence aus, statt blind das erste Ergebnis zu übernehmen.
Der Eintrag "und": Das Ergebnis-Array enthält meist einen Eintrag "und" für „nicht bestimmbar“. Filtere ihn aus, wenn du nur echte Sprachen weiterverarbeiten willst.
Fehler: Das Promise wird abgelehnt mit einem InvalidStateError, wenn die Instanz mit destroy() zerstört wurde, mit einem AbortError bei Abbruch über das Signal, und mit einem QuotaExceededError, wenn der Text inputQuota überschreitet. Die Größe eines Textes vorab kannst du mit measureInputUsage() prüfen.
Erster Aufruf: create() kann einen Modell-Download auslösen, der Zeit und Speicherplatz braucht. Dafür ist teilweise eine Nutzeraktivierung nötig, zum Beispiel ein Klick.
Ressourcen: Verwende eine Instanz für mehrere Aufrufe wieder und gib sie mit destroy() frei, wenn du sie nicht mehr brauchst.

Siehe auch

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