Uso do Next.js

O adaptador Next é onde a maior parte do comportamento específico de roteamento reside.

Roteamento de caminho

pathRouting reside nas opções init() que você fornece ao 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'],
  },
});

Isso informa ao adaptador quais caminhos o middleware deve localizar.

Com essa configuração em vigor:

• /pricing pode se tornar /fr-FR/pricing
• /dashboard permanece /dashboard
• /__design permanece /__design
• /__email permanece /__email

O adaptador também exclui automaticamente rotas não de página óbvias, como /_next e /api.

Fluxo de middleware

waysMiddleware() é a API de middleware do init(). Ela:

• resolve o local a partir do cookie, pathname, preferência do navegador ou baseLocale
• normaliza o caminho de entrada se um prefixo de localidade deve ser adicionado ou removido
• cria o NextResponse correto para redirecionamentos, reescritas ou solicitações de passagem
• escreve o cookie de preferência de localidade usando a política de init()
• encaminha os cabeçalhos de solicitação cientes da localidade que seu aplicativo pode ler posteriormente

Para o caso normal, isso é suficiente:

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

Quando você precisar personalizar o resultado do middleware, passe as opções explicitamente:

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

Acesse transformRequestHeaders ou transformResponse apenas quando precisar de um comportamento extra além do resultado padrão do middleware.

Ordem de resolução de localidade

O adaptador atual resolve o locale nesta ordem:

1. cookie 18ways_locale
2. prefixo de localidade no caminho
3. preferências do navegador
4. baseLocale

Essa ordem é importante porque permite que uma preferência explícita do usuário sobreponha tudo o mais.

Mudanças de localidade do lado do cliente

Use useLocale() do @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}
    />
  );
}

Use useLocale() quando você quiser seus próprios controles. Use LanguageSwitcher quando você quiser o seletor pronto conectado ao mesmo estado de localidade.

Quando o roteamento de caminho está habilitado, setLocale() atualiza a URL. Quando está desabilitado, ele atualiza o estado da localidade e atualiza a rota.

Links cientes da localidade

Existem dois auxiliares de cliente úteis:

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

• useLocalizedHref() constrói hrefs internos cientes da localidade.
• useUnlocalizedPathname() permite que você compare rotas sem se preocupar com o prefixo de localidade atual.

Esses links devem seguir as mesmas regras que seu middleware impõe. Se o middleware está adicionando ou removendo prefixos de localidade para uma rota, useLocalizedHref() deve ser o helper que você utiliza no t lado do cliente.

Metadados traduzidos

generateWaysMetadata() pode traduzir campos de metadados de string para você.

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

Quando o roteamento de caminho está habilitado, o adaptador também emite URLs canônicas e alternativas específicas de localidade.

Composição de middleware

O adaptador não assume que possui todo o seu middleware. waysMiddleware() pode ser chamado dentro da sua camada de autenticação, ou personalizado com transformRequestHeaders e transformResponse.

O que pertence à próxima faixa

Documente o comportamento aqui quando depender de:

• middleware
• prefixos de caminho
• metadados traduzidos
• Resolução de localidade SSR

Se o comportamento for apenas a renderização do React, ele pertence à trilha do React.