API Next.js

tyndale-next ajoute un câblage spécifique à Next.js au-dessus de tyndale-react.

Chemins d’import

tyndale-next — helpers et composants orientés application
tyndale-next/server — exports sûrs côté serveur pour le code RSC
tyndale-next/config — wrapper de configuration Next
tyndale-next/middleware — middleware de routage des locales

Fondamentaux de l’App Router

`TyndaleServerProvider`

Composant serveur qui lit public/_tyndale/{locale}.json et manifest.json depuis le disque, puis hydrate le provider client.

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

Props

locale: string
children: React.ReactNode

Notes :

Lit la locale par défaut depuis TYNDALE_DEFAULT_LOCALE.
Lit la sortie des traductions depuis TYNDALE_OUTPUT ou public/_tyndale.
Ne définit pas <html dir> pour vous. Utilisez useDirection() côté client ou getDirection(locale) côté serveur.

`TyndaleNextClientProvider`

Wrapper client autour de TyndaleProvider. Il connecte useChangeLocale() à la navigation Next en poussant une URL préfixée par la locale.

La plupart des applications devraient utiliser TyndaleServerProvider plutôt que monter celui-ci directement.

'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()`

Retourne les params de locale pour generateStaticParams() en lisant tyndale.config.json.

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

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

Forme de retour :

Array<{ locale: string }>

Le résultat inclut d’abord la locale par défaut, puis chaque locale de locales.

Configuration

`withTyndaleConfig(nextConfig)`

Enveloppe votre configuration Next et injecte les variables d’environnement d’exécution que Tyndale lit au moment du build et lors des requêtes.

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

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

Ce que cela ajoute :

TYNDALE_DEFAULT_LOCALE
TYNDALE_LOCALES
TYNDALE_COOKIE_NAME
TYNDALE_LOCALE_ALIASES
TYNDALE_OUTPUT
un alias webpack pour que le serveur et le client résolvent la même instance de tyndale-react

Middleware

`createTyndaleMiddleware()`

Crée le middleware Next qui gère le routage des locales.

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

export default createTyndaleMiddleware();

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

Comportement, dans l’ordre :

Utilise la locale de l’URL lorsqu’elle est présente.
Se rabat sur le cookie de locale.
Se rabat sur l’en-tête Accept-Language.
Se rabat sur defaultLocale.

Il :

redirige les alias de locale vers leur locale canonique
redirige les préfixes de locale non pris en charge vers la locale par défaut
définit un en-tête de requête x-tyndale-locale pour les routes valides préfixées par une locale
persiste la locale choisie dans le cookie TYNDALE_LOCALE

Helpers de direction et de locale

`useDirection()`

Hook client qui renvoie 'ltr' ou 'rtl' pour la locale actuelle.

'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 sûr côté serveur qui renvoie 'ltr' ou 'rtl' pour une chaîne de locale.

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

const dir = getDirection(locale);

`isRtlLocale(locale)`

Renvoie true lorsque la locale utilise une écriture de droite à gauche.

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

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

`resolveAlias(locale, aliases)`

Associe un alias de locale à sa locale canonique.

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

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

Limite de cache

`TyndaleCache`

Boundary de cache client pour le contenu traduit dans les layouts partagés. La clé de cache est définie à la fois par id et par la locale actuelle.

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

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

Utilisez-le pour les éléments d’UI traduits répétés dans des layouts qui se réaffichent pendant la navigation. Ne l’utilisez pas comme cache de données général.