Utilisation de Next.js

L'adaptateur Next est l'endroit où se trouve la plupart des comportements spécifiques au routage.

Routage de chemin

pathRouting se trouve dans les options init() que vous donnez à l'adaptateur.

// 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'],
  },
});

Cela indique à l'adaptateur quels chemins le middleware doit localiser.

Avec cette configuration en place :

• /pricing peut devenir /fr-FR/pricing
• /dashboard reste /dashboard
• /__design reste /__design
• /__email reste /__email

L'adaptateur exclut également automatiquement les routes non-page évidentes comme /_next et /api.

Flux de middleware

waysMiddleware() est l'API middleware de init(). Elle :

• résout la locale à partir du cookie, du chemin d'accès, des préférences du navigateur ou de baseLocale
• normalise le chemin d'accès entrant si un préfixe de locale doit être ajouté ou supprimé
• crée le bon NextResponse pour les redirections, réécritures ou requêtes de passage
• écrit le cookie de préférence locale en utilisant la politique de init()
• transmet les en-têtes de requête sensibles à la locale que votre application peut lire plus tard

Pour le cas normal, cela suffit :

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

Lorsque vous devez personnaliser le résultat du middleware, passez les options explicitement :

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,
});

Accédez à transformRequestHeaders ou transformResponse uniquement lorsque vous avez besoin d'un comportement supplémentaire en plus du résultat par défaut du middleware.

Ordre de résolution de la locale

L'adaptateur actuel résout la locale dans cet ordre :

1. 18ways_locale cookie
2. préfixe de locale dans le chemin d'accès
3. préférences du navigateur
4. baseLocale

Cet ordre est important car il permet à une préférence explicite de l'utilisateur de prévaloir sur tout le reste.

Modifications de la locale côté client

Utilisez useLocale() de @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}
    />
  );
}

Utilisez useLocale() lorsque vous souhaitez vos propres contrôles. Utilisez LanguageSwitcher lorsque vous voulez le sélecteur prêt à l'emploi connecté au même état de locale.

Lorsque le routage par chemin est activé, setLocale() met à jour l'URL. Lorsqu'il est désactivé, il met à jour l'état de la locale et rafraîchit la route.

Liens sensibles à la locale

Il y a deux assistants clients utiles :

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

• useLocalizedHref() construit des href internes sensibles à la locale.
• useUnlocalizedPathname() vous permet de comparer des routes sans vous soucier du préfixe de la locale actuelle.

Ces liens doivent suivre les mêmes règles que celles imposées par votre middleware. Si le middleware ajoute ou supprime des préfixes de locale pour une route, useLocalizedHref() devrait être l'outil que vous utilisez sur le client.

Métadonnées traduites

generateWaysMetadata() peut traduire les champs de métadonnées de chaîne pour vous.

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

Lorsque le routage par chemin est activé, l'adaptateur émet également des URL canoniques et des URL de langue alternatives spécifiques à la locale.

Composition de middleware

L'adaptateur ne suppose pas qu'il possède l'ensemble de votre middleware. waysMiddleware() peut être appelé à l'intérieur de votre couche d'authentification, ou personnalisé avec transformRequestHeaders et transformResponse.

Ce qui appartient à la prochaine piste

Documentez le comportement ici lorsqu'il dépend de :

• middleware
• préfixes de chemin d'accès
• métadonnées traduites
• Résolution de la locale SSR

Si le comportement est simplement un rendu React, il appartient plutôt à la piste React.