Window: languagechange — Ereignis · JavaScript-Referenz

Signatur

window.addEventListener("languagechange", handler)

Beschreibung

Das Ereignis languagechange wird am globalen Objekt ausgelöst, sobald sich die bevorzugten Sprachen des Benutzers ändern, also der Wert von navigator.language bzw. navigator.languages. Das passiert typischerweise, wenn der Benutzer in den Browser- oder Systemeinstellungen die Sprache oder deren Reihenfolge ändert.

Nützlich ist das Ereignis für mehrsprachige Webanwendungen, die die Oberflächensprache an den Browser koppeln: Man kann Texte, Datums- und Zahlenformate (z. B. über Intl.DateTimeFormat oder Intl.NumberFormat) neu berechnen, ohne dass die Seite neu geladen werden muss.

Das Ereignis ist ein einfaches Event ohne zusätzliche Eigenschaften. Es lässt sich nicht abbrechen und steigt nicht auf (bubbelt nicht). Die neuen Sprachwerte liest man im Handler direkt aus navigator.languages aus. Man kann den Handler per addEventListener("languagechange", …) oder über die Eigenschaft window.onlanguagechange registrieren. In Web Workern gibt es das Ereignis ebenfalls, dort am self-Objekt.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Der Ereignistyp, hier immer `"languagechange"`.
$handler Pflicht	(event: Event) => void		Callback, der bei einer Sprachänderung aufgerufen wird. Bekommt ein einfaches `Event`-Objekt übergeben.
$options	boolean \| AddEventListenerOptions	false	Optionale Listener-Optionen wie `once`, `signal` oder `passive`.

Rückgabewert

Typ

void

Beschreibung

addEventListener gibt nichts zurück. Der Handler bekommt ein Event ohne sprachspezifische Daten übergeben.

Beispiele

Sprachänderung per addEventListener protokollieren

const logLanguages = () => {
  console.log('Bevorzugte Sprache:', navigator.language);
  console.log('Alle Sprachen:', navigator.languages.join(', '));
};

window.addEventListener('languagechange', logLanguages);
logLanguages(); // Startzustand ausgeben

Bevorzugte Sprache: de-DE Alle Sprachen: de-DE, de, en-US, en

Datumsanzeige bei Sprachwechsel neu formatieren

const el = document.querySelector('#heute');

const render = () => {
  const fmt = new Intl.DateTimeFormat(navigator.languages, {
    dateStyle: 'full'
  });
  el.textContent = fmt.format(new Date());
  document.documentElement.lang = navigator.language;
};

render();
window.addEventListener('languagechange', render);

z. B. "Montag, 3. Juni 2024" → nach Wechsel auf Englisch: "Monday, June 3, 2024"

on-Property verwenden und Listener wieder entfernen

// Variante 1: Event-Handler-Eigenschaft
window.onlanguagechange = () => {
  console.log('Neue Sprache (onlanguagechange):', navigator.language);
};

// Variante 2: Listener mit AbortController wieder entfernen
const controller = new AbortController();
window.addEventListener('languagechange', () => {
  console.log('Sprache geändert');
}, { signal: controller.signal });

// Später, z. B. beim Abbau einer Komponente:
controller.abort();
window.onlanguagechange = null;

Im Web Worker auf Sprachwechsel reagieren

// worker.js
self.addEventListener('languagechange', () => {
  self.postMessage({ languages: [...navigator.languages] });
});

{ languages: ['en-US', 'en', 'de'] }

// Wichtig · Fallstricke

Das Ereignis enthält keine Angaben zur neuen Sprache. Die Werte liest man immer aus navigator.language bzw. navigator.languages.
Die Werte von navigator.languages müssen nicht mit dem Accept-Language-Header übereinstimmen, und nicht jeder Browser löst das Ereignis bei jeder Systemänderung sofort aus. Manche Browser tun das erst nach einem Neustart oder nur, wenn die Sprache in den Browsereinstellungen geändert wurde.
Aus Datenschutzgründen (Fingerprinting-Schutz, z. B. resistFingerprinting in Firefox oder Safari) können die gemeldeten Sprachen vereinfacht sein. Das Ereignis wird dann eventuell gar nicht ausgelöst.
Es ist nicht sicher, dass das Ereignis überhaupt kommt. Deshalb sollte die Anwendung die Sprache auch beim Start einmal auswerten.
Formatierer wie Intl.DateTimeFormat, die im Cache liegen, müssen nach dem Ereignis neu erzeugt werden. Sonst verwenden sie weiter die alte Sprache.
Browserunterstützung: in allen modernen Browsern vorhanden, auch in Web Workern. Im Internet Explorer gibt es das Ereignis nicht.

Siehe auch

Navigator.language Navigator.languages Window Clipboard: clipboardchange Window: hashchange Window: gamepadconnected