Uso de Next.js

El adaptador de Next se divide en:

un archivo local 18ways.config.ts
integración de Next en tiempo de compilación en next.config.js
ayudantes del servidor de @18ways/next/server
ayudantes de cliente en @18ways/next/client

Configuración compartida

Crea 18ways.config.ts en la raíz de tu aplicación.

// 18ways.config.ts
import type { WaysConfig } from '@18ways/next/config';
 
export default {
  apiKey: process.env.NEXT_PUBLIC_18WAYS_PUBLIC_API_KEY,
  baseLocale: 'en-GB',
  router: 'app', // 'app', 'path', or 'none' depending on if you use app router, path router, or if you don't want the router to sync with locale at all
} satisfies WaysConfig;

A continuación, en tu next.config.js:

// next.config.js
const { withWays } = require('@18ways/next/config');
 
module.exports = withWays({
  // your normal next config here
});

Enrutamiento de rutas de App Router

Para App Router, el enrutamiento por configuración regional está definido por el propio árbol de rutas:

las rutas localizadas públicas se encuentran en app/[lang]/...
las rutas sin localizar permanecen fuera de [lang]

Enrutador de rutas, enrutamiento de rutas

Si quieres enrutamiento de locales basado en la ruta, establece router: 'path' y proporciona acceptedLocales. withWays() configura entonces el enrutamiento nativo de rutas i18n de Next por ti, con la detección automática de locales de Next desactivada para que 18ways siga encargándose de la resolución de locales.

// 18ways.config.ts
import type { WaysConfig } from '@18ways/next/config';
 
export default {
  apiKey: process.env.NEXT_PUBLIC_18WAYS_PUBLIC_API_KEY,
  baseLocale: 'en-GB',
  router: 'path', // 'app', 'path', or 'none' depending on if you use app router, path router, or if you don't want the router to sync with locale at all
  acceptedLocales: ['en-GB', 'fr-FR'], // keep this in sync with the languages enabled in your 18ways dashboard
} satisfies WaysConfig;

Usa router: 'none' cuando alguna capa de enrutado existente ya se encargue de las URL con configuración regional y solo quieras que 18ways gestione el estado de la configuración regional.

Diseño raíz

Importar de @18ways/next/server.

tsx

import { WaysRoot, htmlAttrs } from '@18ways/next/server';
 
export default async function RootLayout({ children, params }) {
  const attrs = await htmlAttrs({ params });
 
  return (
    <html {...attrs}>
      <body>
        <WaysRoot params={params}>{children}</WaysRoot>
      </body>
    </html>
  );
}

Proxy

En App Router, usa proxy.ts para gestionar la redirección de la configuración regional raíz y cualquier canonicalización de dominio:

export { default, config } from '@18ways/next/proxy';

Si tu aplicación ya tiene su propio proxy.ts o middleware.ts, compón getWaysProxyResponse() y devuélvelo antes del resto de la lógica específica de tu aplicación:

import type { NextFetchEvent, NextRequest } from 'next/server';
import { getWaysProxyResponse } from '@18ways/next/proxy';
 
export default async function middleware(request: NextRequest, event: NextFetchEvent) {
  const waysResponse = await getWaysProxyResponse(request);
  if (waysResponse) {
    return waysResponse;
  }
 
  // your existing middleware logic
}

Cambios de configuración regional del lado del cliente

Utiliza useLocale() de @18ways/next/client.

tsx

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

Cuando la ruta actual está localizada, setLocale() conserva la ruta y actualiza el segmento locale. Cuando la ruta actual no está localizada, mantiene la ruta sin localizar y actualiza el estado de locale.

Importa desde @18ways/next/client:

tsx

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

Link localiza automáticamente los href internos
useRouter() aplica las mismas reglas a push() y replace()
useUnlocalizedPathname() te permite comparar el estado de la ruta sin el prefijo de configuración regional

Usa la anulación de locale solo cuando necesites forzar una elección:

locale="fr-FR" fuerza un destino localizado
locale={false} obliga a un destino sin localizar

Metadatos traducidos

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

tsx

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