Signatur
Beschreibung
Die Eigenschaft hreflang des HTMLLinkElement-Interfaces spiegelt das HTML-Attribut hreflang wider. Sie enthält ein Sprach-Tag nach BCP 47, z. B. "de", "de-AT", "en-US" oder den Sonderwert "x-default". Damit gibt sie die Sprache (und gegebenenfalls die Region) der Ressource an, auf die der Link verweist, nicht die Sprache des aktuellen Dokuments.
In der Praxis wird das Attribut vor allem mit rel="alternate" eingesetzt. So kann man Suchmaschinen und anderen Clients mitteilen, dass eine Seite in anderen Sprach- oder Länderversionen existiert (Stichwort hreflang-SEO). Mit JavaScript kann man diese Alternativen auslesen, etwa um einen Sprachumschalter aufzubauen, oder in Single-Page-Anwendungen dynamisch setzen.
Die Eigenschaft ist ein reiner String-Reflektor: Beim Lesen erhält man den Attributwert oder einen leeren String, wenn das Attribut fehlt. Beim Schreiben wird das Attribut gesetzt. Der Browser prüft das Sprach-Tag nicht und normalisiert es auch nicht.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $value | string | "" | Beim Setzen: ein BCP-47-Sprach-Tag wie "fr", "pt-BR" oder "x-default". |
Rückgabewert
hreflang-Attributs. Fehlt das Attribut, ist es ein leerer String "".Beispiele
hreflang eines vorhandenen Links auslesen
// HTML: <link rel="alternate" href="https://example.com/en/" hreflang="en-US">
const link = document.querySelector('link[rel="alternate"]');
console.log(link.hreflang);Sprachumschalter aus alternate-Links erzeugen
const alternates = [...document.querySelectorAll('link[rel="alternate"][hreflang]')];
const nav = document.createElement('nav');
for (const { hreflang, href } of alternates) {
if (hreflang === 'x-default') continue;
const a = document.createElement('a');
a.href = href;
a.hreflang = hreflang; // auch HTMLAnchorElement kennt hreflang
a.textContent = hreflang.toUpperCase();
nav.append(a, ' ');
}
document.body.prepend(nav);
console.log(alternates.map((l) => l.hreflang));Alternate-Link in einer SPA dynamisch setzen
const setAlternate = (lang, url) => {
let link = document.head.querySelector(`link[rel="alternate"][hreflang="${lang}"]`);
if (!link) {
link = document.createElement('link');
link.rel = 'alternate';
link.hreflang = lang;
document.head.append(link);
}
link.href = url;
return link;
};
const l = setAlternate('de-AT', 'https://example.com/at/produkte');
console.log(l.outerHTML);// Wichtig · Fallstricke
- Keine Prüfung: Der Browser nimmt jeden String an, auch ungültige Werte wie
"deutsch"oder"en_US"(Unterstrich statt Bindestrich). Wenn du prüfen willst, ob ein Tag gültig ist, kannst duIntl.getCanonicalLocales()verwenden. Diese Funktion wirft bei ungültigen Tags einenRangeError. - Nur ein Hinweis:
hreflangbeeinflusst weder das Laden noch das Rendern der Ressource. - SEO: Suchmaschinen werten hreflang-Links meist nur aus, wenn sie schon im ausgelieferten HTML stehen. Per JavaScript nachträglich gesetzte Links werden womöglich nicht erkannt. Außerdem sollten die Verweise gegenseitig sein, also jede Sprachversion auf alle anderen zeigen.
- Die Sprache des aktuellen Dokuments steht nicht hier, sondern in
document.documentElement.lang. - Browser-Kompatibilität: wird von allen gängigen Browsern seit Langem unterstützt.