LanguageDetector — Schnittstelle · JavaScript-Referenz

Signatur

interface LanguageDetector

Beschreibung

Das Interface LanguageDetector gehört zu den Translator and Language Detector APIs. Es übernimmt die Spracherkennung, also die Frage „In welcher Sprache ist dieser Text geschrieben?“. Die Erkennung läuft über ein KI-Modell, das der Browser auf dem Gerät bereitstellt. Die Texte verlassen den Rechner dabei nicht. Das ist für den Datenschutz gut und funktioniert nach dem Herunterladen des Modells auch ohne Netz.

Typische Einsatzfälle sind: vor einer Übersetzung mit Translator die Ausgangssprache bestimmen, Nutzerbeiträge an die richtige Moderation weiterleiten, das Attribut lang dynamisch setzen oder eine passende Rechtschreibprüfung wählen.

Die Nutzung läuft immer in drei Schritten ab:

LanguageDetector.availability(options) (statisch) prüft, ob das Modell bereitsteht. Mögliche Antworten: "unavailable", "downloadable", "downloading" oder "available".
LanguageDetector.create(options) (statisch) erzeugt eine Instanz und lädt das Modell bei Bedarf herunter. Über monitor lässt sich der Fortschritt verfolgen.
detector.detect(input, options) gibt ein Promise auf ein Array von Objekten { detectedLanguage, confidence } zurück, absteigend nach confidence sortiert. Weitere Instanz-Mitglieder: measureInputUsage(), inputQuota, expectedInputLanguages und destroy().

Die Sprachen werden als BCP-47-Sprachkürzel angegeben (z. B. "de", "en", "ja"). Kann das Modell keine Sprache sicher bestimmen, erscheint der Eintrag "und" (undetermined, also „unbestimmt“).

Parameter

Name	Typ	Beschreibung
$options.expectedInputLanguages	string[]	Optional für `create()` und `availability()`: Liste der BCP-47-Sprachen, die in der Eingabe zu erwarten sind. Hilft dem Browser, ein passendes Modell bereitzustellen.
$options.monitor	(monitor: CreateMonitor) => void	Nur bei `create()`: Rückruffunktion, die ein Überwachungsobjekt erhält. Dessen Ereignis `downloadprogress` meldet den Fortschritt des Modell-Downloads über `e.loaded` (Wert von 0 bis 1).
$options.signal	AbortSignal	Bricht `create()` bzw. `detect()` ab. Das Promise wird dann mit einem `AbortError` abgelehnt.
$input Pflicht	string	Bei `detect()` und `measureInputUsage()`: der Text, dessen Sprache bestimmt werden soll.

Rückgabewert

Typ

Promise<LanguageDetector>

Beschreibung

LanguageDetector.create() liefert ein Promise auf eine fertige Instanz. detect() liefert Promise<Array<{ detectedLanguage: string, confidence: number }>>, availability() liefert Promise<string>.

Beispiele

Verfügbarkeit prüfen und Detektor erzeugen

const initDetector = async () => {
  if (!('LanguageDetector' in self)) {
    console.warn('LanguageDetector wird nicht unterstützt');
    return null;
  }

  const status = await LanguageDetector.availability();
  console.log('Status:', status);
  if (status === 'unavailable') return null;

  // Beim ersten Download ist eine Nutzeraktion nötig (z. B. ein Klick)
  return LanguageDetector.create({
    monitor(m) {
      m.addEventListener('downloadprogress', (e) => {
        console.log(`Download: ${Math.round(e.loaded * 100)} %`);
      });
    }
  });
};

document.querySelector('#start').addEventListener('click', async () => {
  const detector = await initDetector();
  console.log('Bereit:', !!detector);
});

Status: downloadable Download: 0 % Download: 100 % Bereit: true

Sprache eines Textes erkennen

const detector = await LanguageDetector.create();

const results = await detector.detect('Guten Morgen, wie geht es dir heute?');

// Ergebnisse sind nach Wahrscheinlichkeit absteigend sortiert
for (const { detectedLanguage, confidence } of results.slice(0, 3)) {
  console.log(detectedLanguage, confidence.toFixed(3));
}

de 0.998 nl 0.001 en 0.000

Praxis: erkannte Sprache an den Translator weitergeben

const translateToGerman = async (text) => {
  const detector = await LanguageDetector.create();
  const [best] = await detector.detect(text);
  detector.destroy(); // Ressourcen freigeben

  if (best.detectedLanguage === 'und' || best.confidence < 0.6) {
    throw new Error('Sprache nicht sicher erkennbar');
  }
  if (best.detectedLanguage === 'de') return text;

  const translator = await Translator.create({
    sourceLanguage: best.detectedLanguage,
    targetLanguage: 'de'
  });
  return translator.translate(text);
};

console.log(await translateToGerman('The weather is nice today.'));

Das Wetter ist heute schön.

Eingabelänge prüfen und Erkennung abbrechen

const controller = new AbortController();
const detector = await LanguageDetector.create({
  expectedInputLanguages: ['de', 'en', 'fr']
});

const text = document.querySelector('textarea').value;
const usage = await detector.measureInputUsage(text);

if (usage > detector.inputQuota) {
  console.warn('Text zu lang für das Modell');
} else {
  setTimeout(() => controller.abort(), 2000); // nach 2 s abbrechen
  try {
    const [top] = await detector.detect(text, { signal: controller.signal });
    console.log('Sprache:', top.detectedLanguage);
  } catch (err) {
    if (err.name === 'AbortError') console.log('Abgebrochen');
  }
}

Sprache: fr

// Wichtig · Fallstricke

Kompatibilität: Die API ist experimentell. Standardmäßig verfügbar ist sie derzeit in Chromium-basierten Desktop-Browsern (Chrome/Edge ab 138). Firefox und Safari unterstützen sie bislang nicht. Deshalb immer vorher mit 'LanguageDetector' in self prüfen.
Sicherer Kontext: Die API steht nur unter HTTPS zur Verfügung. In iframes wird sie über die Permissions Policy language-detector gesteuert.
Nutzeraktion: Liefert availability() den Wert "downloadable" oder "downloading", braucht create() eine vorübergehende Nutzeraktion (z. B. einen Klick). Ohne sie wird das Promise mit NotAllowedError abgelehnt.
Kurze Texte sind unzuverlässig: Einzelne Wörter oder sehr kurze Sätze liefern oft niedrige confidence-Werte oder falsche Treffer. Deshalb einen Schwellenwert festlegen und den Fall "und" gesondert behandeln.
Ressourcen: Das Modell belegt Speicher. Nicht mehr benötigte Instanzen mit destroy() freigeben und die Instanz für viele Aufrufe wiederverwenden, statt jedes Mal neu create() aufzurufen.
Der erste Download kann groß sein und hängt von Speicherplatz und Hardware ab. Der Browser kann die Verfügbarkeit ohne Vorwarnung auf "unavailable" setzen.

Siehe auch

BarcodeDetector IdleDetector LanguageModel GamepadEvent ImageDecoder