Middleware

Übersicht

Diese Anleitung führt Sie durch das Hinzufügen von i18n-Middleware-Routing und lokalisierten Pfaden zu Ihrer Next.js-Anwendung unter Verwendung der integrierten Middleware von gt-next.

Was ist i18n-Middleware-Routing?

Das Erstellen neuer Routen für jede Sprache hat den Vorteil, dass Ihre Website benutzerfreundlicher wird und das SEO verbessert. i18n-Routing ermöglicht es Ihnen, bestimmte URLs mit verschiedenen Sprachversionen zu verknüpfen. Zum Beispiel können Sie /en/airplanes für Englisch, /zh/airplanes für Chinesisch und so weiter haben.

Sie können dies mit lokalisierten Pfaden noch einen Schritt weiterführen. Diese sind eine Erweiterung des i18n-Routings und ermöglichen es Ihnen, einen Alias-Pfad für eine Sprachversion anzugeben. Zum Beispiel können Sie /en/airplanes für Englisch, /zh/飞机 für Chinesisch und so weiter festlegen.

i18n-Routing einrichten

Wir führen Sie in zwei einfachen Schritten durch das Hinzufügen von i18n-Routing zu Ihrer Next.js-Anwendung:

Schritt 1: Eine dynamische Route hinzufügen

Fügen Sie in Ihrem App-Ordner ein Verzeichnis mit dem Namen [locale] ein (z. B. app/[locale]). Legen Sie alle Ihre Seiten und Layouts in dieses Verzeichnis.

Stellen Sie sicher, dass alle speziellen Dateien innerhalb von app/ unter app/[locale] verschachtelt sind.

Schritt 2: Die Middleware-Datei hinzufügen

Erstellen Sie in Next.js eine Datei mit dem Namen middleware.js (oder .ts, wenn Sie TypeScript verwenden) im Stammverzeichnis. Wenn Sie den Ordner src/ verwenden, legen Sie die Datei stattdessen in src/middleware.js (oder .ts) ab. Fügen Sie die Funktion createNextMiddleware() in die Datei ein.

import { createNextMiddleware } from 'gt-next/middleware'

export default createNextMiddleware();

export const config = {
  matcher: [
    /*
      * Match all request paths except for the ones starting with:
      * - api (API routes)
      * - _next (internal files)
      * - static files
      */
    "/((?!api|static|.*\\..*|_next).*)",
  ],
}

Lokalisierte Pfade einrichten

Du kannst lokalisierte Pfade über die Option pathConfig in der Middleware-Datei angeben.

export default createNextMiddleware({
  pathConfig: {
    // You can specify a shared path (optional)
    // This will create "/en/about" and "/zh/about"
    "/about": "/about",

    // Specify localized paths
    // This will create "/en/airplanes" and "/zh/飞机"
    "/airplanes": {
      "zh": "/飞机",
    }

    // Add dynamic path parameters
    // This will create "/en/airports/123" and "/zh/飞机机场/123"
    "/airports/[id]": {
      "zh": "/飞机机场/[id]",
    }
  },
});

In diesem Beispiel erstellen wir einen Standardpfad für /en/about und lokalisierte Pfade für /en/airplanes und /en/airports/[id]. Im Chinesischen werden diese entsprechend auf /zh/about, /zh/飞机 und /zh/飞机机场/[id] abgebildet.

Routing-Verhalten

Standardmäßiges Locale-Präfix

Standardmäßig wird Ihre defaultLocale (d. h. die Standardsprache Ihrer App) nicht mit einem Locale-Code in der URL versehen. Wenn Ihre Standard-Locale zum Beispiel en ist und Sie eine Seite unter /about haben, ist diese auf Englisch unter /about erreichbar. Auf Chinesisch hingegen ist sie unter /zh/about auf Chinesisch erreichbar.

Wenn Sie dieses Verhalten nicht wünschen, kann es deaktiviert werden, indem Sie prefixDefaultLocale in der Middleware-Konfiguration auf false setzen.

Locale-Erkennung und Weiterleitung

Die Middleware erkennt die Sprache des Nutzers anhand von (1) dem Locale im URL-Pfad, (2) dem Referrer-Locale, (3) den vom Browser akzeptierten Sprachen und (4) schließlich der defaultLocale. Der Nutzer wird dann entsprechend weitergeleitet.

Sobald eine lokalisierte Version der Seite existiert, wird der Nutzer zur lokalisierten URL weitergeleitet. Zum Beispiel wird /zh/airplanes immer zu /zh/飞机 weiterleiten.

Spezialfall: Lokalisierte Pfade ohne Locale-Präfix

Wenn Sie zu einem lokalisierten Pfad ohne Locale-Präfix navigieren (z. B. /飞机), wird die Middleware diesen Pfad mit dem Locale-Präfix versehen, das sie als Ihr aktuelles Locale erkennt.

Zum Beispiel wird ein Besuch von /飞机 nur dann zu /zh/飞机 weiterleiten, wenn die Middleware Ihr Locale explizit als zh erkennt. Das ist praktisch, funktioniert aber nur, wenn die Middleware Ihr Locale als zh erkennt.

Andernfalls wird Ihr Pfad mit Ihrem aktuellen Locale-Präfix versehen. Zum Beispiel wird ein Besuch von /飞机 zu /en/飞机 weiterleiten, wenn die Middleware Ihr Locale als en erkennt. Dies führt zu einem 404-Fehler.

Wir empfehlen, für alle Links in Ihrem Projekt immer den Pfad Ihrer defaultLocale zu verwenden. So wird immer automatisch zum korrekten lokalisierten Pfad weitergeleitet.

<Link href="/about">About</Link>
<Link href="/planes">Planes</Link>
<Link href="/airports/123">Airport 123</Link>

Wenn Sie explizit auf ein anderes Locale verlinken möchten, können Sie dies tun, indem Sie den lokalisierten Pfad verwenden.

<Link href="/zh/about">About in Chinese</Link>
<Link href="/zh/飞机">Planes in Chinese</Link>
<Link href="/zh/飞机机场/123">Airport 123 in Chinese</Link>

Hinweise

• i18n-Routing ändert die URL-Struktur Ihrer Anwendung. Jede Sprache hat ihre eigene URL.
• Die Middleware-Datei ist erforderlich, um die Routing-Logik zu steuern.
• Sie können die unterstützten Sprachversionen in der Middleware-Konfiguration und in der Next-Konfigurationsdatei angeben.

Nächste Schritte

• Siehe die API-Dokumentation für createNextMiddleware().