Verwendung von Next.js

Der Next-Adapter ist der Ort, an dem sich das meiste routing-spezifische Verhalten befindet.

Pfadrouting

pathRouting befindet sich in den init() Optionen, die Sie dem Adapter geben.

// src/lib/ways.ts
import { init as initWays } from '@18ways/next/server';
 
export const {
  waysMiddleware,
} = initWays({
  apiKey: 'YOUR_18WAYS_PUBLIC_API_KEY',
  baseLocale: 'en-GB',
  persistLocaleCookie: true,
  pathRouting: {
    exclude: ['/dashboard', '/__design', '/__email'],
  },
});

Das sagt dem Adapter, welche Pfade das Middleware lokalisiert werden sollen.

Mit dieser Konfiguration:

• /pricing kann zu /fr-FR/pricing werden
• /dashboard bleibt /dashboard
• /__design bleibt /__design
• /__email bleibt /__email

Der Adapter schließt auch offensichtlich keine Seitenrouten wie /_next und /api automatisch aus.

Middleware-Flow

waysMiddleware() ist die Middleware-API von init(). Sie:

• bestimmt die Sprache aus dem Cookie, dem Pfadnamen, den Browsereinstellungen oder baseLocale
• normalisiert den eingehenden Pfadnamen, wenn ein Sprachpräfix hinzugefügt oder entfernt werden soll
• erstellt die richtige NextResponse für Weiterleitungen, Umschreibungen oder Durchlaufanforderungen
• schreibt das Cookie für die Gebietsschema-Präferenz unter Verwendung der Richtlinie von init()
• leitet die lokalisierten Anfrage-Header weiter, die Ihre App später lesen kann

Für den Normalfall ist das ausreichend:

// src/middleware.ts
import type { NextRequest } from 'next/server';
import { waysMiddleware } from '@/lib/ways';
 
export default function middleware(
  request: NextRequest
) {
  return waysMiddleware(request);
}

Wenn Sie das Middleware-Ergebnis anpassen müssen, übergeben Sie die Optionen ausdrücklich:

return waysMiddleware(request, {
  /**
   * Defaults to noop.
   * Use this to add or replace
   * request headers before the
   * response is created.
   */
  transformRequestHeaders: (context) =>
    context.requestHeaders,
 
  /**
   * Defaults to noop.
   * Use this to decorate or replace
   * the final NextResponse.
   */
  transformResponse: (response) => response,
});

Greifen Sie nur auf transformRequestHeaders oder transformResponse zu, wenn Sie zusätzliches Verhalten über das Standard-Middleware-Ergebnis hinaus benötigen.

Reihenfolge der Gebietsschemaauflösung

Der aktuelle Adapter löst die Gebietsschema in dieser Reihenfolge auf:

1. 18ways_locale Cookie
2. Lokalisierungsprefix im Pfadnamen
3. Browser-Einstellungen
4. basisLocale

Diese Reihenfolge ist wichtig, da sie eine ausdrückliche Benutzerpräferenz über alles andere stellt.

Änderungen der Client-seitigen Locale

Verwenden Sie useLocale() von @18ways/next/client.

'use client';
 
import {
  LanguageSwitcher,
} from '@18ways/react';
import { useLocale } from '@18ways/next/client';
 
export function LocaleControls() {
  const { locale, setLocale } = useLocale();
 
  return (
    <LanguageSwitcher
      currentLocale={locale}
      onLocaleChange={setLocale}
    />
  );
}

Verwenden Sie useLocale(), wenn Sie Ihre eigenen Steuerelemente möchten. Verwenden Sie LanguageSwitcher, wenn Sie den fertigen Selector verwenden möchten, der mit demselben Locale-Zustand verbunden ist.

Wenn das Pfadrouting aktiviert ist, aktualisiert setLocale() die URL. Wenn es deaktiviert ist, aktualisiert es den Locale-Zustand und aktualisiert die Route.

Lokalisierte Links

Es gibt zwei nützliche Client-Helfer:

import {
  useLocalizedHref,
  useUnlocalizedPathname,
} from '@18ways/next/client';

• useLocalizedHref() erstellt lokalisierte interne hrefs.
• useUnlocalizedPathname() ermöglicht es Ihnen, Routen zu vergleichen, ohne sich um das aktuelle Locale-Präfix kümmern zu müssen.

Diese Links sollten denselben Regeln folgen, die Ihr Middleware durchsetzt. Wenn die Middleware Sprachpräfixe für eine Route hinzufügt oder entfernt, sollte useLocalizedHref() der Helfer sein, auf den Sie im Client zurückgreifen.

Übersetzte Metadaten

generateWaysMetadata() kann für Sie String-Metadatenfelder übersetzen.

export async function generateMetadata() {
  return generateWaysMetadata((t) => ({
    title: t('Pricing'),
    description: t(
      'Simple pricing for runtime translation'
    ),
  }));
}

Wenn das Pfadrouting aktiviert ist, gibt der Adapter auch lokal spezifische kanonische und alternative Sprache-URLs aus.

Middleware-Zusammensetzung

Der Adapter geht nicht davon aus, dass er Ihre gesamte Middleware besitzt. waysMiddleware() kann innerhalb Ihrer Authentifizierungsschicht aufgerufen oder mit transformRequestHeaders und transformResponse angepasst werden.

Was gehört in den nächsten Track

Dokumentieren Sie hier das Verhalten, wenn es abhängt von:

• Middleware
• Pfadnamen-Präfixe
• übersetzte Metadaten
• SSR Gebietsermittlung

Wenn das Verhalten nur das Rendern von React ist, gehört es stattdessen in den React-Track.