API Next.js

tyndale-next добавляет специфичную для Next.js связку поверх tyndale-react.

Пути импорта

tyndale-next — хелперы и компоненты для приложения
tyndale-next/server — безопасные для сервера экспорты для кода RSC
tyndale-next/config — обёртка для конфигурации Next
tyndale-next/middleware — middleware маршрутизации локалей

Основы App Router

`TyndaleServerProvider`

Серверный компонент, который считывает public/_tyndale/{locale}.json и manifest.json с диска и гидратирует клиентский provider.

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

Примечания:

Читает локаль по умолчанию из TYNDALE_DEFAULT_LOCALE.
Читает результат сборки переводов из TYNDALE_OUTPUT или public/_tyndale.
Не устанавливает <html dir> за вас. Используйте useDirection() на клиенте или getDirection(locale) на сервере.

`TyndaleNextClientProvider`

Клиентская обёртка вокруг TyndaleProvider. Она подключает useChangeLocale() к навигации Next, добавляя в URL префикс локали.

В большинстве приложений следует использовать TyndaleServerProvider вместо прямого монтирования этого компонента.

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

Возвращает параметры локали для generateStaticParams(), считывая tyndale.config.json.

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

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

Форма возвращаемого значения:

Array<{ locale: string }>

Результат включает сначала локаль по умолчанию, затем каждую локаль из locales.

Конфигурация

`withTyndaleConfig(nextConfig)`

Оборачивает вашу конфигурацию Next и добавляет runtime-переменные окружения, которые Tyndale читает во время сборки и обработки запросов.

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

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

Что добавляется:

TYNDALE_DEFAULT_LOCALE
TYNDALE_LOCALES
TYNDALE_COOKIE_NAME
TYNDALE_LOCALE_ALIASES
TYNDALE_OUTPUT
webpack alias, чтобы сервер и клиент разрешали один и тот же экземпляр tyndale-react

Middleware

`createTyndaleMiddleware()`

Создаёт middleware Next, которое обрабатывает маршрутизацию локалей.

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

export default createTyndaleMiddleware();

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

Поведение по порядку:

Использует локаль из URL, если она присутствует.
Если нет — использует cookie локали.
Если нет — использует заголовок Accept-Language.
Если нет — использует defaultLocale.

Также:

перенаправляет alias-локали на их каноническую локаль
перенаправляет неподдерживаемые префиксы локали на локаль по умолчанию
устанавливает заголовок запроса x-tyndale-locale для валидных маршрутов с префиксом локали
сохраняет выбранную локаль в cookie TYNDALE_LOCALE

Хелперы направления и локали

`useDirection()`

Клиентский хук, который возвращает 'ltr' или 'rtl' для текущей локали.

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

Безопасный для сервера хелпер, который возвращает 'ltr' или 'rtl' для строки локали.

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

const dir = getDirection(locale);

`isRtlLocale(locale)`

Возвращает true, когда локаль использует письменность справа налево.

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

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

`resolveAlias(locale, aliases)`

Сопоставляет alias локали с её канонической локалью.

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

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

Граница кэша

`TyndaleCache`

Клиентская граница кэша для переведённого контента в общих layout. Ключ кэша ограничен и id, и текущей локалью.

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

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

Используйте это для повторяющегося переведённого UI в layout, которые перерисовываются во время навигации. Не используйте это как общий кэш данных.