Uso do Next.js

O adaptador Next está dividido em:

um ficheiro local 18ways.config.ts
integração do Next em tempo de compilação em next.config.js
helpers do servidor de @18ways/next/server
ajudantes do cliente em @18ways/next/client

Configuração partilhada

Crie 18ways.config.ts na raiz da sua aplicação.

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

Depois, no teu next.config.js:

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

Encaminhamento de caminhos do App Router

Para o App Router, o encaminhamento por idioma é definido pela própria árvore de rotas:

as rotas públicas localizadas ficam em app/[lang]/...
As rotas não localizadas permanecem fora de [lang]

Encaminhamento de rota Path Router

Se quiser encaminhamento de locale baseado no caminho, defina router: 'path' e forneça acceptedLocales. withWays() configura então, por si, o encaminhamento nativo de caminhos i18n do Next, com a deteção automática de locale do Next desativada, para que o 18ways continue a controlar a resolução de locale.

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

Use router: 'none' quando já existe uma camada de encaminhamento que controla os URLs com localização e só queres que o 18ways gestione o estado da localização.

Layout raiz

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

No App Router, usa proxy.ts para tratar o redirecionamento da localidade raiz e qualquer canonização de domínio:

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

Se a sua aplicação já tiver o seu próprio proxy.ts ou middleware.ts, componha getWaysProxyResponse() e devolva-o antes do resto da lógica específica da sua aplicação:

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
}

Alterações de localidade do lado do cliente

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

Quando a rota atual está localizada, setLocale() preserva a rota e atualiza o segmento regional. Quando a rota atual não está localizada, mantém a rota não localizada e atualiza o estado regional.

Importar de @18ways/next/client:

tsx

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

Liga localiza automaticamente os href internos
useRouter() aplica as mesmas regras a push() e replace()
useUnlocalizedPathname() permite comparar o estado da rota sem o prefixo da localidade

Utilize a substituição de locale apenas quando precisar de forçar uma escolha:

locale="fr-FR" força um alvo localizado
locale={false} força um destino não localizado

Metadados traduzidos

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

tsx

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