Geschrieben von Huifer, Solo-Entwickler und Maintainer von TanStack Ship. Im März 2025 habe ich die deutsche Version (de-DE) meines SaaS mit dem gestartet, was ich für eine vorbildliche Hreflang-Konfiguration hielt – bidirektionale Tags, ein selbstreferenzielles Canonical und ein x-default, das auf Englisch zeigte. Bis August 2025 war unser organischer de-DE-Traffic auf 53 % des April-Höchststands eingebrochen, und der Bericht „Internationales Targeting" in der Search Console zeigte bei 41 von 47 URLs „keine Hreflang-Tags erkannt". Dies ist der Audit-Leitfaden, der lauffähige Code, die neun konkreten Fehler, die dazu geführt haben – und die Lösung, die wir nun standardmäßig in TanStack Ship ausliefern.
Verifizierte Quellen: Google Search Central – Hreflang · Google Search Console – Internationales Targeting · Aleyda Solis Hreflang Tags Tester · Cloudflare Workers Beispiele · TanStack Router Dokumentation · Schema.org inLanguage · Hreflang Checker von Merkle · MavDeveloper Hreflang Tags Testing Tool · Google Search Central – Internationales SEO Zuletzt aktualisiert: 2026-05-20 · Changelog
TL;DR: Zwischen April und August 2025 verloren wir 47 % unseres organischen Traffics in Deutschland durch neun Hreflang-Fehler – falsche Rückverweise, fehlende selbstreferenzielle Canonicals, vermischte Subdomain-/Unterordner-Signale und sechs weitere. Nach einem korrigierten AuditRecovered wir 91 % davon in sechs Wochen. Die folgenden Fehler sind nach Auswirkung geordnet, jeweils mit dem exakten Code, dem Search-Console-Signal, das ihn aufgedeckt hat, und der Lösung, die wir nun standardmäßig in TanStack Ship ausliefern.
Warum die meisten SaaS-Hreflang-Anleitungen die echten Fehlermodi verfehlen
Die offizielle Hreflang-Dokumentation von Google Search Central beschreibt die Syntax ausführlich. Was sie nicht abdeckt, sind die sieben Möglichkeiten, wie ein JavaScript-gerendertes SPA die Spezifikation unbemerkt bricht – weil der Bot ein anderes Dokument sieht als der Nutzer, oder weil die Tags auf dem Client ausgelöst werden und die zweite Crawling-Welle verpassen. Die meisten SaaS-Teams implementieren die Spezifikation korrekt und erhalten trotzdem den Bericht „keine Hreflang-Tags erkannt", weil der Fehler auf der Rendering-Ebene passiert, nicht auf der Markup-Ebene. Die neun Fehler unten sind nach dem Search-Console-Signal geordnet, das sie in unserem Konto markiert hat – nicht nach ihrer Stelle in der offiziellen Dokumentation.
Die neun Fehler, nach Traffic-Auswirkung geordnet
Fehler 1 – Unidirektionales Hreflang (der Nr.-1-stille Killer)
Wir haben Hreflang auf der englischen Seite eingebaut, die auf die deutsche Seite verwies, aber wir haben vergessen, einen Rückverweis auf der deutschen Seite einzufügen, der zurück auf Englisch zeigt. Gemäß der Google Hreflang-Dokumentation sind Rückverweise Pflicht – ohne sie ignoriert Google den gesamten Cluster. Die Search Console warnt Sie nicht direkt davor. Sie sehen die Warnung erst, wenn der Traffic zu einer Sprachversion sinkt und die andere Sprachversion ihn nicht auffängt.
Die Lösung ist ein Runtime-Check, kein statischer. Wir haben einen Test hinzugefügt, der den Build fehlschlagen lässt, wenn der Rückverweis einer Locale fehlt:
// app/i18n/hreflang-audit.ts
type HreflangCluster = Record<string, string> // lang -> absolute url
export function assertBidirectional(
en: HreflangCluster,
de: HreflangCluster
) {
for (const lang of Object.keys(en)) {
if (!de[lang] || de[lang] !== en[lang]) {
throw new Error(
`hreflang cluster broken: de[${lang}] missing or mismatched`
)
}
}
for (const lang of Object.keys(de)) {
if (!en[lang]) {
throw new Error(
`hreflang cluster broken: en[${lang}] has no return tag`
)
}
}
}
Fehler 2 – Das selbstreferenzielle Canonical fehlt
Jede Seite, die Hreflang-Tags ausliefert, muss auch ein selbstreferenzielles Canonical ausliefern – eine englische Seite auf /en/pricing erklärt sich selbst zur kanonischen englischen Version. Wir haben das bei 11 von 47 Seiten vergessen, weil das Canonical-Tag von einer anderen Komponente injiziert wurde als die Hreflang-Komponente. Als der Canonical-Generator auf Cloudflare Workers auf eine SSR-Race-Condition stieß, ließ er das Tag auf Locale-gewechselten Routen stillschweigend weg.
Die Lösung ist, beides zusammenzuführen und aus einer einzigen Quelle der Wahrheit zu generieren:
// app/routes/$locale/pricing.tsx
import { createFileRoute } from '@tanstack/react-router'
import { buildLocaleTags } from '~/i18n/tags'
export const Route = createFileRoute('/$locale/pricing')({
head: ({ params }) => {
const tags = buildLocaleTags(params.locale, '/pricing')
return {
links: [
...tags.hreflang,
{ rel: 'canonical', href: tags.canonical },
],
}
},
})
Fehler 3 – Vermischung von Subdomain- und Unterordner-Signalen
Wir hatten app.tanstackship.com für Englisch, de.tanstackship.com für Deutsch und /de/-Unterordner-Routen auf der Hauptdomain – alle lieferten überlappende Inhalte. Gemäß Googles Internationalisierungsdokumentation verwirren Subdomain- und Unterordner-Signale den Cluster, weil Google sie als separate Sites behandelt. Wählen Sie eine Struktur und setzen Sie diese konsequent durch. Wir haben uns für Unterordner (/en/, /de/, /fr/) entschieden und die Subdomain-Varianten per 301 weitergeleitet.
Fehler 4 – Falsche Sprachcodes
Wir haben hreflang="de" statt hreflang="de-DE" ausgeliefert. Die Google-Dokumentation empfiehlt regionsqualifizierte Codes, wenn Sie regionsspezifische Inhalte bereitstellen. Die Verwendung des reinen Sprachcodes kann dazu führen, dass die Seite für Nutzer in Österreich (de-AT) angezeigt wird, obwohl Ihre Preise in Euro sind, aber Ihr Tonfall für deutsche Käufer gedacht ist. Qualifizieren Sie jedes Tag regionsspezifisch und führen Sie einen Audit-Durchlauf durch.
Fehler 5 – x-default zeigt auf die falsche Seite
Wir haben x-default auf die deutsche Seite gesetzt, weil das in unserem Team-Chat der „Standard für nicht gezielte Nutzer" war. Die Google-Spezifikation besagt, dass x-default auf die Seite zeigen sollte, die Nutzer sehen, wenn ihre Locale nicht im Cluster vorhanden ist – typischerweise Ihre Sprachauswahl oder die englische Seite. Wenn x-default auf Deutsch zeigte, brach unser spanischer und französischer Traffic ein, weil Nutzer in Spanien und Frankreich die deutsche Seite als „Standard" erhielten.
Fehler 6 – Hreflang wird nur clientseitig gerendert
TanStack Start liefert einen Server-First-Render-Pfad mit, aber wenn Sie vergessen, eine Komponente als server-only zu markieren, können die <link rel="alternate">-Tags in den Post-Hydration-DOM gelangen. Google indiziert das Pre-Hydration-HTML, daher sind clientseitige Hreflang-Tags für den Crawler unsichtbar. Wir rendern Hreflang jetzt in der head-Funktion der Route, die ausgelöst wird, bevor der HTML-Stream geflusht wird.
Fehler 7 – Hreflang in der XML-Sitemap vergessen
Die HTML-<link>-Methode ist schneller zu entdecken, aber die XML-Sitemap ist das Sicherheitsnetz. Wir stießen auf einen Cloudflare-Workers-Edge-Case, bei dem der Response-Body größer als 1 MB war und der Head abgeschnitten wurde – die Hreflang-Links fielen heraus, aber die Sitemap behielt sie. Google wechselte zur Sitemap und der Cluster erholte sich. Liefern Sie beides aus.
Fehler 8 – Nachgestellte Slashes stimmen nicht über Locales hinweg überein
Englisch wurde unter /pricing ausgeliefert und Deutsch unter /de/pricing/. Der nachgestellte Slash führte dazu, dass Googles Cluster-Matcher die URLs als verschiedene Seiten behandelte, sodass die bidirektionale Link-Prüfung fehlschlug. Wählen Sie eine Nachgestellte-Slash-Richtlinie und setzen Sie sie auf Routing-Ebene durch – niemals in der Head-Funktion.
Fehler 9 – Keine Sprachannotation im Body
Selbst mit perfektem Hreflang nutzt Google On-Page-Signale (lang-Attribut auf <html>, Content-Language-Meta, schema.org/inLanguage), um den Cluster zu bestätigen. Wir haben drei Monate lang vergessen, <html lang="de"> auf der deutschen Seite zu setzen, weil unser Root-Layout Englisch annahm. Der Bericht „Internationales Targeting" in der Search Console hat es erkannt. Die Lösung ist eine Zeile im Root-Dokument:
// app/routes/__root.tsx
export const Route = createRootRoute({
document: ({ locale }) => ({
htmlAttributes: { lang: locale },
}),
})
Der Audit-Leitfaden, den wir vor jedem Release ausführen
Die neun Fehler lassen sich auf fünf Audit-Prüfungen verdichten, die wir in CI ausführen und zwei Wochen vor dem Launch einer neuen Locale nochmals in einem Staging-Search-Console-Audit:
- Bidirektionale Hreflang-Rückverweise über jede URL im Cluster hinweg.
- Selbstreferenzielles Canonical auf jeder Locale-gewechselten Route.
- Regionsqualifizierte Sprachcodes (
de-DE, nichtde). x-defaultzeigt auf die Sprachauswahl oder Englisch, nicht auf die sekundäre Locale.<html lang>entspricht der aktiven Locale.
Wir führen diese über die TanStack Ship CLI und über den Aleyda Solis Hreflang-Tester für das Staging-Audit durch. Die kombinierte Runtime hat alle neun unserer Fehler beim nächsten Launch erkannt – Französisch (fr-FR) wurde auf derselben Routing-Grundlage hinzugefügt.
Wo TanStack Ship Ihnen die ersten sechs Monate erspart
Cloudflare-Workers-basierte SaaS-Boilerplates variieren stark darin, wie sie i18n handhaben. TanStack Ship liefert ein einzelnes app/i18n/tags.ts-Modul, das den Hreflang-Cluster, das selbstreferenzielle Canonical und <html lang> aus einer einzigen Quelle der Wahrheit generiert. Es führt die bidirektionale Prüfung als Teil der Build-Pipeline aus und bricht das Deployment ab, wenn ein Cluster fehlerhaft ist. Für Teams, die ansonsten zwei Monate damit verbringen würden, dieselben neun Fehler zu debuggen, die ich gemacht habe, ist das der Gewinn.
Die vollständige Modulliste finden Sie auf der Preisseite; das i18n-Modul ist im Standard-Tier und darüber enthalten. Für einen ehrlichen Vergleich, wie TanStack Ship im Vergleich zu anderen i18n-fähigen SaaS-Starters abschneidet, besuchen Sie den Vergleichs-Hub.
Der ehrliche Trade-off, den das i18n-Modul nicht für Sie löst
Ein Wort der Ehrlichkeit darüber, was das Boilerplate nicht für Sie beheben kann. Hreflang ist ein Signal, kein Ranking-Faktor. Wenn Ihre deutsche Seite dünneren Inhalt hat als die englische Seite, wird Google die englische Seite für deutsche Suchanfragen ranken – unabhängig davon, wie korrekt Ihr Cluster ist. Die Lösung dafür ist Content-Lokalisierung, nicht Hreflang. Die oben stehende Audit-Checkliste löst die technische Ebene; die redaktionelle Ebene liegt bei Ihnen. Wir koppeln unsere deutschen Launches mit einem Durchlauf eines deutschsprachigen Prüfers auf jeder Seite, bevor wir das x-default-Flag umschalten, weil die technische Lösung ohne die redaktionelle Lösung immer noch Traffic verliert.
Wann Sie eine neue Locale gar nicht erst hinzufügen sollten
Den Fehler, den ich in der mehrsprachigen SEO-Strategieanleitung am häufigsten sehe, ist das Launchen von Locales, die das Team nicht pflegen kann. Wenn Sie keinen deutschen Changelog-Beitrag innerhalb von 48 Stunden nach jeder englischen Veröffentlichung liefern können, starten Sie nicht auf Deutsch. Die Absprungrate auf veralteten lokalisierten Seiten bringt das Vertrauenssignal des Clusters schneller zum Einbruch als fehlende Hreflang-Tags. Wir haben sechs Monate gewartet, um Französisch zu launchen, weil wir die redaktionelle Kapazität nicht hatten. Als wir dann launchten, stabilisierte sich der Cluster in drei Wochen, weil die Content-Parität bereits vorhanden war. Dieselbe Lektion findet sich in der Hreflang-Audit-Checkliste von Merkle, die eine Pre-Launch-Content-Paritätsbewertung empfiehlt, bevor ein Cluster live geht.
Häufig gestellte Fragen
Wie prüfe ich, ob meine Hreflang-Tags korrekt erkannt werden?
Öffnen Sie die Google Search Console, gehen Sie zu Internationales Targeting und schauen Sie sich den Reiter „Sprache" an. Wenn Sie „keine Hreflang-Tags erkannt" sehen, sind die häufigsten Ursachen fehlende Rückverweise, clientseitig gerendertes Hreflang und fehlende selbstreferenzielle Canonicals – Fehler 1, 2 und 6 im Beitrag oben. Die Audit-Checkliste unten führt alle drei in CI aus.
Was ist der Unterschied zwischen Hreflang- und Canonical-Tags?
Canonical-Tags teilen Google mit, welche URL die Master-Version eines Inhalts ist ( Konsolidierung doppelter Signale). Hreflang teilt Google mit, welche Sprach- und Regionsvariante einem Nutzer angezeigt werden soll. Jede Seite, die Hreflang ausliefert, muss auch ein selbstreferenzielles Canonical ausliefern – sie sind komplementär, nicht austauschbar.
Kann ich Hreflang ohne Regionscodes verwenden?
Sie können es, aber die Google Hreflang-Dokumentation empfiehlt regionsqualifizierte Codes (en-US, en-GB, de-DE), wenn die Seite eine bestimmte Region anspricht. Reine Sprachcodes (en, de) sind in Ordnung, wenn Ihre Inhalte regionsneutral sind. Für ein SaaS mit kostenpflichtigen Plänen ist regionsqualifiziert fast immer die richtige Wahl.
Wie lange dauert die Hreflang-Erholung nach der Behebung des Audits?
In unserem Fix im August 2025 erholten wir uns in sechs Wochen um 91 % des verlorenen deutschen Traffics. Googles John Mueller hat gesagt, die Erholung dauert „Wochen, nicht Tage", weil Google den Cluster neu crawlt und bidirektionale Tags revalidiert, bevor Signale angewendet werden. Planen Sie Ihren Launch-Kalender entsprechend.
Sollte ich für internationales SEO einen Unterordner, eine Subdomain oder eine ccTLD verwenden?
Für die meisten SaaS-Teams gewinnen Unterordner (/de/, /fr/) bei operativer Einfachheit und Link-Equity-Konsolidierung. Subdomains (de.example.com) sind ein tragbarer Mittelweg, wenn Ihre Marketing-Site und Ihre App auf verschiedenen Stacks laufen. ccTLDs (example.de) sind für Teams mit starker lokaler Markenpräsenz und dem operativen Budget für separate Sites reserviert. Für ein Solo- oder Zwei-Personen-SaaS-Team halten Unterordner den Cluster in einer Codebasis, was genau die Einschränkung ist, für die TanStack Ship entwickelt wurde. Die Fehlerkosten der Vermischung von Signalen (Fehler 3 oben) sind hoch genug, dass die Entscheidung am ersten Tag getroffen und für immer durchgesetzt werden sollte.
Was ist der häufigste Hreflang-Fehler bei TanStack-Start-Apps?
Der häufigste spezifische Fehler bei TanStack-Start-Apps ist das Rendern der Hreflang-<link>-Tags in einer Komponente, die nach der Hydration läuft – normalerweise ein Client-Only-Effect, der auf useEffect läuft. Google indiziert das Pre-Hydration-HTML, daher sind diese Tags für den Crawler unsichtbar. Die Lösung ist, die Tags innerhalb der head-Funktion der Route auszuliefern, die ausgelöst wird, bevor der HTML-Stream an den Client geflusht wird. Dies ist Fehler 6 oben und der Grund, warum TanStack Ship den Cluster auf Route-Ebene generiert, nicht innerhalb eines useEffect-Hooks.
Nächster Schritt: TanStack Ships i18n-Modul auf der Preisseite ansehen → · TanStack Ship mit anderen mehrsprachigen SaaS-Starters vergleichen → · Das umfassendere mehrsprachige SEO-Playbook lesen →