hreflang Tags: Der ultimative Leitfaden

Geschrieben von Huifer, Solo-Entwickler und Maintainer von TanStack Ship. Im März 2026 habe ich die mehrsprachige Schicht einer TanStack-Start-App auf Cloudflare Workers ausgeliefert und zugesehen, wie /de/pricing 19 Tage lang unsichtbar in Google blieb, bevor ich den fehlenden Return-Link-Bug entdeckt habe. Seitdem bin ich auf acht verschiedene hreflang-Fehler gestoßen. Dieser Leitfaden ist das Post-mortem von allem – plus die Implementierungsreferenz, die ich jetzt beim Shippen stets offen halte.

Verifizierte Quellen: Google Search Central — Manage multi-regional and multilingual sites · Google Search Central — hreflang documentation · schema.org hreflang property · Ahrefs hreflang guide · Moz hreflang guide · Semrush hreflang guide · Screaming Frog hreflang validation · Bing hreflang support · Yandex language meta · TanStack Ship GitHub Organization Zuletzt aktualisiert: 11. August 2026 · Changelog

TL;DR: hreflang-Tags teilen Suchmaschinen mit, welche Sprach- und Regionalvariante einer Seite für welche Nutzerin angezeigt werden soll. Sie leben an drei Stellen – als HTML-<link>-Tags, in einer XML-Sitemap oder in HTTP-Headern für Nicht-HTML-Dateien. Die Implementierung ist klein. Die Fehlermodi sind es nicht. Die acht Fallstricke unten machen die Mehrheit aller Production-hreflang-Bugs aus, die ich je debuggt habe.

Was hreflang-Tags tatsächlich bewirken

hreflang ist ein Signal, keine Direktive. Suchmaschinen dürfen es verwenden – müssen es aber nicht. Bei korrekter Implementierung erledigt es drei konkrete Aufgaben.

Sprache-zu-URL-Abbildung. Wenn eine Nutzerin in Berlin nach einer Anfrage sucht, für die /en/pricing rankt, teilt hreflang Google mit, /de/pricing für deutschsprachige Anfragen zu bevorzugen – selbst wenn die englische Seite eine höhere Domain-Autorität hat.
Übersetzungs-Clustering. hreflang gruppiert Übersetzungsseiten miteinander. Das verhindert, dass Google Ihre englische und deutsche Preisseite als Duplicate Content behandelt und beide herabstuft.
Regionales Targeting. Mit Locale-Codes wie en-GB und en-US teilen Sie Google mit, welche regionale Variante angezeigt werden soll – britische Pfund-Preise auf der UK-Seite, Dollar-Preise auf der US-Seite.

Gemäß der Google Search Central-Dokumentation ist hreflang das einzige Signal, das Google offiziell für seitenübergreifende Sprachbeziehungen unterstützt.

hreflang vs. Canonical – die häufigste Verwechslung

rel="canonical" sagt: „Diese beiden URLs sind dieselbe Seite. Wählen Sie eine."
rel="alternate" hreflang="xx" sagt: „Diese URLs sind Übersetzungen. Zeigen Sie die richtige pro Nutzer."

Ein selbst-referenzielles Canonical ist zusammen mit hreflang erforderlich. Ein Canonical, das jede Sprachvariante auf die englische Seite zurückweist, bricht hreflang. Der Leitfaden zur mehrsprachigen SEO-Strategie behandelt das Canonical-und-hreflang-Paar.

Anatomie eines hreflang-Tags

Das rel="alternate" hreflang="xx"-Muster

html

<link rel="alternate" hreflang="en" href="https://tanstackship.com/en/pricing" />
<link rel="alternate" hreflang="de" href="https://tanstackship.com/de/pricing" />
<link rel="alternate" hreflang="zh-Hans" href="https://tanstackship.com/zh-Hans/pricing" />
<link rel="alternate" hreflang="x-default" href="https://tanstackship.com/en/pricing" />

Jedes Tag sagt: „Es gibt eine alternative Version dieser Seite in Sprache X unter dieser URL." Jede Seite im Cluster muss jede andere Seite auflisten – einschließlich eines Selbstverweises.

Sprachcodes vs. Locale-Codes

Gemäß der Google hreflang-Dokumentation gibt es zwei Formate:

Nur Sprache: en, de, zh. Dieselben Inhalte werden für jede Region mit dieser Sprache ausgeliefert.
Sprache-Region: en-GB, en-US, pt-BR, zh-Hans, zh-Hant. Inhalte variieren nach Region – Währung, Einheiten, rechtliche Begriffe.

Das Trennzeichen ist ein Bindestrich. Kein Unterstrich. Ich habe einmal en_US geshipped, und der Bug hat vier Tage gebraucht, um aufzutauchen, weil Google ungültige Codes stillschweigend ignoriert. Siehe Fallstrick #2.

x-default – der Fallback, den niemand setzt

x-default ist das Escape-Hatch der Spezifikation. Es teilt Suchmaschinen mit, welche Seite angezeigt werden soll, wenn keine andere Variante zur Sprache der Nutzerin passt. Der typische Wert ist Ihre Locale-Switcher-Seite oder die Standard-Locale-Landingpage. Wenn Sie es weglassen, rät Google – und liegt in etwa 30 % der Fälle falsch. Der Ahrefs hreflang-Leitfaden erläutert die x-default-Semantik.

Implementierungsmethoden im Vergleich

HTML-Head-Tags

Die einfachste Methode. Jede Seite rendert <link rel="alternate">-Tags, die auf jede andere Sprachvariante zeigen. Erfordert dynamische Generierung pro Seite, wenn Inhalte Routen haben – eine JavaScript-gerenderte SPA ohne SSR liefert hreflang-loses HTML an den Crawler. Das ist die Hauptursache der meisten modernen SPA-hreflang-Fehler.

XML-Sitemap mit xhtml:link

Zentralisierte Deklaration. Jede URL wird einmal aufgelistet mit einem <xhtml:link rel="alternate" hreflang="x" href="..."/> für jede Alternative. Von Google für große mehrsprachige Websites empfohlen. Skaliert gut.

HTTP-Link-Header

Für Nicht-HTML-Dateien – PDFs, reinbildbasierte Seiten, Video-Manifeste:

Link: <https://tanstackship.com/en/whitepaper.pdf>; rel="alternate"; hreflang="en",
      <https://tanstackship.com/de/whitepaper.pdf>; rel="alternate"; hreflang="de"

Verwenden Sie dies nur, wenn HTML und Sitemap nicht möglich sind. Die meisten Teams vergessen, dies zu pflegen.

Best Practice: HTML und Sitemap kombiniert einsetzen

HTML-Tags für schnelle Erkennung auf kleinen Websites. Sitemap für Vollständigkeit auf großen Websites und als Fallback, wenn ein Rendering pro Seite fehlschlägt. Der Google-Crawler verwendet das, was er zuerst sieht.

hreflang in Single-Page Apps implementieren

SPAs sind der Ort, an dem die meisten hreflang-Fehler entstehen. Statische HTML-Dateien können hartcodierte Tags ausliefern. SPAs nicht.

Warum SPAs den einfachen Fall brechen

Eine Client-only-React-App rendert serverseitig einen leeren <head> und füllt ihn nach der Hydration. Googlebot kann warten, aber das gerenderte DOM muss trotzdem die richtigen <link>-Tags enthalten – und viele SPA-Router setzen standardmäßig keine Sprachalternativen in den Head.

Drei Lösungen, nach SEO-Zuverlässigkeit gereiht:

Server-side Rendering (empfohlen). TanStack Start, Next.js App Router und Remix unterstützen alle das Injizieren von Head-Tags pro Route. Das hreflang-Markup ist in der ursprünglichen HTML-Antwort enthalten. Crawler sehen es sofort. Das habe ich im März 2026 geshipped – mehr dazu im TanStack Ship i18n-Modul.
Pre-Rendering pro Locale. Bauen Sie eine statische HTML-Datei pro Route pro Locale zum Build-Zeitpunkt. Tags sind eingebacken.
Client-seitige Injektion mit Verifizierung. Injizieren Sie per JavaScript nach einem Routenwechsel. Google hat öffentlich bekannt gegeben, dass HTML-link-tag hreflang bevorzugt wird.

Server-seitige Injektion in einer TanStack Start Root Route

typescript

// src/lib/hreflang.ts
interface HreflangConfig {
  baseUrl: string
  currentPath: string
  locales: readonly string[]
  defaultLocale: string
}

export function buildHreflangLinks(config: HreflangConfig): Array<{ lang: string; href: string }> {
  const { baseUrl, currentPath, locales, defaultLocale } = config
  const normalizedPath = stripLocalePrefix(currentPath, locales)

  const links = locales.map((locale) => ({
    lang: locale,
    href: `${baseUrl}/${locale}${normalizedPath}`,
  }))

  links.push({
    lang: "x-default",
    href: `${baseUrl}/${defaultLocale}${normalizedPath}`,
  })

  return links
}

function stripLocalePrefix(path: string, locales: readonly string[]): string {
  const re = new RegExp(`^/(${locales.join("|")})(?=/|$)`)
  return path.replace(re, "") || "/"
}

tsx

// src/routes/__root.tsx
export const Route = createRootRoute({
  head: ({ match }) => {
    const links = buildHreflangLinks({
      baseUrl: "https://tanstackship.com",
      currentPath: match.pathname,
      locales: ["en", "de", "zh-Hans", "es"],
      defaultLocale: "en",
    })

    return {
      links: links.map(({ lang, href }) => ({
        rel: "alternate",
        hreflang: lang,
        href,
      })),
    }
  },
})

Der Crawler erhält den vollständigen hreflang-Cluster in der ursprünglichen HTML. Kein JavaScript erforderlich.

Dynamischer Locale-Wechsel ohne Verlust der Alternates

Wenn eine Nutzerin auf den Locale-Switcher klickt und die URL client-seitig wechselt, muss die neue Route den Cluster neu ausgeben. Wenn Ihr Router die Head-Tags der vorherigen Route zwischenspeichert, werden die Alternates veraltet. TanStack Routers head-Funktion ist pro Match, also wird sie bei Navigation neu ausgeführt – aber wenn Sie den Head-Kontext zwischenspeichern, müssen Sie ihn bei Locale-Wechsel invalidieren. Ich habe diesen Bug zweimal geshipped.

Fallstricke, die ich tatsächlich erlebt habe

Jeder davon ist ein realer Production-Bug, den ich auf TanStack-Ship-Infrastruktur debuggt habe.

Fallstrick #1 – Fehlende Return-Links

Der #1 hreflang-Fehler weltweit. Wenn Seite A auf Seite B mit hreflang="de" zeigt, muss Seite B zurück auf Seite A mit hreflang="en" zeigen. Die Beziehung ist bidirektional.

Im März 2026 habe ich hreflang-Tags geshipped, die jede Sprachvariante auf jede andere zeigten – außer ich hatte vergessen, den Head der deutschen Seite neu zu generieren, als ich es zum Cluster hinzugefügt habe. Die deutsche Seite zeigte nur noch auf Englisch und auf sich selbst. Google behandelte den gesamten Cluster als einseitig und ignorierte ihn. /de/pricing war 19 Tage lang unsichtbar.

Die Lösung: ein Unit-Test, der_assertiert, dass die Anzahl der Alternates gleich locales.length + 1 ist (das +1 ist x-default) auf jeder Seite. Ich shippe diesen Test jetzt in jedem PR, das die Locale-Konfiguration berührt.

Fallstrick #2 – Unterstrich in Sprachcodes

Die Spezifikation ist en-US. Nicht en_US. Nicht EN-US. Google ignoriert ungültige Codes stillschweigend – kein Konsolenfehler, keine Search-Console-Warnung, das Tag matches einfach nichts. Gemäß der schema.org hreflang-Property ist das Format BCP 47, das Bindestriche verwendet.

Fallstrick #3 – Widersprüchliche Canonical- und hreflang-Signale

Ein selbst-referenzielles Canonical ist erforderlich. Ein Canonical, das jede Sprachvariante auf die englische Seite zurückweist, ist ein Bug – es teilt Google mit, dass die englische Seite die kanonische Version jeder Sprache ist, und widerspricht damit dem hreflang-Cluster. Der Moz hreflang-Leitfaden zeigt ein klares Beispiel für das Canonical-hreflang-Paar.

Fallstrick #4 – x-default vergessen

Das am häufigsten fehlende Tag. Ein hreflang-Cluster ohne x-default ist technisch gültig, aber operativ unvollständig.

Fallstrick #5 – Locale-Codes, die nicht zur Inhaltssprache passen

Wenn Ihr HTTP-Content-Language-Header en sagt, aber Ihr hreflang-Tag en-US, widersprechen sich die beiden Signale. Google bevorzugt hreflang, aber das Missverhältnis verwirrt Audit-Tools. Wählen Sie eine einzige Quelle der Wahrheit.

Fallstrick #6 – Ländercodes ohne Sprache

hreflang="US" ist nicht gültig. Das erste Segment muss ein Sprachcode sein. hreflang="en-US" ist gültig. Dieser Fehler entsteht durch die Verwechslung von hreflang mit einer regionalen Weiterleitung oder einem CDN-Geo-Targeting.

Fallstrick #7 – Dynamische Routen-Staleness bei Client-Navigation

Bereits oben erwähnt. Wenn die Nutzerin den Locale client-seitig wechselt, ohne dass die Seite komplett neu lädt, können die Head-Tags der vorherigen Route persistieren. Geben Sie den Cluster bei jedem Locale-Wechsel immer neu aus und _assertieren Sie, dass er innerhalb von 100 ms nach der Navigation aktualisiert wird.

Fallstrick #8 – hreflang implementieren, ohne hreflang auf dem Rückweg zu implementieren

Dasselbe wie Fallstrick #1, aber separat aufgelistet, weil der Fehlermodus ein anderer ist. Seite A zeigt auf Seite B. Seite B hat überhaupt keine hreflang-Tags – vielleicht weil es eine Marketing-Landingpage ohne Head-Management ist. Der Cluster ist unvollständig; Google behandelt Seite B als nicht übersetzt.

Validierung: So verifiziere ich hreflang

Drei Checks, nach Aufwand geordnet. Fünf Minuten insgesamt.

Google Search Console – International Targeting

Der International Targeting Report zeigt, welche Sprache und welches Land Ihre Website pro URL anpeilt. Bei korrekter Implementierung erscheint jede Seite unter ihrer deklarierten Sprache. Wenn eine Seite fehlt oder unter der falschen Sprache erscheint, ist der Cluster defekt.

Der Haken: Der Report aktualisiert sich mit einer Verzögerung von mehreren Wochen. Neue Tags können 3–6 Wochen brauchen, um aufzutauchen. Der Semrush hreflang-Leitfaden bespricht diese Verzögerung und empfiehlt, den Report einmal beim Launch und erneut 60 Tage später auszuführen.

Screaming Frog hreflang-Validierung

Der Screaming Frog SEO Spider crawled Ihre Website, extrahiert jedes hreflang-Tag und validiert den bidirektionalen Cluster. Er markiert fehlende Return-Links, ungültige Sprachcodes und Nicht-kanonische hreflang-URLs. Die kostenlose Version deckt bis zu 500 URLs ab.

Das ist mein Pre-Launch-Check. Jeder hreflang-PR läuft durch Screaming Frog, bevor er gemergt wird.

Ein curl-Spot-Check

Für einen schnellen Plausibilitätscheck:

bash

curl -s https://tanstackship.com/en/pricing | grep 'hreflang='

Sie sollten ein <link rel="alternate" hreflang="...">-Tag pro Locale plus x-default sehen. Wenn Sie weniger sehen, ist der Cluster unvollständig. Wenn Sie hreflang="en_US" sehen, ist Fallstrick #2 in Production.

Abschließende Gedanken und was Sie zuerst shippen sollten

Wenn Sie dies lesen, bevor Sie hreflang geshipped haben, hier ist die Reihenfolge der Operationen, die mir die meiste Nacharbeit erspart hat:

Entscheiden Sie Locales und Sprach-Region-Format vor dem Programmieren. BCP 47 mit Bindestrichen. Fügen Sie x-default ab Tag eins hinzu.
Generieren Sie den Cluster serverseitig. Client-only-Injektion ist für SEO unzuverlässig.
Schreiben Sie den bidirektionalen Test. Asserten Sie, dass jede Seite locales.length + 1 Alternates hat. Führen Sie ihn bei jedem PR aus.
Fügen Sie Screaming Frog zur Pre-Launch-Checkliste hinzu. Fünf Minuten. Fängt alles ab.
Planen Sie einen 60-Tage-Search-Console-Review. Der International Targeting Report hat Verzögerungen.

Für die breitere mehrsprachige Architektur – Locale-Routing, Message-Extraktion, Währungshandling – durchläuft der Beitrag i18n-Architektur-Patterns den vollständigen Stack. Der Beitrag SaaS-Globalisierungsstrategie behandelt die Positionierungsseite: was zuerst zu lokalisieren ist, was zu überspringen ist, wie der ROI pro Markt gemessen wird.

hreflang ist klein. Es ist auch eines der fehleranfälligsten Stücke technischer SEO, weil die Fehlermodi stumm sind – Google warnt Sie nicht, Search Console hinkt Wochen hinterher, und falschsprachiger Traffic sieht wie ein Lokalisierungsbug aus, nicht wie ein SEO-Bug. Der Unit-Test plus der Screaming-Frog-Check verwandeln stumme Fehler in laute.

Über diesen Artikel

Geschrieben von Huifer, Solo-Entwickler und Maintainer von TanStack Ship. Hat seit 2023 mehr als zwölf Production-TanStack-Apps auf Cloudflare Workers geshipped. Die hreflang-Implementierung in TanStack Ships i18n-Modul ist seit März 2026 in Production.
Verifizierte Quellen: Google Search Central — hreflang documentation · schema.org hreflang property · Ahrefs hreflang guide · Moz hreflang guide · Semrush hreflang guide · Screaming Frog hreflang validation · Bing hreflang support · Yandex language meta · TanStack Ship GitHub Organization
Zuletzt aktualisiert: 11. August 2026 · Changelog

Mit TanStack Ship starten – der TanStack Start SaaS-Starter, der hreflang, Canonical-Paarung, Locale-Routing und die Verifizierungstests aus diesem Beitrag standardmäßig mitliefert. Preise ansehen · Alternativen vergleichen · Blog lesen