Autor:
    Aymeric PINEAU
    Erstellung:2025-03-25Letzte Aktualisierung:2026-08-25

    Übersetzen Sie Ihre Tanstack Start mit Solid.js Website mit Intlayer | Internationalisierung (i18n)

    Inhaltsverzeichnis

    Dieser Leitfaden zeigt, wie man Intlayer für eine nahtlose Internationalisierung in Tanstack Start Projekten mit Solid.js, lokalisierungsbewusstem Routing, TypeScript-Unterstützung und modernen Entwicklungspraktiken integriert.

    Warum Intlayer gegenüber Alternativen?

    Im Vergleich zu Hauptlösungen wie „react-i18next“ oder „i18next“ ist Intlayer eine Lösung, die über integrierte Optimierungen verfügt wie:

    Intlayer ist für die perfekte Zusammenarbeit mit TanStack Start und Solid optimiert, indem es mehrsprachiges Routing, Sitemap und alle Funktionen bietet, die für die Skalierung der Internationalisierung (i18n) erforderlich sind.

    Anstatt riesige JSON-Dateien in Ihre Seiten zu laden, laden Sie nur den erforderlichen Inhalt. Intlayer hilft Ihre Bundle- und Seitengröße um bis zu 50 % zu reduzieren.

    Durch die Festlegung des Inhaltsbereichs Ihrer Anwendung wird die Wartung für umfangreiche Anwendungen erleichtert. Sie können einen einzelnen Feature-Ordner duplizieren oder löschen, ohne die mentale Belastung durch die Überprüfung Ihrer gesamten Inhaltscodebasis auf sich nehmen zu müssen. Darüber hinaus ist Intlayer vollständig typisiert (fully typed), um die Genauigkeit Ihrer Inhalte sicherzustellen.

    Durch die gemeinsame Platzierung von Inhalten reduziert sich der von Large Language Models (LLMs) benötigte Kontext. Intlayer verfügt außerdem über eine Reihe von Tools, wie zum Beispiel eine CLI zum Testen auf fehlende Übersetzungen,LSP, MCP und agent skills, um die Entwicklererfahrung (DX) für KI-Agenten noch reibungsloser zu gestalten.

    Nutzen Sie die Automatisierung, um Ihre CI/CD-Pipeline mit dem LLM Ihrer Wahl auf Kosten Ihres KI-Anbieters zu übersetzen. Intlayer bietet außerdem einen Compiler zur Automatisierung der Inhaltsextraktion sowie eine Webplattform zur Unterstützung der Übersetzung im Hintergrund.

    Das Verbinden großer JSON-Dateien mit Komponenten kann zu Leistungs- und Reaktivitätsproblemen führen. Intlayer optimiert das Laden Ihrer Inhalte zur Erstellungszeit.

    Intlayer ist mehr als nur eine i18n-Lösung. Es bietet einen selbstgehosteten visuellen Editor und ein vollständiges CMS, um Ihnen zu helfen Verwalten Sie Ihre mehrsprachigen Inhalte in Echtzeit und gestalten Sie die Zusammenarbeit mit Übersetzern, Textern und anderen Teammitgliedern reibungslos. Inhalte können lokal und/oder remote gespeichert werden.

    Schritt-für-Schritt-Anleitung zur Einrichtung von Intlayer in einer Tanstack Start Anwendung

    www.youtube.com
    ide.intlayer.org
    intlayer-tanstack-start-solid.vercel.app

    Siehe Anwendungsvorlage auf GitHub.

    1. Projekt erstellen

      Beginnen Sie mit der Erstellung eines neuen TanStack Start Projekts, indem Sie dem Leitfaden Neues Projekt starten auf der TanStack Start Website folgen.

    2. Intlayer-Pakete installieren

      Installieren Sie die erforderlichen Pakete mit Ihrem bevorzugten Paketmanager:

      bash
      npx intlayer init --interactive
      Das Flag --interactive ist optional. Verwenden Sie intlayer-cli init, wenn Sie ein KI-Agent sind.
      Dieser Befehl erkennt Ihre Umgebung und installiert die erforderlichen Pakete. Zum Beispiel:
      bash
      npm install intlayer solid-intlayer
npm install vite-intlayer --save-dev

      • intlayer

        Das Kernpaket, das Internationalisierungswerkzeuge für Konfigurationsmanagement, Übersetzung, Inhaltsdeklaration, Transpilation und CLI-Befehle bereitstellt.

      • solid-intlayer Das Paket, das Intlayer in Solid-Anwendungen integriert. Es bietet Kontextanbieter und Hooks für die Solid-Internationalisierung.

      • vite-intlayer Enthält das Vite-Plugin zur Integration von Intlayer in den Vite-Bundler sowie Middleware zur Erkennung der bevorzugten Sprache des Benutzers, zur Verwaltung von Cookies und zur Handhabung von URL-Weiterleitungen.

    3. Konfiguration Ihres Projekts

      Erstellen Sie eine Konfigurationsdatei, um die Sprachen Ihrer Anwendung zu konfigurieren:

      intlayer.config.ts
      import type { IntlayerConfig } from "intlayer";

import { Locales } from "intlayer";

const config: IntlayerConfig = {
  internationalization: {
    defaultLocale: Locales.ENGLISH,
    locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
  },
};

export default config;
      Über diese Konfigurationsdatei können Sie lokalisierte URLs, Middleware-Weiterleitungen, Cookie-Namen, den Speicherort und die Erweiterung Ihrer Inhaltsdeklarationen einrichten, Intlayer-Protokolle in der Konsole deaktivieren und vieles mehr. Eine vollständige Liste der verfügbaren Parameter finden Sie in der Konfigurationsdokumentation.

    4. Intlayer in Ihre Vite-Konfiguration integrieren

      Fügen Sie das Intlayer-Plugin zu Ihrer Konfiguration hinzu:

      vite.config.ts
      import { intlayer } from "vite-intlayer";
import { defineConfig } from "vite";
import { devtools } from "@tanstack/devtools-vite";
import { tanstackStart } from "@tanstack/solid-start/plugin/vite";
import solidPlugin from "vite-plugin-solid";

export default defineConfig({
  plugins: [
    devtools(),
    tanstackStart({
      router: {
        routeFileIgnorePattern:
          ".content.(ts|tsx|js|mjs|cjs|jsx|json|jsonc|json5|md|mdx|yaml|yml)$",
      },
    }),
    solidPlugin({ ssr: true }),
    intlayer({
      proxy: {
        ignore: (req) => req.url?.startsWith("/api"),
      },
    }),
  ],
});
      Das Vite-Plugin intlayer() wird verwendet, um Intlayer in Vite zu integrieren. Es stellt die Erstellung von Inhaltsdeklarationsdateien sicher und überwacht diese im Entwicklungsmodus. Es definiert Intlayer-Umgebungsvariablen innerhalb der Vite-Anwendung. Darüber hinaus bietet es Aliase zur Leistungsoptimierung.

    5. Root-Layout erstellen

      Konfigurieren Sie Ihr Root-Layout für die Internationalisierung, indem Sie useParams verwenden, um das aktuelle Gebietsschema zu erkennen und die Attribute lang und dir für das html-Tag festzulegen.

      src/routes/__root.tsx
      import {
  HeadContent,
  Scripts,
  createRootRouteWithContext,
  getRouteApi,
} from "@tanstack/solid-router";
import { HydrationScript } from "solid-js/web";
import { Suspense, type ParentComponent } from "solid-js";
import { IntlayerProvider } from "solid-intlayer";
import { defaultLocale, getHTMLTextDir } from "intlayer";

const localeRoute = getRouteApi("/{-$locale}");

export const Route = createRootRouteWithContext()({
  shellComponent: RootComponent,
});

const RootComponent: ParentComponent = (props) => {
  const params = localeRoute.useParams();
  const locale = params()?.locale ?? defaultLocale;

  return (
    <html dir={getHTMLTextDir(locale)} lang={locale}>
      <head>
        <HydrationScript />
        <HeadContent />
      </head>
      <body>
        <IntlayerProvider locale={locale}>
          <Suspense>{props.children}</Suspense>
        </IntlayerProvider>
        <Scripts />
      </body>
    </html>
  );
};

    6. Gebietsschema-Layout erstellen

      Erstellen Sie ein Layout, das das Gebietskennungs-Präfix verarbeitet und Validierungen durchführt. Dieses Layout stellt sicher, dass nur gültige Gebietsschemata verarbeitet werden.

      Dieser Schritt ist optional, wenn Sie das Gebietskennungs-Präfix nicht auf Routenebene validieren müssen.
      src/routes/{-$locale}/route.tsx
      import { createFileRoute, Outlet, redirect } from "@tanstack/solid-router";
import { validatePrefix } from "intlayer";

export const Route = createFileRoute("/{-$locale}")({
  beforeLoad: ({ params }) => {
    const localeParam = params.locale;

    // Das Gebietskennungs-Präfix validieren
    const { isValid, localePrefix } = validatePrefix(localeParam);

    if (!isValid) {
      throw redirect({
        to: "/{-$locale}/404",
        params: { locale: localePrefix },
        replace: true,
      });
    }
  },
  component: Outlet,
});
      Hier ist {-$locale} ein dynamischer Routenparameter, der durch das aktuelle Gebietsschema ersetzt wird. Diese Notation macht den Slot optional und ermöglicht die Nutzung von Routing-Modi wie 'prefix-no-default' etc.

      Beachten Sie, dass dieser Slot Probleme verursachen kann, wenn Sie mehrere dynamische Segmente in der gleichen Route verwenden (z. B. /{-$locale}/anderer-pfad/$weitererDynamischerPfad/...). Für den Modus 'prefix-all' möchten Sie den Slot möglicherweise stattdessen auf $locale umstellen. Für den Modus 'no-prefix' oder 'search-params' können Sie den Slot ganz entfernen.

    7. Deklarieren Sie Ihren Inhalt

      Erstellen und verwalten Sie Ihre Inhaltsdeklarationen, um Übersetzungen zu speichern:

      src/contents/page.content.ts
      import type { Dictionary } from "intlayer";

import { t } from "intlayer";

const appContent = {
  content: {
    links: {
      about: t({
        en: "About",
        es: "Acerca de",
        fr: "À propos",
      }),
      home: t({
        en: "Home",
        es: "Inicio",
        fr: "Accueil",
      }),
    },
    meta: {
      title: t({
        en: "Welcome to Intlayer + TanStack Router",
        es: "Bienvenido a Intlayer + TanStack Router",
        fr: "Bienvenue à Intlayer + TanStack Router",
      }),
      description: t({
        en: "This is an example of using Intlayer with TanStack Router",
        es: "Este es un ejemplo de uso de Intlayer con TanStack Router",
        fr: "Ceci est un exemple d'utilisation d'Intlayer avec TanStack Router",
      }),
    },
  },
  key: "app",
} satisfies Dictionary;

export default appContent;
      Ihre Inhaltsdeklarationen können an beliebiger Stelle in Ihrer Anwendung definiert werden, solange sie im Verzeichnis contentDir (standardmäßig ./app) enthalten sind. Und der Dateierweiterung für Inhaltsdeklarationen (standardmäßig .content.{json,ts,tsx,js,jsx,mjs,cjs,md,mdx,yaml,yml}) entsprechen.
      Weitere Informationen finden Sie in der Dokumentation zur Inhaltsdeklaration.

    8. Lokalisierungsbewusste Komponenten und Hooks verwenden

      Erstellen Sie eine LocalizedLink-Komponente für lokalisierungsbewusste Navigation:

      src/components/LocalizedLink.tsx
      import { Link, type LinkProps } from "@tanstack/solid-router";
import { getPrefix } from "intlayer";
import { useLocale } from "solid-intlayer";
import type { JSX } from "solid-js";

export const LOCALE_ROUTE = "{-$locale}" as const;

export type RemoveLocaleParam<TVal> = TVal extends string
  ? RemoveLocaleFromString<TVal>
  : TVal;

export type To = RemoveLocaleParam<LinkProps["to"]>;

type CollapseDoubleSlashes<TString extends string> =
  TString extends `${infer THead}//${infer TTail}`
    ? CollapseDoubleSlashes<`${THead}/${TTail}`>
    : TString;

export type LocalizedLinkProps = Omit<LinkProps, "to"> & {
  to?: To;
} & JSX.AnchorHTMLAttributes<HTMLAnchorElement>;

type RemoveAll<
  TString extends string,
  TSub extends string,
> = TString extends `${infer THead}${TSub}${infer TTail}`
  ? RemoveAll<`${THead}${TTail}`, TSub>
  : TString;

type RemoveLocaleFromString<TString extends string> = CollapseDoubleSlashes<
  RemoveAll<TString, typeof LOCALE_ROUTE>
>;

export const LocalizedLink = (props: LocalizedLinkProps) => {
  const { locale } = useLocale();

  return (
    <Link
      {...props}
      params={{
        locale: getPrefix(locale()).localePrefix,
        ...(typeof props.params === "object" ? props.params : {}),
      }}
      to={`/${LOCALE_ROUTE}${props.to ?? ""}` as LinkProps["to"]}
    />
  );
};

      Diese Komponente hat zwei Ziele:

      • Entfernen des unnötigen {-$locale}-Präfixes aus der URL.
      • Einfügen des Gebietsschema-Parameters in die URL, um sicherzustellen, dass der Benutzer direkt auf die lokalisierte Route weitergeleitet wird.

      Anschließend können wir einen useLocalizedNavigate-Hook für die programmgesteuerte Navigation erstellen:

      src/hooks/useLocalizedNavigate.tsx
      import { useNavigate } from "@tanstack/solid-router";
import { getLocalizedUrl } from "intlayer";
import { useLocale } from "solid-intlayer";

export const useLocalizedNavigate = () => {
  const navigate = useNavigate();
  const { locale } = useLocale();

  const localizedNavigate = (to: string) => {
    const localizedTo = getLocalizedUrl(to, locale());
    return navigate({ to: localizedTo });
  };

  return localizedNavigate;
};

    9. Intlayer in Ihren Seiten nutzen

      Verwenden Sie standardmäßig useIntlayer: Es ist der empfohlene Weg, Inhalte innerhalb von Komponenten zu lesen, und der Compiler löst den Aufruf auf die gerenderte Locale auf. Greifen Sie nur außerhalb des Solid-Baums zu getIntlayer / getIntlayerAsync: im head von Routen, in Loadern und Server Functions.

      Greifen Sie in Ihrer gesamten Anwendung auf Ihre Inhaltswörterbücher zu:

      Lokalisierte Startseite

      src/routes/{-$locale}/index.tsx
      import { createFileRoute } from "@tanstack/solid-router";
import { useIntlayer } from "solid-intlayer";
import { LocalizedLink } from "@/components/LocalizedLink";

export const Route = createFileRoute("/{-$locale}/")({
  component: RouteComponent,
});

function RouteComponent() {
  const content = useIntlayer("index-page");

  return (
    <main>
      <h1>{content.heroTitle}</h1>
      <p>{content.heroDesc}</p>
      <div>
        <LocalizedLink to="/">{content.navHome}</LocalizedLink>
        <LocalizedLink to="/about">{content.navAbout}</LocalizedLink>
      </div>
    </main>
  );
}
      html
      <img src="{content.image.src.value}" alt="{content.image.value}" />
<img src="{content.image.src.toString()}" alt="{content.image.toString()}" />
<img src="{String(content.image.src)}" alt="{String(content.image)}" />

      In Solid gibt useIntlayer reaktiven Inhalt zurück (z.B. content). Sie können direkt auf seine Eigenschaften zugreifen.

      Um mehr über den useIntlayer-Hook zu erfahren, lesen Sie die Dokumentation.

    10. Eine Sprachumschalter-Komponente erstellen

      Erstellen Sie eine Komponente, mit der Benutzer die Sprache ändern können:

      src/components/LocaleSwitcher.tsx
      import { useLocation } from "@tanstack/solid-router";
import { getLocaleName, getPathWithoutLocale, getPrefix } from "intlayer";
import { For } from "solid-js";
import { useIntlayer, useLocale } from "solid-intlayer";
import { LocalizedLink, type To } from "./LocalizedLink";

export const LocaleSwitcher = () => {
  const content = useIntlayer("locale-switcher");
  const location = useLocation();

  const { availableLocales, locale, setLocale } = useLocale();

  const pathWithoutLocale = () => getPathWithoutLocale(location().pathname);

  return (
    <div class="flex flex-row gap-2">
      <For each={availableLocales}>
        {(localeEl) => (
          <LocalizedLink
            aria-current={localeEl === locale() ? "page" : undefined}
            onClick={() => setLocale(localeEl)}
            params={{ locale: getPrefix(localeEl).localePrefix }}
            to={pathWithoutLocale() as To}
          >
            {getLocaleName(localeEl)}
          </LocalizedLink>
        )}
      </For>
    </div>
  );
};

export default LocaleSwitcher;

      In Solid ist locale aus useLocale ein Signal-Accessor. Verwenden Sie locale() (mit Klammern), um den aktuellen Wert reaktiv zu lesen.

      Um mehr über den useLocale-Hook zu erfahren, lesen Sie die Dokumentation.

    11. Verwaltung von HTML-Attributen

      Wie in Schritt 5 zu sehen ist, können Sie die Attribute lang und dir des html-Tags mit useParams in Ihrer Root-Komponente verwalten. Dies stellt sicher, dass die korrekten Attribute auf dem Server und dem Client festgelegt werden.

      src/routes/__root.tsx
      const RootComponent: ParentComponent = (props) => {
  const params = localeRoute.useParams();
  const locale = params()?.locale ?? defaultLocale;

  return (
    <html dir={getHTMLTextDir(locale)} lang={locale}>
      {/* ... */}
    </html>
  );
};

    12. Middleware hinzufügen

      Sie können auch den intlayerProxy verwenden, um serverseitiges Routing zu Ihrer Anwendung hinzuzufügen. Dieses Plugin erkennt automatisch das aktuelle Gebietsschema basierend auf der URL und setzt das entsprechende Sprach-Cookie. Wenn kein Gebietsschema angegeben ist, bestimmt das Plugin das am besten geeignete Gebietsschema basierend auf den Spracheinstellungen des Browsers des Benutzers. Wenn kein Gebietsschema erkannt wird, leitet es auf das Standardgebietsschema weiter.

      Beachten Sie, dass Sie für die Verwendung des intlayerProxy in der Produktion das Paket vite-intlayer von devDependencies zu dependencies verschieben müssen.
      Seit Intlayer v9 ist intlayerProxy() direkt in das intlayer() Plugin gebündelt und standardmäßig über die routing.enableProxy Option aktiviert (true standardmäßig). Die separate Registrierung wie unten gezeigt ist nun optional; sie wird für Rückwärtskompatibilität und für Setups beibehalten, die die Plugin-Reihenfolge kontrollieren müssen. Setzen Sie routing.enableProxy: false, um sich abzumelden. Siehe die v9 Release Notes.
      vite.config.ts
      import { tanstackStart } from "@tanstack/solid-start/plugin/vite";
import solid from "vite-plugin-solid";
import { nitro } from "nitro/vite";
import { defineConfig } from "vite";
import { intlayer } from "vite-intlayer";

export default defineConfig({
  plugins: [
    nitro(),
    intlayer({
      proxy: {
        ignore: (req) => req.url?.startsWith("/api"),
      },
    }),
    tanstackStart({
      router: {
        routeFileIgnorePattern:
          ".content.(ts|tsx|js|mjs|cjs|jsx|json|jsonc|json5|md|mdx|yaml|yml)$",
      },
    }),
    solid(),
  ],
});

    13. Internationalisieren Sie Ihre Metadaten

      getIntlayer löst synchron gegen das zusammengeführte Dictionary auf, also gegen jenes, das alle deklarierten Locales enthält. head bleibt synchron und es wird nichts erwartet, aber das gesamte mehrsprachige Dictionary landet im Route-Chunk, der an den Browser geht.

      src/routes/{-$locale}/index.tsx
      import { createFileRoute } from "@tanstack/solid-router";
import {
  defaultLocale,
  getIntlayer,
  getLocalizedUrl,
  localeMap,
} from "intlayer";

export const Route = createFileRoute("/{-$locale}/")({
  component: RouteComponent,
  head: ({ params }) => {
    const { locale = defaultLocale } = params;
    const path = "/"; // The path for this route

    const metaContent = getIntlayer("app", locale);

    return {
      links: [
        // Canonical link: Points to the current localized page
        { rel: "canonical", href: getLocalizedUrl(path, locale) },

        // Hreflang: Tell Google about all localized versions
        ...localeMap(({ locale: mapLocale }) => ({
          rel: "alternate",
          hrefLang: mapLocale,
          href: getLocalizedUrl(path, mapLocale),
        })),

        // x-default: For users in unmatched languages
        // Define the default fallback locale (usually your primary language)
        {
          rel: "alternate",
          hrefLang: "x-default",
          href: getLocalizedUrl(path, defaultLocale),
        },
      ],
      meta: [
        { title: metaContent.title },
        { name: "description", content: metaContent.meta.description },
      ],
    };
  },
});

      Am besten für kleine Metadaten-Dictionaries, wenige Locales oder beim Prototyping.

      getIntlayerAsync (verfügbar ab v9.4) verhält sich wie getIntlayer, doch das Build-Plugin verweist es auf den Locale-Chunk in .intlayer/dynamic_dictionaries/ statt auf das zusammengeführte Dictionary. Eine Seite liefert damit nur die Locale aus, die sie rendert. Da dieser Chunk bei Bedarf geladen wird, wird head zu async:

      src/routes/{-$locale}/index.tsx
      import { createFileRoute } from "@tanstack/solid-router";
import {
  defaultLocale,
  getIntlayerAsync,
  getLocalizedUrl,
  localeMap,
} from "intlayer";

export const Route = createFileRoute("/{-$locale}/")({
  component: RouteComponent,
  head: async ({ params }) => {
    const { locale = defaultLocale } = params;
    const path = "/"; // The path for this route

    const metaContent = await getIntlayerAsync("app", locale);

    return {
      links: [
        // Canonical link: Points to the current localized page
        { rel: "canonical", href: getLocalizedUrl(path, locale) },

        // Hreflang: Tell Google about all localized versions
        ...localeMap(({ locale: mapLocale }) => ({
          rel: "alternate",
          hrefLang: mapLocale,
          href: getLocalizedUrl(path, mapLocale),
        })),

        // x-default: For users in unmatched languages
        // Define the default fallback locale (usually your primary language)
        {
          rel: "alternate",
          hrefLang: "x-default",
          href: getLocalizedUrl(path, defaultLocale),
        },
      ],
      meta: [
        { title: metaContent.title },
        { name: "description", content: metaContent.meta.description },
      ],
    };
  },
});
      Liest ein head mehrere Dictionaries, lösen Sie sie mit Promise.all auf; jedes getIntlayerAsync einzeln zu awaiten verkettet die Anfragen, statt sie parallel auszuführen.

      Der Kompromiss: Der dynamische Import wird während der Ausführung von head aufgelöst, also auf dem kritischen Pfad des Dokument-Renderings. Auf einer kalten Route verzögert das den head um einige Millisekunden und kann den LCP leicht verschlechtern.

      Lösen Sie das Dictionary stattdessen im loader der Route auf und lesen Sie es in head aus loaderData zurück. Die Loader der gematchten Routen laufen parallel, und staleTime: Infinity teilt TanStack Router mit, dass das Ergebnis nie veraltet, der Locale-Chunk wird also einmal aufgelöst und danach aus dem Router-Cache bedient, während head synchron bleibt.

      src/routes/{-$locale}/index.tsx
      import { createFileRoute } from "@tanstack/solid-router";
import {
  defaultLocale,
  getIntlayerAsync,
  getLocalizedUrl,
  localeMap,
} from "intlayer";

export const Route = createFileRoute("/{-$locale}/")({
  component: RouteComponent,
  // Resolved in parallel with the other matched routes, off the head critical path
  loader: async ({ params }) => {
    const { locale = defaultLocale } = params;

    return { metaContent: await getIntlayerAsync("app", locale) };
  },
  // The dictionary never changes for a given locale: resolve the chunk once
  staleTime: Infinity,
  head: ({ params, loaderData }) => {
    const { locale = defaultLocale } = params;
    const path = "/"; // The path for this route

    return {
      links: [
        // Canonical link: Points to the current localized page
        { rel: "canonical", href: getLocalizedUrl(path, locale) },

        // Hreflang: Tell Google about all localized versions
        ...localeMap(({ locale: mapLocale }) => ({
          rel: "alternate",
          hrefLang: mapLocale,
          href: getLocalizedUrl(path, mapLocale),
        })),

        // x-default: For users in unmatched languages
        // Define the default fallback locale (usually your primary language)
        {
          rel: "alternate",
          hrefLang: "x-default",
          href: getLocalizedUrl(path, defaultLocale),
        },
      ],
      meta: [
        { title: loaderData?.metaContent.title },
        {
          name: "description",
          content: loaderData?.metaContent.meta.description,
        },
      ],
    };
  },
});
      head kann aufgerufen werden, bevor der Loader fertig ist; loaderData ist deshalb als möglicherweise undefined typisiert. Behalten Sie die Optional-Chaining-Aufrufe bei oder geben Sie einen Fallback-Titel zurück.

      Sie behalten den Locale-Chunk, ohne seine Kosten auf dem kritischen Pfad des head zu bezahlen. Der Preis ist die Developer Experience: Der Inhalt muss explizit vom Loader über loaderData an den head durchgereicht werden.

      Welche Auflösung soll ich wählen?

      Statische Auflösung Dynamische Auflösung Gecachte dynamische Auflösung
      API getIntlayer getIntlayerAsync (v9.4+) getIntlayerAsync im loader (v9.4+)
      head-Signatur synchron async synchron, liest loaderData
      Ausgelieferte Locales alle deklarierten Locales nur die angeforderte Locale nur die angeforderte Locale
      Client-Navigationen nichts aufzulösen bei jedem Match erneut ausgeführt aus dem Router-Cache bedient
      Developer Experience am einfachsten ein await Inhalt über loaderData durchgereicht

    14. Gebietsschema in Ihren Server-Aktionen abrufen

      Möglicherweise möchten Sie auf das aktuelle Gebietsschema innerhalb Ihrer Server-Aktionen oder API-Endpunkte zugreifen. Dies können Sie mit dem Helfer getLocale von intlayer tun.

      Hier ist ein Beispiel mit den Server-Funktionen von TanStack Start:

      src/routes/{-$locale}/index.tsx
      import { createServerFn } from "@tanstack/solid-start";
import {
  getRequestHeader,
  getRequestHeaders,
} from "@tanstack/solid-start/server";
import { getCookie, getIntlayer, getLocale } from "intlayer";

export const getLocaleServer = createServerFn().handler(async () => {
  const locale = await getLocale({
    // Das Cookie aus der Anfrage abrufen (Standard: 'INTLAYER_LOCALE')
    getCookie: (name) => {
      const cookieString = getRequestHeader("cookie");

      return getCookie(name, cookieString);
    },
    // Den Header aus der Anfrage abrufen (Standard: 'x-intlayer-locale')
    // Fallback-Verwendung der Accept-Language-Aushandlung
    getHeader: (name) => getRequestHeader(name),
  });

  // Einige Inhalte mit getIntlayer() abrufen
  const content = getIntlayer("app", locale);

  return { locale, content };
});

    15. Nicht gefundene Seiten verwalten

      Wenn ein Benutzer eine nicht existierende Seite besucht, können Sie eine benutzerdefinierte 404-Seite anzeigen, und das Sprachpräfix kann beeinflussen, wie die 404-Seite ausgelöst wird.

      Verständnis der 404-Verarbeitung von TanStack Router mit Gebietskennungs-Präfixen

      In TanStack Router erfordert die Handhabung von 404-Seiten mit lokalisierten Routen einen mehrschichtigen Ansatz:

      1. Dedizierte 404-Route: Eine spezifische Route zur Anzeige der 404-UI.
      2. Validierung auf Routenebene: Validiert Gebietskennungs-Präfixe und leitet ungültige an 404 weiter.
      3. Catch-all-Route: Erfasst alle nicht passenden Pfade innerhalb des Gebietskennungssegments.
      src/routes/{-$locale}/404.tsx
      import { createFileRoute } from "@tanstack/solid-router";

// Dies erstellt eine dedizierte /[locale]/404-Route
// Sie wird sowohl als direkte Route verwendet als auch als Komponente in anderen Dateien importiert
export const Route = createFileRoute("/{-$locale}/404")({
  component: NotFoundComponent,
});

// Separat exportiert, damit sie in notFoundComponent und Catch-all-Routen wiederverwendet werden kann
export function NotFoundComponent() {
  return (
    <div>
      <h1>404</h1>
    </div>
  );
}
      src/routes/{-$locale}/route.tsx
      import { createFileRoute, Outlet, redirect } from "@tanstack/solid-router";
import { validatePrefix } from "intlayer";
import { NotFoundComponent } from "./404";

export const Route = createFileRoute("/{-$locale}")({
  // beforeLoad wird ausgeführt, bevor die Route gerendert wird (sowohl auf dem Server als auch auf dem Client)
  // Es ist der ideale Ort, um das Gebietskennungs-Präfix zu validieren
  beforeLoad: ({ params }) => {
    const localeParam = params.locale;

    // validatePrefix prüft, ob das Gebietsschema gemäß Ihrer Intlayer-Konfiguration gültig ist
    const { isValid, localePrefix } = validatePrefix(localeParam);

    if (!isValid) {
      // Ungültiges Sprachpräfix - Weiterleitung zur 404-Seite mit einem gültigen Sprachpräfix
      throw redirect({
        to: "/{-$locale}/404",
        params: { locale: localePrefix },
      });
    }
  },
  component: Outlet,
  // notFoundComponent wird aufgerufen, wenn eine untergeordnete Route nicht existiert
  // z. B. /en/nicht-existente-seite löst dies innerhalb des /en-Layouts aus
  notFoundComponent: NotFoundComponent,
});
      src/routes/{-$locale}/$.tsx
      import { createFileRoute } from "@tanstack/solid-router";

import { NotFoundComponent } from "./404";

// Die $-Route (Splat/Catch-all) passt auf jeden Pfad, der nicht auf andere Routen passt
// z. B. /en/ein/tief/verschachtelter/ungueltiger/pfad
// Dies stellt sicher, dass ALLE nicht passenden Pfade innerhalb eines Gebietsschemas die 404-Seite zeigen
// Ohne dies könnten nicht passende tiefe Pfade eine leere Seite oder einen Fehler anzeigen
export const Route = createFileRoute("/{-$locale}/$")({
  component: NotFoundComponent,
});

    16. Den Inhalt Ihrer Komponenten extrahieren

      Optional

      Wenn Sie eine bestehende Codebasis haben, kann die Transformation von Tausenden von Dateien zeitaufwendig sein.

      Um diesen Prozess zu erleichtern, bietet Intlayer einen Compiler / Extractor an, um Ihre Komponenten zu transformieren und den Inhalt zu extrahieren.

      Um es einzurichten, können Sie einen compiler-Abschnitt in Ihrer intlayer.config.ts-Datei hinzufügen:

      intlayer.config.ts
      import { type IntlayerConfig } from "intlayer";

const config: IntlayerConfig = {
  // ... Rest Ihrer Konfiguration
  compiler: {
    /**
     * Gibt an, ob der Compiler aktiviert sein soll.
     */
    enabled: true,

    /**
     * Definiert den Pfad der Ausgabedateien
     */
    output: ({ fileName, extension }) => `./${fileName}${extension}`,

    /**
     * Gibt an, ob die Komponenten nach der Transformation gespeichert werden sollen.
     *
     * - Wenn `true`, schreibt der Compiler die Komponentendatei auf die Festplatte um. Die Transformation wird also permanent sein, und der Compiler überspringt die Transformation für den nächsten Prozess. Auf diese Weise kann der Compiler die Anwendung transformieren und anschließend entfernt werden.
     *
     * - Wenn `false`, injiziert der Compiler den Funktionsaufruf `useIntlayer()` nur in den Code der Build-Ausgabe und lässt die Basis-Codebasis intakt. Die Transformation erfolgt nur im Speicher.
     */
    saveComponents: false,

    /**
     * Wörterbuch-Schlüsselpräfix
     */
    dictionaryKeyPrefix: "",
  },
};

export default config;

      Führen Sie den Extractor aus, um Ihre Komponenten zu transformieren und den Inhalt zu extrahieren.

      bash
      npx intlayer extract
      Since v9, the intlayerCompiler is included in the intlayer plugin. So you don't need to add it manually.

      Aktualisieren Sie Ihre vite.config.ts, um das intlayerCompiler-Plugin einzubinden:

      vite.config.ts
      import { intlayer, intlayerCompiler } from "vite-intlayer";
import { defineConfig } from "vite";
import { devtools } from "@tanstack/devtools-vite";
import { tanstackStart } from "@tanstack/solid-start/plugin/vite";
import solidPlugin from "vite-plugin-solid";

export default defineConfig({
  plugins: [
    devtools(),
    tanstackStart({
      router: {
        routeFileIgnorePattern:
          ".content.(ts|tsx|js|mjs|cjs|jsx|json|jsonc|json5|md|mdx|yaml|yml)$",
      },
    }),
    solidPlugin({ ssr: true }),
    intlayer(),
    intlayerCompiler(), // Adds the compiler plugin
  ],
});
      bash
      npm run build # Oder npm run dev

    17. Sitemap generieren

      Intlayer wird mit einem integrierten Sitemap-Generator geliefert, mit dem Sie ganz einfach eine Sitemap für Ihre Anwendung erstellen können. Er berücksichtigt lokalisierte Routen und fügt die erforderlichen Metadaten für Suchmaschinen hinzu.

      Die von Intlayer generierte Sitemap unterstützt den xhtml:link-Namespace (Hreflang XML-Erweiterungen). Im Gegensatz zu Standard-Sitemap-Generatoren, die nur rohe URLs auflisten, erstellt Intlayer automatisch die erforderlichen bidirektionalen Links zwischen allen Sprachversionen einer Seite (z. B. /about, /about?lang=fr und /about?lang=es). Dies stellt sicher, dass Suchmaschinen die richtige Sprachversion korrekt indexieren und der richtigen Zielgruppe bereitstellen.

      Um ihn zu verwenden, müssen Sie zuerst Ihre vite.config.ts konfigurieren, um das Vorrendern für Ihre lokalisierten Routen zu aktivieren und die standardmäßige TanStack Start Sitemap-Generierung zu deaktivieren.

      vite.config.ts
      import { localeMap, localeFlatMap } from "intlayer";
// ... andere Imports

export const pathList = ["", "/about", "/404"];

const localizedPages = localeFlatMap(({ urlPrefix }) =>
  pathList.map((path) => ({
    path: `${urlPrefix}${path}`,
    prerender: {
      enabled: true,
    },
  }))
);

export default defineConfig({
  plugins: [
    // ... andere Plugins
    tanstackStart({
      // ... andere Konfigurationen
      sitemap: {
        enabled: false,
      },
      prerender: {
        enabled: true,
        crawlLinks: false,
        concurrency: 10,
      },
      pages: localizedPages,
    }),
  ],
});

      Erstellen Sie dann eine Route src/routes/sitemap[.]xml.ts, die die Funktion generateSitemap verwendet:

      src/routes/sitemap[.]xml.ts
      import { createFileRoute } from "@tanstack/solid-router";
import { generateSitemap } from "intlayer";

const SITE_URL = "http://localhost:3000";

export const Route = createFileRoute("/sitemap.xml")({
  server: {
    handlers: {
      GET: async () => {
        const sitemap = generateSitemap(
          [
            { path: "/", changefreq: "daily", priority: 1.0 },
            { path: "/about", changefreq: "monthly", priority: 0.8 },
          ],
          { siteUrl: SITE_URL }
        );

        return new Response(sitemap, {
          headers: { "Content-Type": "application/xml" },
        });
      },
    },
  },
});

    18. TypeScript konfigurieren

      Intlayer verwendet Modul-Augmentation, um die Vorteile von TypeScript zu nutzen und Ihre Codebasis robuster zu machen.

      Stellen Sie sicher, dass Ihre TypeScript-Konfiguration die automatisch generierten Typen enthält:

      tsconfig.json
      {
  // ... Ihre bestehenden Konfigurationen
  include: [
    // ... Ihre bestehenden Includes
    ".intlayer/**/*.ts", // Die automatisch generierten Typen einbinden
  ],
}

    Git-Konfiguration

    Es wird empfohlen, die von Intlayer generierten Dateien zu ignorieren. Dies ermöglicht es Ihnen, zu vermeiden, sie in Ihr Git-Repository zu committen.

    Dazu können Sie die folgenden Anweisungen zu Ihrer .gitignore-Datei hinzufügen:

    .gitignore
    # Von Intlayer generierte Dateien ignorieren
.intlayer

    VS Code Erweiterung

    Um Ihre Entwicklungserfahrung mit Intlayer zu verbessern, können Sie die offizielle Intlayer VS Code Erweiterung installieren.

    Vom VS Code Marketplace installieren

    Diese Erweiterung bietet:

    • Autovervollständigung für Übersetzungsschlüssel.
    • Echtzeit-Fehlererkennung für fehlende Übersetzungen.
    • Inline-Vorschauen von übersetzten Inhalten.
    • Schnellaktionen, um Übersetzungen einfach zu erstellen und zu aktualisieren.

    Weitere Details zur Verwendung der Erweiterung finden Sie in der Dokumentation zur Intlayer VS Code Erweiterung.

    Weiter gehen

    Um weiter zu gehen, können Sie den visuellen Editor implementieren oder Ihre Inhalte mit dem CMS extern verwalten.

    Dokumentationsreferenzen

    Tanstack StartAstro