HTMLElement.lang — Eigenschaft · JavaScript-Referenz

Signatur

HTMLElement.lang

Beschreibung

Die Eigenschaft lang spiegelt das globale HTML-Attribut lang wider. Sie gibt an, in welcher Sprache der Textinhalt und die übersetzbaren Attributwerte (etwa title, alt oder placeholder) eines Elements verfasst sind. Der Wert ist ein Sprachtag nach BCP 47, z. B. "de", "de-AT", "en-GB" oder "zh-Hant".

Die Sprachangabe hat praktische Folgen: Screenreader wählen danach Aussprache und Stimme, Browser nutzen sie für automatische Silbentrennung (hyphens: auto), Anführungszeichen (quotes), die Rechtschreibprüfung und Übersetzungsangebote. In CSS lässt sie sich mit der Pseudoklasse :lang() ansprechen, die auch die geerbte Sprache berücksichtigt.

Wichtig: Die Eigenschaft liefert nur den Wert des eigenen Attributs. Hat das Element kein lang-Attribut, ist der Rückgabewert ein leerer String, obwohl das Element die Sprache eines Vorfahren erbt. Um die tatsächlich wirksame Sprache zu ermitteln, sucht man mit element.closest("[lang]") den nächsten Vorfahren mit gesetztem Attribut.

Typische Einsatzfälle sind mehrsprachige Anwendungen, die beim Sprachwechsel document.documentElement.lang anpassen, sowie das Auszeichnen einzelner fremdsprachiger Textstellen, die dynamisch eingefügt werden.

Parameter

Name	Typ	Default	Beschreibung
$value	string	""	Beim Setzen: ein BCP-47-Sprachtag wie `"de"` oder `"en-US"`. Ein leerer String bedeutet unbekannte Sprache und unterbricht die Vererbung vom Elternelement.

Rückgabewert

Typ

string

Beschreibung

Der Wert des lang-Attributs des Elements oder ein leerer String, wenn das Attribut fehlt. Der Wert wird unverändert zurückgegeben, also weder normalisiert noch geprüft.

Beispiele

Sprache der Seite lesen und setzen

const root = document.documentElement;
console.log(root.lang); // z. B. "de"

// Beim Sprachwechsel in einer Single-Page-App
const setPageLanguage = (tag) => {
  root.lang = tag;
  console.log(root.getAttribute("lang"));
};

setPageLanguage("en-GB");

de en-GB

Wirksame (geerbte) Sprache eines Elements ermitteln

// <html lang="de"><body><p id="absatz">Hallo</p></body></html>
const p = document.getElementById("absatz");

console.log(JSON.stringify(p.lang)); // eigenes Attribut fehlt

const effectiveLang = (el) => el.closest("[lang]")?.lang ?? "";
console.log(effectiveLang(p));

"" de

Fremdsprachige Zitate korrekt auszeichnen

const quotes = [
  { text: "Carpe diem", lang: "la" },
  { text: "Stay hungry, stay foolish", lang: "en" }
];

const list = document.createElement("ul");
for (const { text, lang } of quotes) {
  const li = document.createElement("li");
  const q = document.createElement("q");
  q.lang = lang; // Screenreader wechseln die Aussprache
  q.textContent = text;
  li.append(q);
  list.append(li);
}
document.body.append(list);
console.log(list.innerHTML);

<li><q lang="la">Carpe diem</q></li><li><q lang="en">Stay hungry, stay foolish</q></li>

Sprachtag mit Intl validieren und normalisieren

const applyLang = (el, tag) => {
  try {
    const [canonical] = Intl.getCanonicalLocales(tag);
    el.lang = canonical;
  } catch {
    console.warn(`Ungültiger Sprachtag: ${tag}`);
  }
};

const div = document.createElement("div");
applyLang(div, "de-at");
console.log(div.lang);
applyLang(div, "de_AT");

de-AT Ungültiger Sprachtag: de_AT

// Wichtig · Fallstricke

Keine Vererbung beim Lesen: el.lang liefert "", wenn das Element selbst kein Attribut hat. Die wirksame Sprache findet man über closest("[lang]") oder in CSS mit :lang().
Keine Prüfung: Der Browser nimmt jeden String an, auch "de_DE" (Unterstrich ist in BCP 47 nicht zulässig) oder "deutsch". Mit Intl.getCanonicalLocales() lässt sich der Tag prüfen und normalisieren.
Leerer String ≠ entfernen: el.lang = "" setzt lang="" und bedeutet damit ausdrücklich unbekannte Sprache. Um wieder vom Elternelement zu erben, el.removeAttribute("lang") verwenden.
Barrierefreiheit: Ein fehlendes oder falsches lang auf <html> verletzt WCAG 3.1.1. Screenreader lesen den Text dann mit falscher Aussprache vor.
In SVG- und MathML-Elementen gibt es keine HTMLElement.lang-Eigenschaft. Dort das Attribut mit setAttribute("lang", …) setzen (bei XML zusätzlich xml:lang).
Die Eigenschaft wird in allen Browsern unterstützt. Für die Sprache der Oberfläche des Nutzers stattdessen navigator.language verwenden.

Siehe auch

Navigator.language Element.closest() HTMLElement.dir HTMLElement.nonce HTMLElement.inert