Übersetzen Sie Ihre Tanstack Start-Website mit Intlayer | Internationalisierung (i18n)

Inhaltsverzeichnis

Diese Anleitung zeigt, wie Sie Intlayer für eine nahtlose Internationalisierung in Tanstack Start-Projekten mit lokalisierungsbewusstem Routing, TypeScript-Unterstützung und modernen Entwicklungspraktiken integrieren.

Warum Intlayer gegenüber Alternativen?

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

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

Siehe Anwendungsvorlage auf GitHub.

1. 1

   Projekt erstellen

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

2. 2

   Intlayer-Pakete installieren

   Installieren Sie die erforderlichen Pakete mit Ihrem bevorzugten Paketmanager:

   bash

   Inhalt kopieren

   Code kopieren

   Kopieren Sie den Code in die Zwischenablage

   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

   Inhalt kopieren

   Code kopieren

   Kopieren Sie den Code in die Zwischenablage

   npm install intlayer react-intlayer
   npm install vite-intlayer --save-dev
   

   • intlayer

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

   • react-intlayer Das Paket, das Intlayer in die React-Anwendung integriert. Es bietet Kontextanbieter und Hooks für die Internationalisierung in React.

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

3. 3

   Konfiguration Ihres Projekts

   Architektur

   In dieser Architektur sind alle lokalisierten Routen unter dem Routensegment {-$locale} verschachtelt. Dieser Ansatz stellt sicher, dass jede Sprache eine dedizierte URL hat, und ermöglicht gleichzeitig ein automatisches Locale-Präfix, Validierung und SEO-Optimierung.

   bash

   Inhalt kopieren

   Code kopieren

   Kopieren Sie den Code in die Zwischenablage

   .
   ├── src
   │   ├── components
   │   │   ├── Header.tsx
   │   │   ├── locale-switcher.content.ts
   │   │   ├── locale-switcher.tsx
   │   │   └── localized-link.tsx
   │   ├── hooks
   │   │   ├── useI18nHTMLAttributes.tsx
   │   │   └── useLocalizedNavigate.ts
   │   ├── routes
   │   │   ├── {-$locale}
   │   │   │   ├── 404.content.ts
   │   │   │   ├── 404.tsx
   │   │   │   ├── about.content.ts
   │   │   │   ├── about.tsx
   │   │   │   ├── index.content.tsx
   │   │   │   ├── index.tsx
   │   │   │   └── route.tsx             # Locale layout & prefix validation
   │   │   ├── __root.tsx                # Root route with IntlayerProvider
   │   │   └── sitemap[.]xml.ts
   │   ├── router.tsx
   │   └── styles.css
   ├── intlayer.config.ts
   ├── package.json
   ├── tsconfig.json
   └── vite.config.ts
   

   Konfiguration

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

   intlayer.config.ts

   Inhalt kopieren

   Code kopieren

   Kopieren Sie den Code in die Zwischenablage

   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 festlegen, Intlayer-Protokolle in der Konsole deaktivieren und vieles mehr. Eine vollständige Liste der verfügbaren Parameter finden Sie in der Konfigurationsdokumentation.

4. 4

   Intlayer in Ihre Vite-Konfiguration integrieren

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

   vite.config.ts

   Inhalt kopieren

   Code kopieren

   Kopieren Sie den Code in die Zwischenablage

   import { tanstackStart } from "@tanstack/react-start/plugin/vite";
   import viteReact from "@vitejs/plugin-react";
   import { nitro } from "nitro/vite";
   import { defineConfig } from "vite";
   import { intlayer } from "vite-intlayer";
   
   const config = 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)$",
         },
       }),
       viteReact(),
     ],
   });
   
   export default config;
   

   Das intlayer() Vite-Plugin wird verwendet, um Intlayer mit 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. 5

   Root-Layout erstellen

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

   src/routes/__root.tsx

   Inhalt kopieren

   Code kopieren

   Kopieren Sie den Code in die Zwischenablage

   import {
     createRootRouteWithContext,
     getRouteApi,
     HeadContent,
     Scripts,
   } from "@tanstack/react-router";
   import { defaultLocale, getHTMLTextDir } from "intlayer";
   import { type ReactNode } from "react";
   import { IntlayerProvider } from "react-intlayer";
   
   const localeRoute = getRouteApi("/{-$locale}");
   
   export const Route = createRootRouteWithContext<{}>()({
     head: () => ({
       meta: [
         {
           charSet: "utf-8",
         },
         {
           content: "width=device-width, initial-scale=1",
           name: "viewport",
         },
         {
           title: "TanStack Start Starter",
         },
       ],
     }),
   
     shellComponent: RootDocument,
   });
   
   function RootDocument({ children }: { children: ReactNode }) {
     const params = localeRoute.useParams();
     const locale = params?.locale ?? defaultLocale;
   
     return (
       <html dir={getHTMLTextDir(locale)} lang={locale}>
         <head>
           <HeadContent />
         </head>
         <body>
           <IntlayerProvider locale={locale}>{children}</IntlayerProvider>
           <Scripts />
         </body>
       </html>
     );
   }
   

6. 6

   Locale-Layout erstellen

   Erstellen Sie ein Layout, das das Locale-Präfix verarbeitet und eine Validierung durchführt.

   src/routes/{-$locale}/route.tsx

   Inhalt kopieren

   Code kopieren

   Kopieren Sie den Code in die Zwischenablage

   import { createFileRoute, Outlet, redirect } from "@tanstack/react-router";
   import { validatePrefix } from "intlayer";
   
   export const Route = createFileRoute("/{-$locale}")({
     beforeLoad: ({ params }) => {
       const localeParam = params.locale;
   
       // Locale-Präfix validieren
       const { isValid, localePrefix } = validatePrefix(localeParam);
   
       if (!isValid) {
         throw redirect({
           to: "/{-$locale}/404",
           params: { locale: localePrefix },
         });
       }
     },
     component: Outlet,
   });
   

   Hier ist {-$locale} ein dynamischer Routenparameter, der durch die aktuelle Locale ersetzt wird. Diese Notation macht den Platzhalter optional, sodass er mit Routing-Modi wie 'prefix-no-default' usw. funktioniert.

   Beachten Sie, dass dieser Platzhalter Probleme verursachen kann, wenn Sie mehrere dynamische Segmente in derselben Route verwenden (z. B. /{-$locale}/anderer-pfad/$einWeitererDynamischerPfad/...). Für den Modus 'prefix-all' sollten Sie stattdessen den Platzhalter $locale verwenden. Für den Modus 'no-prefix' oder 'search-params' können Sie den Platzhalter ganz entfernen.

7. 7

   Inhalte deklarieren

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

   src/contents/page.content.ts

   Inhalt kopieren

   Code kopieren

   Kopieren Sie den Code in die Zwischenablage

   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 überall in Ihrer Anwendung definiert werden, solange sie im Verzeichnis contentDir (standardmäßig ./app) enthalten sind. Und sie müssen der Dateierweiterung für Inhaltsdeklarationen entsprechen (standardmäßig .content.{json,ts,tsx,js,jsx,mjs,cjs,md,mdx,yaml,yml}).

   Weitere Einzelheiten finden Sie in der Dokumentation zur Inhaltsdeklaration.

8. 7

   Lokalisierungsbewusste Komponenten und Hooks erstellen

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

   src/components/localized-link.tsx

   Inhalt kopieren

   Code kopieren

   Kopieren Sie den Code in die Zwischenablage

   import type { FC } from "react";
   
   import { Link, type LinkComponentProps } from "@tanstack/react-router";
   import { useLocale } from "react-intlayer";
   import { getPrefix } from "intlayer";
   
   export const LOCALE_ROUTE = "{-$locale}" as const;
   
   export type To = StripLocalePrefix<LinkComponentProps["to"]>;
   
   export type StripLocalePrefix<T extends string | undefined> = T extends
     `/${typeof LOCALE_ROUTE}/` | `/${typeof LOCALE_ROUTE}`
     ? "/"
     : T extends `/${typeof LOCALE_ROUTE}/${infer Rest}`
       ? `/${Rest}`
       : T;
   
   type LocalizedLinkProps = {
     to?: To;
   } & Omit<LinkComponentProps, "to">;
   
   export const LocalizedLink: FC<LocalizedLinkProps> = (props) => {
     const { locale } = useLocale();
     const { localePrefix } = getPrefix(locale);
   
     return (
       <Link
         {...props}
         params={{
           locale: localePrefix,
           ...(typeof props?.params === "object" ? props?.params : {}),
         }}
         to={`/${LOCALE_ROUTE}${props.to}` as LinkComponentProps["to"]}
       />
     );
   };
   

   Diese Komponente verfolgt zwei Ziele:

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

   Dann können wir einen useLocalizedNavigate-Hook für die programmatische Navigation erstellen:

   src/hooks/useLocalizedNavigate.tsx

   Inhalt kopieren

   Code kopieren

   Kopieren Sie den Code in die Zwischenablage

   import { useNavigate } from "@tanstack/react-router";
   import { getPrefix } from "intlayer";
   import { useLocale } from "react-intlayer";
   import type { StripLocalePrefix } from "@/components/localized-link";
   import type { FileRouteTypes } from "@/routeTree.gen";
   
   type NavigateFn = ReturnType<typeof useNavigate>;
   type BaseNavigateOptions = Parameters<NavigateFn>[0];
   
   type LocalizedTo = StripLocalePrefix<FileRouteTypes["to"]>;
   
   export type LocalizedNavigateOptions = Omit<
     BaseNavigateOptions,
     "to" | "params"
   > & {
     to: LocalizedTo;
     params?: Omit<NonNullable<BaseNavigateOptions["params"]>, "locale">;
   };
   
   type LocalizedNavigate = (
     options: LocalizedNavigateOptions
   ) => ReturnType<NavigateFn>;
   
   export const useLocalizedNavigate = () => {
     const navigate = useNavigate();
   
     const { locale } = useLocale();
   
     const localizedNavigate: LocalizedNavigate = (args: any) => {
       const { localePrefix } = getPrefix(locale);
   
       if (typeof args === "string") {
         return navigate({
           to: `/${LOCALE_ROUTE}${args}`,
           params: { locale: localePrefix },
         });
       }
   
       const { to, ...rest } = args;
   
       const localizedTo = `/${LOCALE_ROUTE}${to}` as any;
   
       return navigate({
         to: localizedTo,
         params: { locale: localePrefix, ...rest } as any,
       });
     };
   
     return localizedNavigate;
   };
   

9. 8

   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 React-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 Homepage

   src/routes/{-$locale}/index.tsx

   Inhalt kopieren

   Code kopieren

   Kopieren Sie den Code in die Zwischenablage

   import { createFileRoute } from "@tanstack/react-router";
   import { useIntlayer } from "react-intlayer";
   
   import LocaleSwitcher from "@/components/locale-switcher";
   import { LocalizedLink } from "@/components/localized-link";
   import { useLocalizedNavigate } from "@/hooks/useLocalizedNavigate";
   
   export const Route = createFileRoute("/{-$locale}/")({
     component: RouteComponent,
   });
   
   function RouteComponent() {
     const content = useIntlayer("app");
     const navigate = useLocalizedNavigate();
   
     return (
       <div>
         <div>
           {content.title}
           <LocaleSwitcher />
           <div>
             <LocalizedLink to="/">{content.links.home}</LocalizedLink>
             <LocalizedLink to="/about">{content.links.about}</LocalizedLink>
           </div>
           <div>
             <button onClick={() => navigate({ to: "/" })}>
               {content.links.home}
             </button>
             <button onClick={() => navigate({ to: "/about" })}>
               {content.links.about}
             </button>
           </div>
         </div>
       </div>
     );
   }
   

   Wenn Sie Ihren Inhalt in einem string-Attribut verwenden möchten, wie z. B. alt, title, href, aria-label, usw., können Sie den Wert der Funktion verwenden, wie:

   tsx

   Inhalt kopieren

   Code kopieren

   Kopieren Sie den Code in die Zwischenablage

   <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)} />
   

   Weitere Informationen zum Hook useIntlayer finden Sie in der Dokumentation.

10. 9

    Locale Switcher Component erstellen

    Erstellen Sie eine Komponente, die es Benutzern ermöglicht, Sprachen zu wechseln:

    src/components/locale-switcher.tsx

    Inhalt kopieren

    Code kopieren

    Kopieren Sie den Code in die Zwischenablage

    import { useLocation } from "@tanstack/react-router";
    import {
      getHTMLTextDir,
      getLocaleName,
      getPathWithoutLocale,
      getPrefix,
      Locales,
    } from "intlayer";
    import type { FC } from "react";
    import { useLocale } from "react-intlayer";
    
    import { LocalizedLink, type To } from "./localized-link";
    
    export const LocaleSwitcher: FC = () => {
      const { pathname } = useLocation();
    
      const { availableLocales, locale, setLocale } = useLocale();
    
      const pathWithoutLocale = getPathWithoutLocale(pathname);
    
      return (
        <ol>
          {availableLocales.map((localeEl) => (
            <li key={localeEl}>
              <LocalizedLink
                aria-current={localeEl === locale ? "page" : undefined}
                onClick={() => setLocale(localeEl)}
                params={{ locale: getPrefix(localeEl).localePrefix }}
                to={pathWithoutLocale as To}
              >
                <span>
                  {/* Locale - z. B. DE */}
                  {localeEl}
                </span>
                <span>
                  {/* Sprache in ihrer eigenen Locale - z. B. Deutsch */}
                  {getLocaleName(localeEl, locale)}
                </span>
                <span dir={getHTMLTextDir(localeEl)} lang={localeEl}>
                  {/* Sprache in aktueller Locale - z. B. Francés mit aktueller Locale auf Locales.SPANISH */}
                  {getLocaleName(localeEl)}
                </span>
                <span dir="ltr" lang={Locales.ENGLISH}>
                  {/* Sprache in Englisch - z. B. German */}
                  {getLocaleName(localeEl, Locales.ENGLISH)}
                </span>
              </LocalizedLink>
            </li>
          ))}
        </ol>
      );
    };
    

    Weitere Informationen zum Hook useLocale finden Sie in der Dokumentation.

11. 10

    HTML-Attribute verwalten

    Wie in Schritt 5 beschrieben, 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 gesetzt werden.

    src/routes/__root.tsx

    Inhalt kopieren

    Code kopieren

    Kopieren Sie den Code in die Zwischenablage

    const localeRoute = getRouteApi("/{-$locale}");
    
    function RootDocument({ children }: { children: ReactNode }) {
      const params = localeRoute.useParams();
      const locale = params?.locale ?? defaultLocale;
    
      return (
        <html dir={getHTMLTextDir(locale)} lang={locale}>
          {/* ... */}
        </html>
      );
    }
    

12. 11

    Middleware hinzufügen

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

    Beachten Sie, dass Sie zum Verwenden von intlayerProxy in der Produktion das Package vite-intlayer von devDependencies zu dependencies verschieben müssen.

    Seit Intlayer v9 ist intlayerProxy() direkt im intlayer()-Plugin gebündelt und standardmäßig über die Option routing.enableProxy aktiviert (standardmäßig true). Die separate Registrierung wie unten gezeigt ist jetzt optional: Sie wird aus Gründen der Rückwärtskompatibilität und für Setups beibehalten, die die Plugin-Reihenfolge steuern müssen. Setzen Sie routing.enableProxy: false, um sich abzumelden. Siehe v9 Release Notes.

    vite.config.ts

    Inhalt kopieren

    Code kopieren

    Kopieren Sie den Code in die Zwischenablage

    import { tanstackStart } from "@tanstack/react-start/plugin/vite";
    import viteReact from "@vitejs/plugin-react";
    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)$",
          },
        }),
        viteReact(),
      ],
    });
    

13. 12

    Metadaten internationalisieren

    Statische AuflösungDynamische AuflösungGecachte dynamische Auflösung

    getIntlayer wird synchron gegen das zusammengeführte Wörterbuch aufgelöst, das jede deklarierte Locale enthält. head bleibt synchron und nichts wird abgewartet, aber das gesamte mehrsprachige Wörterbuch wird in den an den Browser gesendeten Route-Chunk gezogen.

    src/routes/{-$locale}/index.tsx

    Inhalt kopieren

    Code kopieren

    Kopieren Sie den Code in die Zwischenablage

    import { createFileRoute } from "@tanstack/react-router";
    import {
      defaultLocale,
      getIntlayer,
      getLocalizedUrl,
      localeMap,
    } from "intlayer";
    
    export const Route = createFileRoute("/{-$locale}/")({
      component: RouteComponent,
      head: ({ params }) => {
        const { locale = defaultLocale } = params;
        const path = "/"; // Der Pfad für diese Route
    
        const metaContent = getIntlayer("app", locale);
    
        return {
          links: [
            // Canonical-Link: Verweist auf die aktuelle lokalisierte Seite
            { rel: "canonical", href: getLocalizedUrl(path, locale) },
    
            // Hreflang: Teilen Sie Google alle lokalisierten Versionen mit
            ...localeMap(({ locale: mapLocale }) => ({
              rel: "alternate",
              hrefLang: mapLocale,
              href: getLocalizedUrl(path, mapLocale),
            })),
    
            // x-default: Für Benutzer in nicht übereinstimmenden Sprachen
            // Definieren Sie die Standard-Fallback-Locale (normalerweise Ihre Hauptsprache)
            {
              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-Wörterbücher, eine Handvoll Locales oder während des Prototyping.

    getIntlayerAsync (verfügbar ab v9.4) verhält sich wie getIntlayer, aber das Build-Plugin verweist auf den Locale-spezifischen Chunk in .intlayer/dynamic_dictionaries/ statt auf das zusammengeführte Wörterbuch. Eine Seite wird daher nur mit der Locale versendet, die sie rendert. Da dieser Chunk bei Bedarf geladen wird, wird head zu async:

    src/routes/{-$locale}/index.tsx

    Inhalt kopieren

    Code kopieren

    Kopieren Sie den Code in die Zwischenablage

    import { createFileRoute } from "@tanstack/react-router";
    import {
      defaultLocale,
      getIntlayerAsync,
      getLocalizedUrl,
      localeMap,
    } from "intlayer";
    
    export const Route = createFileRoute("/{-$locale}/")({
      component: RouteComponent,
      head: async ({ params }) => {
        const { locale = defaultLocale } = params;
        const path = "/"; // Der Pfad für diese Route
    
        const metaContent = await getIntlayerAsync("app", locale);
    
        return {
          links: [
            // Canonical-Link: Verweist auf die aktuelle lokalisierte Seite
            { rel: "canonical", href: getLocalizedUrl(path, locale) },
    
            // Hreflang: Teilen Sie Google alle lokalisierten Versionen mit
            ...localeMap(({ locale: mapLocale }) => ({
              rel: "alternate",
              hrefLang: mapLocale,
              href: getLocalizedUrl(path, mapLocale),
            })),
    
            // x-default: Für Benutzer in nicht übereinstimmenden Sprachen
            // Definieren Sie die Standard-Fallback-Locale (normalerweise Ihre Hauptsprache)
            {
              rel: "alternate",
              hrefLang: "x-default",
              href: getLocalizedUrl(path, defaultLocale),
            },
          ],
          meta: [
            { title: metaContent.title },
            { name: "description", content: metaContent.meta.description },
          ],
        };
      },
    });
    

    Wenn ein head mehrere Wörterbücher liest, lösen Sie diese mit Promise.all auf: Das Abwarten jedes getIntlayerAsync auf seiner eigenen Zeile verkettet die Anforderungen, anstatt sie parallel zu verarbeiten.

    Der Kompromiss: Der dynamische Import wird aufgelöst, während head auf dem kritischen Pfad des Document-Rendering läuft. Auf einer kalten Route verzögert dies den head um einige Millisekunden und kann LCP leicht verschlechtern.

    Lösen Sie das Wörterbuch im Route-loader auf und lesen Sie es in head aus loaderData zurück. Loader der übereinstimmenden Routes werden parallel ausgeführt, und staleTime: Infinity teilt TanStack Router mit, dass das Ergebnis nie veraltet, daher wird der Locale-spezifische Chunk einmal aufgelöst und anschließend aus dem Router-Cache bereitgestellt, wobei head synchron bleibt.

    src/routes/{-$locale}/index.tsx

    Inhalt kopieren

    Code kopieren

    Kopieren Sie den Code in die Zwischenablage

    import { createFileRoute } from "@tanstack/react-router";
    import {
      defaultLocale,
      getIntlayerAsync,
      getLocalizedUrl,
      localeMap,
    } from "intlayer";
    
    export const Route = createFileRoute("/{-$locale}/")({
      component: RouteComponent,
      // Wird parallel mit den anderen übereinstimmenden Routes aufgelöst, außerhalb des head-kritischen Pfads
      loader: async ({ params }) => {
        const { locale = defaultLocale } = params;
    
        return { metaContent: await getIntlayerAsync("app", locale) };
      },
      // Das Wörterbuch ändert sich nie für eine bestimmte Locale: Den Chunk einmal auflösen
      staleTime: Infinity,
      head: ({ params, loaderData }) => {
        const { locale = defaultLocale } = params;
        const path = "/"; // Der Pfad für diese Route
    
        return {
          links: [
            // Canonical-Link: Verweist auf die aktuelle lokalisierte Seite
            { rel: "canonical", href: getLocalizedUrl(path, locale) },
    
            // Hreflang: Teilen Sie Google alle lokalisierten Versionen mit
            ...localeMap(({ locale: mapLocale }) => ({
              rel: "alternate",
              hrefLang: mapLocale,
              href: getLocalizedUrl(path, mapLocale),
            })),
    
            // x-default: Für Benutzer in nicht übereinstimmenden Sprachen
            // Definieren Sie die Standard-Fallback-Locale (normalerweise Ihre Hauptsprache)
            {
              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 sich der loader abgewickelt hat, sodass loaderData möglicherweise als undefined eingegeben wird. Behalten Sie das optionale Chaining bei oder geben Sie einen Fallback-Titel zurück.

    Sie behalten den Locale-spezifischen Chunk, ohne seine Kosten auf dem head-kritischen Pfad zu zahlen. Der Preis ist die Entwickler-Experience: Der Inhalt muss explizit vom loader zum head durch loaderData geleitet werden.

    Welche Auflösung sollte ich wählen?

    Alle Tabellendaten anzeigen

    Alle Tabellendaten anzeigen

    Tabelle in einem Modal öffnen, um alle Daten übersichtlich anzuzeigen

    	Statische Auflösung	Dynamische Auflösung	Zwischengespeicherte dynamische Auflösung
    API	getIntlayer	getIntlayerAsync (v9.4+)	getIntlayerAsync in loader (v9.4+)
    head Signatur	synchron	async	synchron, liest loaderData
    Locales versendet	jedes deklarierte Locale	angeforderte Locale nur	angeforderte Locale nur
    Client-Navigationen	nichts zu lösen	bei jedem Match erneut eingegeben	aus dem Router-Cache bereitgestellt
    Entwicklererlebnis	am einfachsten	ein await	Inhalte über loaderData verkettet

14. 13

    Rufen Sie das Locale in Ihren Server-Aktionen ab

    Möglicherweise möchten Sie auf das aktuelle Locale von Ihren Server-Aktionen oder API-Endpunkten aus zugreifen. Sie können dies mit dem getLocale-Helfer von intlayer tun.

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

    src/routes/{-$locale}/index.tsx

    Inhalt kopieren

    Code kopieren

    Kopieren Sie den Code in die Zwischenablage

    import { createServerFn } from "@tanstack/react-start";
    import {
      getRequestHeader,
      getRequestHeaders,
    } from "@tanstack/react-start/server";
    import { getCookie, getIntlayer, getLocale } from "intlayer";
    
    export const getLocaleServer = createServerFn().handler(async () => {
      const locale = await getLocale({
        // Rufen Sie das Cookie aus der Anfrage ab (Standard: 'INTLAYER_LOCALE')
        getCookie: (name) => {
          const cookieString = getRequestHeader("cookie");
    
          return getCookie(name, cookieString);
        },
        // Rufen Sie den Header aus der Anfrage ab (Standard: 'x-intlayer-locale')
        // Fallback mit Accept-Language-Aushandlung
        getHeader: (name) => getRequestHeader(name),
      });
    
      // Rufen Sie Inhalte mit getIntlayerAsync() ab
      const content = getIntlayer("app", locale);
    
      return { locale, content };
    });
    

15. 14

    Nicht gefundene Seiten verwalten

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

    Verständnis der 404-Behandlung von TanStack Router mit Locale-Präfixen

    In TanStack Router erfordert die Behandlung 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 Locale-Präfixe und leitet ungültige auf 404 weiter
    3. Catch-all-Route: Erfasst alle nicht übereinstimmenden Pfade innerhalb des Locale-Segments

    src/routes/{-$locale}/404.tsx

    Inhalt kopieren

    Code kopieren

    Kopieren Sie den Code in die Zwischenablage

    import { createFileRoute } from "@tanstack/react-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

    Inhalt kopieren

    Code kopieren

    Kopieren Sie den Code in die Zwischenablage

    import { createFileRoute, Outlet, redirect } from "@tanstack/react-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 Locale-Präfix zu validieren
      beforeLoad: ({ params }) => {
        const localeParam = params.locale;
    
        // validatePrefix prüft, ob die Locale gemäß Ihrer Intlayer-Konfiguration gültig ist
        const { isValid, localePrefix } = validatePrefix(localeParam);
    
        if (!isValid) {
          // Ungültiges Locale-Präfix - Weiterleitung zur 404-Seite mit einem gültigen Locale-Präfix
          throw redirect({
            to: "/{-$locale}/404",
            params: { locale: localePrefix },
          });
        }
      },
      component: Outlet,
      // notFoundComponent wird aufgerufen, wenn eine untergeordnete Route nicht existiert
      // z.B. löst /en/nicht-existierende-seite dies innerhalb des /en-Layouts aus
      notFoundComponent: NotFoundComponent,
    });
    

    src/routes/{-$locale}/$.tsx

    Inhalt kopieren

    Code kopieren

    Kopieren Sie den Code in die Zwischenablage

    import { createFileRoute } from "@tanstack/react-router";
    
    import { NotFoundComponent } from "./404";
    
    // Die $ (Splat/Catch-all) Route entspricht jedem Pfad, der nicht mit anderen Routen übereinstimmt
    // z.B. /en/irgendein/tief/verschachtelter/ungültiger/pfad
    // Dies stellt sicher, dass ALLE nicht übereinstimmenden Pfade innerhalb einer Locale die 404-Seite anzeigen
    // Ohne dies könnten nicht übereinstimmende tiefe Pfade eine leere Seite oder einen Fehler anzeigen
    export const Route = createFileRoute("/{-$locale}/$")({
      component: NotFoundComponent,
    });
    

16. 15

    Inhalt Ihrer Komponenten extrahieren

    Optional

    isOptional={true}>

    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

    Inhalt kopieren

    Code kopieren

    Kopieren Sie den Code in die Zwischenablage

    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. Auf diese Weise kann der Compiler nur einmal ausgeführt werden, um die App zu transformieren, und dann entfernt werden.
         */
        saveComponents: false,
    
        /**
         * Präfix für Wörterbuchschlüssel
         */
        dictionaryKeyPrefix: "",
      },
    };
    
    export default config;
    

    ExtraktionsbefehlBabel-Compiler

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

    bash

    Inhalt kopieren

    Code kopieren

    Kopieren Sie den Code in die Zwischenablage

    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 aufzunehmen:

    vite.config.ts

    Inhalt kopieren

    Code kopieren

    Kopieren Sie den Code in die Zwischenablage

    import { defineConfig } from "vite";
    import { intlayer, intlayerCompiler } from "vite-intlayer";
    
    export default defineConfig({
      plugins: [
        intlayer(),
        intlayerCompiler(), // Adds the compiler plugin
      ],
    });
    

    bash

    Inhalt kopieren

    Code kopieren

    Kopieren Sie den Code in die Zwischenablage

    npm run build # Oder npm run dev
    

17. 16

    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

    Inhalt kopieren

    Code kopieren

    Kopieren Sie den Code in die Zwischenablage

    import { 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

    Inhalt kopieren

    Code kopieren

    Kopieren Sie den Code in die Zwischenablage

    import { createFileRoute } from "@tanstack/react-router";
    import { generateSitemap } from "intlayer";
    
    const SITE_URL = (
      import.meta.env.VITE_SITE_URL ?? "http://localhost:3000"
    ).replace(/\/$/, "");
    
    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. 17

    TypeScript konfigurieren

    Intlayer verwendet Module 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

    Inhalt kopieren

    Code kopieren

    Kopieren Sie den Code in die Zwischenablage

    {
      // ... Ihre bestehenden Konfigurationen
      include: [
        // ... Ihre bestehenden Includes
        ".intlayer/**/*.ts", // Die automatisch generierten Typen einschließen
      ],
    }
    

Git-Konfiguration

Es wird empfohlen, die von Intlayer generierten Dateien zu ignorieren. So vermeiden Sie, dass diese in Ihr Git-Repository übertragen werden.

Fügen Sie dazu die folgenden Anweisungen zu Ihrer .gitignore-Datei hinzu:

# Die von Intlayer generierten Dateien ignorieren
.intlayer

VS Code Extension

Um dein Entwicklungserlebnis mit Intlayer zu verbessern, kannst du die offizielle Intlayer VS Code Extension installieren.

Installieren vom VS Code Marketplace

Diese Extension bietet:

• Autocompletion für Übersetzungsschlüssel.
• Echtzeit-Fehlererkennung für fehlende Übersetzungen.
• Inline-Vorschau von übersetztem Inhalt.
• Schnellaktionen zum einfachen Erstellen und Aktualisieren von Übersetzungen.

Für weitere Details zur Verwendung der Extension, siehe die Intlayer VS Code Extension Dokumentation.

Weiter geht's

Um weiter zu gehen, können Sie den visuellen Editor implementieren oder Ihren Inhalt mit dem CMS externalisieren.

Dokumentationsreferenzen

• Intlayer Documentation
• Tanstack Start Documentation
• useIntlayer hook
• useLocale hook
• Content Declaration
• Configuration

Häufig gestellte Fragen