So verknüpfen Sie alternative Sprachversionen in TanStack Start v1

Verknüpfen Sie Sprachalternativen für Suchmaschinen

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 die Sprachversionen auf und verursacht Bereitstellungsprobleme: Ein französischsprachiger Nutzer sieht möglicherweise die englische Version in den Suchergebnissen höher eingestuft, obwohl eine französische Übersetzung existiert. Suchmaschinen benötigen explizite Metadaten, um die Beziehung zwischen Sprachvarianten zu verstehen und die entsprechende Version basierend auf den Sprachpräferenzen und dem Standort des Nutzers bereitzustellen.

Lösung

Fügen Sie hreflang Link-Elemente zum Dokument-Head 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 richtige Version für Nutzer bereitstellen können. Jede Seite listet alle ihre Sprachalternativen auf, einschließlich eines Verweises auf sich selbst, wodurch eine bidirektionale Beziehung entsteht, die Suchmaschinen verwenden, um die Übersetzungsstruktur zu verstehen. Diese Metadaten werden pro Route mithilfe des Head-Management-Systems des Frameworks hinzugefügt, das Zugriff auf die aktuellen Route-Parameter hat, die zum Erstellen von URLs für alle Sprachvarianten benötigt werden.

Schritte

1. Erstellen Sie eine Hilfsfunktion zum Erstellen von Sprachalternativ-URLs

Die buildLocation-Methode des Routers erstellt vollständige URLs aus Route-Parametern, die Sie verwenden, 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 von Ihrer Anwendung unterstützten Sprachen auflistet.

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

export const DEFAULT_LANGUAGE = "en";

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

Die head-Funktion erhält Kontext einschließlich matches, params und loaderData, was Zugriff auf den aktuellen Sprachparameter und die Router-Instanz bietet.

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 über die Sprache hinaus schließen 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 den vollständigen Satz von Übersetzungen für diesen Inhalt verstehen.

6. Überprüfen Sie die hreflang-Implementierung

Die head-Funktion gibt link-Elemente zurück, die von der HeadContent-Komponente gerendert werden. Inspizieren Sie das gerenderte HTML, um zu bestätigen, dass die Links im document head 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 bereitzustellen.