Uso do Next.js

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

Roteamento de caminhos

pathRouting vive 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 diz ao adaptador quais caminhos o middleware deve localizar.

Com essa configuração em vigor:

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

O adaptador também exclui automaticamente rotas não relacionadas a páginas, como /_next e /api.

Fluxo de middleware

waysMiddleware() é a API de middleware de 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 a NextResponse correta para redirecionamentos, reescritas ou pedidos de passagem
• escreve o cookie de preferência de localidade usando a política de init()
• encaminha os cabeçalhos de pedido sensíveis à localização que a sua aplicação pode ler mais tarde

Para o caso normal, isto é 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 precisar de 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. 18ways_locale cookie
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 utilizador sobreponha tudo o resto.

Alterações de localidade do lado do cliente

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

Use useLocale() quando quiser os seus próprios controlos. Use LanguageSwitcher quando quiser o seletor pré-fabricado ligado ao mesmo estado de localidade.

Quando o encaminhamento de caminho está ativado, setLocale() atualiza a URL. Quando está desativado, atualiza o estado da localidade e atualiza a rota.

Links cientes da localidade

Existem dois auxiliares úteis para o cliente:

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

• useLocalizedHref() constrói hrefs internos cientes da localidade.
• useUnlocalizedPathname() permite comparar rotas sem se preocupar com o prefixo da localidade atual.

Esses links devem seguir as mesmas regras que o seu middleware impõe. Se o middleware estiver a adicionar ou remover prefixos de localidade para uma rota, useLocalizedHref() deve ser o helper que você utiliza no the client.

Metadados traduzidos

generateWaysMetadata() pode traduzir campos de metadados de string para si.

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

Quando o encaminhamento de caminho está ativado, 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 depende 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.