So übersetzt man Seiten-Metadaten in TanStack Start v1

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 ansehen. Eine spanische Seite mit einem englischen Titel in Suchergebnissen signalisiert schlechte Lokalisierungsqualität. Suchmaschinen können diese Diskrepanz als Ranking-Signal interpretieren und möglicherweise die Sichtbarkeit in sprachspezifischen Suchergebnissen verringern.

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

Lösung

Übersetzen Sie Seiten-Metadaten mit denselben Übersetzungsressourcen wie den Seiteninhalt. Definieren Sie eine head-Funktion in Ihrer Route-Konfiguration, 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 Übersetzungs-Workflow synchronisiert und werden automatisch aktualisiert, wenn sich das Gebietsschema ändert.

Schritte

1. Erstellen Sie eine Hilfsfunktion zum Formatieren 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 Utility, das Nachrichten mit createIntl aus 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);
}

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

2. Definieren Sie Übersetzungsschlüssel für Metadaten

Fügen Sie Titel- und Beschreibungsschlüssel zu Ihren Ü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 Ihre Komponenten-Übersetzungen und halten alle lokalisierten Inhalte an einem Ort.

3. Fügen Sie eine head-Funktion zu Ihrer Route hinzu

Verwenden Sie die head-Option in createFileRoute, um übersetzte Metadaten zurückzugeben. Greifen Sie auf die aktuelle Locale über Route-Parameter oder Loader-Daten zu und formatieren Sie dann Nachrichten mit Ihrer Hilfsfunktion.

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 Document-Head rendert.

4. Verwenden Sie Loader-Daten für dynamische Metadaten

Wenn Metadaten von abgerufenen Daten abhängen, greifen Sie 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 Sie dynamische Werte in übersetzte Metadaten-Vorlagen interpolieren können.