Wie man Seiten-Metadaten in TanStack Start v1 übersetzt

Problem

Seiten-Metadaten – Titel und Beschreibungen – erscheinen in Browser-Tabs, Lesezeichen, Suchergebnissen und Social-Media-Vorschauen. Wenn die Sprache der Metadaten nicht mit der Sprache des Seiteninhalts übereinstimmt, erleben Nutzer eine störende Inkonsistenz, bevor sie die Seite überhaupt betrachten. Eine spanische Seite mit einem englischen Titel in den Suchergebnissen signalisiert eine schlechte Lokalisierungsqualität. Suchmaschinen könnten diese Diskrepanz als Ranking-Signal interpretieren und möglicherweise die Sichtbarkeit in sprachspezifischen Suchergebnissen verringern.

Diese Unstimmigkeit beeinträchtigt das Nutzererlebnis bereits in der Entdeckungsphase. Nutzer, die in ihrer bevorzugten Sprache suchen, erwarten übereinstimmende Metadaten, und Inkonsistenz untergräbt das Vertrauen schon vor dem ersten Klick.

Lösung

Übersetzen Sie Seiten-Metadaten mit denselben Übersetzungsressourcen wie den Seiteninhalt. Definieren Sie eine head-Funktion in Ihrer Routenkonfiguration, die auf übersetzte Strings zugreift und lokalisierte Titel- und Beschreibungs-Metadaten zurückgibt. Dies gewährleistet Konsistenz zwischen dem, was in der Browser-Oberfläche, in Suchergebnissen und auf der gerenderten Seite erscheint.

Durch die Verwendung der Nachrichtenformatierung von react-intl innerhalb der head-Funktion bleiben Metadaten mit Ihrem Übersetzungsworkflow synchronisiert und werden automatisch aktualisiert, wenn sich die Sprache ändert.

Schritte

1. Erstellen Sie einen Helfer zur Formatierung von Nachrichten außerhalb von React-Komponenten

Die head-Funktion läuft außerhalb des React-Komponentenbaums, wo Hooks nicht verfügbar sind. Erstellen Sie ein Hilfsprogramm, das Nachrichten mit createIntl von react-intl formatiert.

import { createIntl, createIntlCache } from "react-intl";

const cache = createIntlCache();

export function formatMetadataMessage(
  locale: string,
  messages: Record<string, string>,
  id: string,
  values?: Record<string, string | number>,
): string {
  const intl = createIntl({ locale, messages }, cache);
  return intl.formatMessage({ id }, values);
}

Dieser Helfer erstellt bei Bedarf eine intl-Instanz zur Verwendung in Nicht-React-Kontexten wie der head-Funktion.

2. Definiere Metadaten-Übersetzungsschlüssel

Füge Titel- und Beschreibungsschlüssel zu deinen Übersetzungsdateien für jede Seite hinzu, die lokalisierte Metadaten benötigt.

export const enMessages = {
  "page.home.title": "Welcome to Our Site",
  "page.home.description": "Discover amazing content in your language",
  "page.about.title": "About Us",
  "page.about.description": "Learn more about our mission and team",
};

export const esMessages = {
  "page.home.title": "Bienvenido a Nuestro Sitio",
  "page.home.description": "Descubre contenido increíble en tu idioma",
  "page.about.title": "Acerca de Nosotros",
  "page.about.description": "Conoce más sobre nuestra misión y equipo",
};

Diese Schlüssel folgen dem gleichen Muster wie deine Komponenten-Übersetzungen und halten alle lokalisierten Inhalte an einem Ort.

3. Füge eine head-Funktion zu deiner Route hinzu

Verwende die head-Option in createFileRoute, um übersetzte Metadaten zurückzugeben. Greife auf das aktuelle Gebietsschema aus den Routenparametern oder Loader-Daten zu und formatiere dann Nachrichten mit deinem Helper.

import { createFileRoute } from "@tanstack/react-router";
import { formatMetadataMessage } from "../utils/formatMetadataMessage";
import { enMessages, esMessages } from "../i18n/messages";

const messagesByLocale = {
  en: enMessages,
  es: esMessages,
};

export const Route = createFileRoute("/$locale/about")({
  head: ({ params }) => {
    const locale = params.locale || "en";
    const messages = messagesByLocale[locale] || messagesByLocale.en;

    return {
      meta: [
        {
          title: formatMetadataMessage(locale, messages, "page.about.title"),
        },
        {
          name: "description",
          content: formatMetadataMessage(
            locale,
            messages,
            "page.about.description",
          ),
        },
      ],
    };
  },
  component: AboutPage,
});

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

Die head-Funktion wird während des Route-Matchings ausgeführt und gibt Metadaten-Objekte zurück, die TanStack Start in den Dokumentenkopf rendert.

4. Verwende Loader-Daten für dynamische Metadaten

Wenn Metadaten von abgerufenen Daten abhängen, greife in der head-Funktion auf loaderData zu, um dynamische Inhalte mit übersetzten Vorlagen zu kombinieren.

import { createFileRoute } from "@tanstack/react-router";
import { formatMetadataMessage } from "../utils/formatMetadataMessage";
import { enMessages, esMessages } from "../i18n/messages";

const messagesByLocale = {
  en: enMessages,
  es: esMessages,
};

export const Route = createFileRoute("/$locale/posts/$postId")({
  loader: async ({ params }) => {
    const post = await fetchPost(params.postId);
    return { post };
  },
  head: ({ params, loaderData }) => {
    const locale = params.locale || "en";
    const messages = messagesByLocale[locale] || messagesByLocale.en;
    const { post } = loaderData;

    return {
      meta: [
        {
          title: formatMetadataMessage(locale, messages, "page.post.title", {
            title: post.title,
          }),
        },
        {
          name: "description",
          content: post.excerpt,
        },
      ],
    };
  },
  component: PostPage,
});

function PostPage() {
  const { post } = Route.useLoaderData();
  return <article>{post.content}</article>;
}

Der Loader ruft Daten ab, bevor die head-Funktion ausgeführt wird, sodass du dynamische Werte in übersetzte Metadaten-Vorlagen einfügen kannst.