Uso de Next.js

El adaptador Next es donde reside la mayor parte del comportamiento específico de enrutamiento.

Enrutamiento de rutas

pathRouting vive en las opciones de init() que le das al adaptador.

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

Eso le indica al adaptador qué rutas el middleware debe localizar.

Con esa configuración en su lugar:

• /pricing puede convertirse en /fr-FR/pricing
• /dashboard permanece /dashboard
• /__design permanece /__design
• /__email permanece /__email

El adaptador también excluye automáticamente rutas no de página obvias como /_next y /api.

Flujo de middleware

waysMiddleware() es la API de middleware de init(). Esta:

• resuelve la configuración regional a partir de la cookie, la ruta, la preferencia del navegador o baseLocale
• normaliza la ruta de acceso entrante si se debe agregar o quitar un prefijo de localización
• crea el NextResponse correcto para redirecciones, reescrituras o solicitudes de paso
• escribe la cookie de preferencia de localización utilizando la política de init()
• reenvía los encabezados de solicitud sensibles a la configuración regional que tu aplicación puede leer más tarde

Para el caso normal, esto es suficiente:

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

Cuando necesites personalizar el resultado del middleware, pasa las opciones explícitamente:

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

Accede a transformRequestHeaders o transformResponse solo cuando necesites un comportamiento adicional sobre el resultado del middleware por defecto.

Orden de resolución de la configuración regional

El adaptador actual resuelve la configuración regional en este orden:

1. 18ways_locale cookie
2. prefijo de localidad en la ruta
3. preferencias del navegador
4. baseLocale

Ese orden es importante porque permite que una preferencia de usuario explícita anule todo lo demás.

Cambios de configuración regional del lado del cliente

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

Usa useLocale() cuando quieras tus propios controles. Usa LanguageSwitcher cuando quieras el selector ya hecho conectado al mismo estado de localización.

Cuando el enrutamiento de rutas está habilitado, setLocale() actualiza la URL. Cuando está deshabilitado, actualiza el estado de la localización y refresca la ruta.

Enlaces conscientes de la configuración regional

Hay dos ayudantes útiles para el cliente:

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

• useLocalizedHref() construye hrefs internos conscientes de la localidad.
• useUnlocalizedPathname() te permite comparar rutas sin preocuparte por el prefijo de la configuración regional actual.

Esos enlaces deben seguir las mismas reglas que tu middleware impone. Si el middleware está añadiendo o eliminando prefijos de localización para una ruta, useLocalizedHref() debería ser el helper que utilices en el cliente.

Metadatos traducidos

generateWaysMetadata() puede traducir campos de metadatos de cadena por ti.

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

Cuando el enrutamiento de rutas está habilitado, el adaptador también emite URLs canónicas y de idioma alternativo específicas de la localidad.

Composición de middleware

El adaptador no asume que posee todo tu middleware. waysMiddleware() se puede llamar dentro de tu capa de autenticación, o personalizarse con transformRequestHeaders y transformResponse.

Lo que pertenece a la siguiente pista

Documenta el comportamiento aquí cuando depende de:

• middleware
• prefijos de ruta
• metadatos traducidos
• Resolución de locales SSR

Si el comportamiento es solo la representación de React, pertenece a la pista de React en su lugar.