API do Next.js

tyndale-next adiciona a integração específica do Next.js por cima de tyndale-react.

Caminhos de importação

tyndale-next — helpers e componentes voltados para a aplicação
tyndale-next/server — exports seguros para servidor para código RSC
tyndale-next/config — wrapper de configuração do Next
tyndale-next/middleware — middleware de roteamento de locale

Essenciais do App Router

`TyndaleServerProvider`

Componente de servidor que lê public/_tyndale/{locale}.json e manifest.json do disco e hidrata o provider do cliente.

import { TyndaleServerProvider } from 'tyndale-next/server';

export default async function LocaleLayout({
  children,
  params,
}: {
  children: React.ReactNode;
  params: Promise<{ locale: string }>;
}) {
  const { locale } = await params;

  return (
    <html lang={locale}>
      <body>
        <TyndaleServerProvider locale={locale}>{children}</TyndaleServerProvider>
      </body>
    </html>
  );
}

Propriedades

locale: string
children: React.ReactNode

Observações:

Lê o locale padrão de TYNDALE_DEFAULT_LOCALE.
Lê a saída de tradução de TYNDALE_OUTPUT ou public/_tyndale.
Não define <html dir> para você. Use useDirection() no cliente ou getDirection(locale) no servidor.

`TyndaleNextClientProvider`

Wrapper de cliente em torno de TyndaleProvider. Ele conecta useChangeLocale() à navegação do Next ao fazer push de uma URL com prefixo de locale.

A maioria dos apps deve usar TyndaleServerProvider em vez de montar isso diretamente.

'use client';

import { TyndaleNextClientProvider } from 'tyndale-next';

export function Providers({
  children,
  locale,
  defaultLocale,
  translations,
  manifest,
}: {
  children: React.ReactNode;
  locale: string;
  defaultLocale: string;
  translations: Record<string, string>;
  manifest: Record<string, unknown> | null;
}) {
  return (
    <TyndaleNextClientProvider
      locale={locale}
      defaultLocale={defaultLocale}
      translations={translations}
      manifest={manifest}
    >
      {children}
    </TyndaleNextClientProvider>
  );
}

`generateStaticLocaleParams()`

Retorna parâmetros de locale para generateStaticParams() lendo tyndale.config.json.

import { generateStaticLocaleParams } from 'tyndale-next/server';

export function generateStaticParams() {
  return generateStaticLocaleParams();
}

Formato de retorno:

Array<{ locale: string }>

O resultado inclui primeiro o locale padrão e depois todos os locales em locales.

Configuração

`withTyndaleConfig(nextConfig)`

Encapsula sua configuração do Next e injeta as variáveis de ambiente de runtime que o Tyndale lê no build e no tempo de requisição.

import { withTyndaleConfig } from 'tyndale-next/config';

export default withTyndaleConfig({
  reactStrictMode: true,
});

O que ele adiciona:

TYNDALE_DEFAULT_LOCALE
TYNDALE_LOCALES
TYNDALE_COOKIE_NAME
TYNDALE_LOCALE_ALIASES
TYNDALE_OUTPUT
um alias do webpack para que servidor e cliente resolvam a mesma instância de tyndale-react

Middleware

`createTyndaleMiddleware()`

Cria o middleware do Next que lida com o roteamento de locale.

import { createTyndaleMiddleware } from 'tyndale-next/middleware';

export default createTyndaleMiddleware();

export const config = {
  matcher: ['/((?!api|_next|_tyndale|.*\\..*).*)'],
};

Comportamento, em ordem:

Usa o locale na URL quando presente.
Faz fallback para o cookie de locale.
Faz fallback para o cabeçalho Accept-Language.
Faz fallback para defaultLocale.

Também:

redireciona aliases de locale para seu locale canônico
redireciona prefixos de locale não suportados para o locale padrão
define um cabeçalho de requisição x-tyndale-locale para rotas válidas com prefixo de locale
persiste o locale escolhido no cookie TYNDALE_LOCALE

Auxiliares de direção e locale

`useDirection()`

Hook de cliente que retorna 'ltr' ou 'rtl' para o locale atual.

'use client';

import { useDirection } from 'tyndale-next';

export function HtmlShell({ children }: { children: React.ReactNode }) {
  const dir = useDirection();
  return <div dir={dir}>{children}</div>;
}

`getDirection(locale)`

Helper seguro para servidor que retorna 'ltr' ou 'rtl' para uma string de locale.

import { getDirection } from 'tyndale-next/server';

const dir = getDirection(locale);

`isRtlLocale(locale)`

Retorna true quando o locale usa uma escrita da direita para a esquerda.

import { isRtlLocale } from 'tyndale-next/server';

isRtlLocale('ar'); // true
isRtlLocale('en-US'); // false

`resolveAlias(locale, aliases)`

Mapeia um alias de locale para seu locale canônico.

import { resolveAlias } from 'tyndale-next/server';

resolveAlias('pt-BR', { 'pt-BR': 'pt' }); // 'pt'

Fronteira de cache

`TyndaleCache`

Fronteira de cache no cliente para conteúdo traduzido em layouts compartilhados. A chave de cache é delimitada por id e pelo locale atual.

import { TyndaleCache } from 'tyndale-next';
import { T } from 'tyndale-react';

<TyndaleCache id="footer-copy">
  <T>Documentation, guides, and examples.</T>
</TyndaleCache>

Use isso para UI traduzida repetida em layouts que são renderizados novamente durante a navegação. Não use como um cache de dados geral.