LanguageDetector.create() — Methode · JavaScript-Referenz

Signatur

LanguageDetector.create(options)

Beschreibung

LanguageDetector.create() ist der Einstiegspunkt der Language Detector API, die zu den im Browser eingebauten KI-APIs gehört. Die Methode gibt ein Promise zurück, das mit einem fertig nutzbaren LanguageDetector-Objekt erfüllt wird. Mit dessen Methode detect() lässt sich dann ermitteln, in welcher Sprache ein Text geschrieben ist. Die Erkennung läuft vollständig lokal auf dem Gerät. Es werden also keine Daten an einen Server geschickt.

Beim ersten Aufruf muss der Browser das Erkennungsmodell unter Umständen erst herunterladen. Über die Option monitor kannst du den Downloadfortschritt verfolgen, etwa für eine Fortschrittsanzeige. Mit expectedInputLanguages teilst du dem Browser mit, welche Sprachen du erwartest. Das kann die Genauigkeit verbessern. Wird eine dieser Sprachen nicht unterstützt, schlägt create() fehl.

Prüfe vor dem Aufruf am besten mit LanguageDetector.availability(), ob die Funktion überhaupt verfügbar ist. Mögliche Ergebnisse sind "unavailable", "downloadable", "downloading" und "available". Ist ein Download nötig, verlangt der Browser eine vorübergehende Nutzeraktivierung. Der Aufruf muss dann zum Beispiel in einem Klick-Handler stehen.

Parameter

Name	Typ	Default	Beschreibung
$options	Object	{}	Optionales Konfigurationsobjekt mit den folgenden Eigenschaften.
$options.expectedInputLanguages	string[]		Liste von BCP-47-Sprachcodes (z. B. `["de", "en"]`), die im Eingabetext erwartet werden. Ist eine davon nicht unterstützt, wird das Promise mit `NotSupportedError` abgelehnt.
$options.monitor	(monitor: CreateMonitor) => void		Callback, der ein `CreateMonitor`-Objekt erhält. An diesem kann man auf das Ereignis `downloadprogress` hören. `event.loaded` liegt dabei zwischen 0 und 1.
$options.signal	AbortSignal		Signal eines `AbortController`, mit dem sich die Erzeugung (samt Download) abbrechen lässt.

Rückgabewert

Typ

Promise<LanguageDetector>

Beschreibung

Ein Promise, das mit einer neuen LanguageDetector-Instanz erfüllt wird. Im Fehlerfall wird es mit einer DOMException abgelehnt, z. B. NotAllowedError, NotSupportedError, AbortError, InvalidStateError oder OperationError.

Beispiele

Einfache Spracherkennung mit Verfügbarkeitsprüfung

if (!('LanguageDetector' in self)) {
  console.log('Language Detector API wird nicht unterstützt.');
} else {
  const status = await LanguageDetector.availability();
  if (status !== 'unavailable') {
    const detector = await LanguageDetector.create();
    const results = await detector.detect('Guten Morgen, wie geht es dir?');
    const [top] = results;
    console.log(top.detectedLanguage, top.confidence.toFixed(2));
  }
}

de 0.98

Download-Fortschritt anzeigen (nach Nutzerklick)

const button = document.querySelector('#init-detector');
const progress = document.querySelector('progress');

button.addEventListener('click', async () => {
  const detector = await LanguageDetector.create({
    monitor(m) {
      m.addEventListener('downloadprogress', (e) => {
        progress.value = e.loaded; // 0 … 1
        console.log(`Heruntergeladen: ${Math.round(e.loaded * 100)} %`);
      });
    },
  });
  console.log('Detektor bereit:', detector);
});

Heruntergeladen: 0 % Heruntergeladen: 100 % Detektor bereit: LanguageDetector {…}

Erwartete Sprachen angeben und Abbruch per AbortController

const controller = new AbortController();
setTimeout(() => controller.abort(), 10_000); // nach 10 s abbrechen

try {
  const detector = await LanguageDetector.create({
    expectedInputLanguages: ['de', 'en', 'fr'],
    signal: controller.signal,
  });
  const results = await detector.detect('Bonjour tout le monde');
  console.log(results.slice(0, 2));
  detector.destroy(); // Ressourcen freigeben
} catch (err) {
  if (err.name === 'AbortError') console.warn('Abgebrochen');
  else if (err.name === 'NotSupportedError') console.warn('Sprache nicht unterstützt');
  else throw err;
}

[{ detectedLanguage: 'fr', confidence: 0.97 }, { detectedLanguage: 'en', confidence: 0.01 }]

// Wichtig · Fallstricke

Experimentell: Bisher nur in Chromium-basierten Browsern verfügbar (Chrome/Edge ab 138, Desktop). Firefox und Safari unterstützen die API derzeit nicht. Prüfe sie deshalb immer mit 'LanguageDetector' in self.
Die API funktioniert nur in einem sicheren Kontext (HTTPS). In iframes muss die Permissions Policy language-detector sie ausdrücklich erlauben.
Ist ein Modell-Download nötig ("downloadable"), braucht der Aufruf eine Nutzeraktivierung. Fehlt sie, gibt es einen NotAllowedError.
Bei sehr kurzen Texten (einzelne Wörter) sind die Ergebnisse unzuverlässig. Werte deshalb immer confidence aus und nimm nicht einfach den ersten Treffer blind.
Rufe detector.destroy() auf, wenn du die Instanz nicht mehr brauchst. So gibst du Speicher und Modellressourcen frei. Und erzeuge nicht bei jeder Erkennung eine neue Instanz, das kostet unnötig Leistung.
Wie lang die Eingabe sein darf, verrät inputQuota. Den Verbrauch eines konkreten Textes misst du vorab mit measureInputUsage().

Siehe auch

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