Wie man alternative Sprachversionen in TanStack Start v1 verlinkt

Sprachalternativen für Suchmaschinen verlinken

Problem

Wenn eine Website denselben Inhalt in mehreren Sprachen anbietet, behandeln Suchmaschinen standardmäßig jede Sprachversion als separate Seite. Ohne explizite Signale, die diese Versionen verbinden, können Suchmaschinen nicht verstehen, dass /en/about und /fr/about Übersetzungen desselben Inhalts sind und nicht konkurrierende Duplikate. Diese Fragmentierung teilt die Ranking-Autorität auf verschiedene Sprachversionen auf und erzeugt Zustellungsprobleme: Ein französischsprachiger Benutzer könnte die englische Version in den Suchergebnissen höher eingestuft sehen, obwohl eine französische Übersetzung existiert. Suchmaschinen benötigen explizite Metadaten, um die Beziehung zwischen Sprachvarianten zu verstehen und die entsprechende Version basierend auf Sprachpräferenzen und Standort des Benutzers auszuliefern.

Lösung

Fügen Sie hreflang-Link-Elemente zum Dokumentenkopf hinzu, die alle verfügbaren Sprachversionen jeder Seite deklarieren. Diese Links teilen Suchmaschinen mit, welche URLs denselben Inhalt in verschiedenen Sprachen enthalten, sodass sie Ranking-Signale konsolidieren und die korrekte Version an Benutzer ausliefern können. Jede Seite listet alle ihre Sprachalternativen auf, einschließlich eines Verweises auf sich selbst, wodurch eine bidirektionale Beziehung entsteht, die Suchmaschinen nutzen, um die Übersetzungsstruktur zu verstehen. Diese Metadaten werden pro Route über das Head-Management-System des Frameworks hinzugefügt, das Zugriff auf die aktuellen Routenparameter hat, die zum Erstellen von URLs für alle Sprachvarianten benötigt werden.

Schritte

1. Erstellen Sie einen Helper zum Aufbau von Sprachalternativ-URLs

Die buildLocation-Methode des Routers konstruiert vollständige URLs aus Routenparametern, die Sie verwenden werden, um URLs für jede Sprachversion zu generieren.

import { AnyRouter } from "@tanstack/react-router";

export function buildLanguageAlternates(
  router: AnyRouter,
  currentPath: string,
  currentLang: string,
  availableLanguages: string[],
) {
  return availableLanguages.map((lang) => {
    const location = router.buildLocation({
      to: currentPath,
      params: { lang },
    });
    return {
      lang,
      href: `${location.pathname}${location.search}${location.hash}`,
    };
  });
}

Diese Funktion nimmt den aktuellen Routenpfad und generiert alternative URLs, indem sie jeden Sprachcode in die Routenparameter einsetzt.

2. Definieren Sie Ihre verfügbaren Sprachen

Erstellen Sie eine Konfigurationsdatei, die alle Sprachen auflistet, die Ihre Anwendung unterstützt.

export const AVAILABLE_LANGUAGES = ["en", "fr", "de", "es"];

export const DEFAULT_LANGUAGE = "en";

Diese zentralisierte Liste wird verwendet, um hreflang-Links für jede Seite zu generieren.

Die head-Funktion erhält einen Kontext, der matches, params und loaderData enthält, was Zugriff auf den aktuellen Sprachparameter und die Router-Instanz ermöglicht.

import { createFileRoute } from "@tanstack/react-router";
import { buildLanguageAlternates, AVAILABLE_LANGUAGES } from "../i18n-config";

export const Route = createFileRoute("/$lang/about")({
  head: ({ params }) => {
    const alternates = buildLanguageAlternates(
      Route.router,
      "/$lang/about",
      params.lang,
      AVAILABLE_LANGUAGES,
    );

    return {
      links: alternates.map((alt) => ({
        rel: "alternate",
        hreflang: alt.lang,
        href: alt.href,
      })),
    };
  },
  component: AboutPage,
});

function AboutPage() {
  return <div>About page content</div>;
}

Das hreflang-Attribut verwendet ISO 639-1 Sprachcodes, und jeder Link verweist auf dieselbe Seite in einer anderen Sprache.

4. Fügen Sie ein x-default hreflang für Fallback-Verhalten hinzu

Das x-default hreflang-Attribut signalisiert die Standardseite, wenn keine Sprache übereinstimmt.

export const Route = createFileRoute("/$lang/about")({
  head: ({ params }) => {
    const alternates = buildLanguageAlternates(
      Route.router,
      "/$lang/about",
      params.lang,
      AVAILABLE_LANGUAGES,
    );

    const defaultUrl = alternates.find((alt) => alt.lang === "en");

    return {
      links: [
        ...alternates.map((alt) => ({
          rel: "alternate",
          hreflang: alt.lang,
          href: alt.href,
        })),
        {
          rel: "alternate",
          hreflang: "x-default",
          href: defaultUrl?.href || alternates[0].href,
        },
      ],
    };
  },
  component: AboutPage,
});

Der x-default-Link bietet eine Fallback-URL für Benutzer, deren Sprachpräferenzen mit keiner deklarierten Alternative übereinstimmen.

5. Anwendung auf dynamische Routen mit Parametern

Für Routen mit zusätzlichen dynamischen Segmenten neben der Sprache, fügen Sie diese Parameter beim Erstellen von Alternativen ein.

export const Route = createFileRoute("/$lang/posts/$postId")({
  head: ({ params }) => {
    const alternates = AVAILABLE_LANGUAGES.map((lang) => {
      const location = Route.router.buildLocation({
        to: "/$lang/posts/$postId",
        params: { lang, postId: params.postId },
      });
      return {
        lang,
        href: `${location.pathname}${location.search}${location.hash}`,
      };
    });

    return {
      links: [
        ...alternates.map((alt) => ({
          rel: "alternate",
          hreflang: alt.lang,
          href: alt.href,
        })),
        {
          rel: "alternate",
          hreflang: "x-default",
          href:
            alternates.find((a) => a.lang === "en")?.href || alternates[0].href,
        },
      ],
    };
  },
});

Jede Seite muss auf alle ihre Sprachversionen verweisen, einschließlich sich selbst, um sicherzustellen, dass Suchmaschinen die vollständige Reihe von Übersetzungen für diesen Inhalt verstehen.

6. Überprüfung der hreflang-Implementierung

Die head-Funktion gibt Link-Elemente zurück, die von der HeadContent-Komponente gerendert werden. Überprüfen Sie den gerenderten HTML-Code, um zu bestätigen, dass die Links im Dokumentkopf erscheinen.

<link rel="alternate" hreflang="en" href="/en/about" />
<link rel="alternate" hreflang="fr" href="/fr/about" />
<link rel="alternate" hreflang="de" href="/de/about" />
<link rel="alternate" hreflang="es" href="/es/about" />
<link rel="alternate" hreflang="x-default" href="/en/about" />

Bidirektionale Links zwischen Seiten stellen sicher, dass Suchmaschinen die Beziehung zwischen lokalisierten Versionen verstehen und es ihnen ermöglichen, jedem Benutzer die am besten geeignete Version anzuzeigen.