React usage

@18ways/react gives you the runtime primitives. The main job is to scope them cleanly.

Root mode vs scope mode

At the root, Ways owns the API key, locale, accepted locales, and shared translation store.

Nested Ways scopes only need context:

tsx

<Ways apiKey="pk_dummy_demo_token" locale="es-ES" baseLocale="en-GB" context="checkout">
  <Ways context="payment-form">
    <PaymentForm />
  </Ways>
</Ways>

Si un subárbol necesita su propia sesión de configuración regional, dale su propia raíz en lugar de depender de una anulación limitada de locale:

tsx

<Ways apiKey="pk_dummy_demo_token" locale="en-GB" baseLocale="en-GB" context="app">
  <MarketingSite />
 
  <Ways apiKey="pk_dummy_demo_token" locale="ja-JP" baseLocale="en-GB" context="hero-demo">
    <EmbeddedLocaleDemo />
  </Ways>
</Ways>

Esa raíz anidada obtiene su propia configuración regional seleccionada, estado de carga y almacén hidratado.

Loading state

If you want to reflect translation work in the UI, use useTranslationLoading().

tsx

import { useTranslationLoading } from '@18ways/react';
 
function SavePanel() {
  const isTranslationLoading = useTranslationLoading();
 
  return <span>{isTranslationLoading ? 'Loading translations...' : 'Ready'}</span>;
}

useTranslationLoading() solo hace seguimiento del trabajo que bloquea el contexto actual. Los controles de nivel raíz como LanguageSwitcher ya leen por ti el estado de carga en tiempo de ejecución de la raíz.

Suspense

<T> y useT() lanzan el error al límite más cercano de React o del framework cuando una lectura que no es de transición sigue pendiente. Durante una transición real de configuración regional, siguen renderizando la configuración regional establecida anterior mediante la alternativa de reserva del almacén en lugar de suspender. El trabajo bloqueante está limitado por suspenseTimeoutMs; después de eso, el renderizado continúa con la mejor alternativa de reserva disponible mientras la carga de la traducción continúa en segundo plano.

Locale hooks

The root runtime exposes two low-level hooks:

tsx

import { useCurrentLocale, useSetCurrentLocale } from '@18ways/react';

Use them when you want to build your own locale controls instead of LanguageSwitcher.

`LanguageSwitcher`

The built-in switcher is controlled and composable.

tsx

<LanguageSwitcher currentLocale={locale} onLocaleChange={setLocale} direction="down" />

Lee la lista de configuraciones regionales aceptadas del runtime raíz y gestiona los estados de carga mientras se resuelve la siguiente configuración regional. Durante una transición de configuración regional, la interfaz de usuario traducida sigue usando la última configuración regional establecida como respaldo hasta que la siguiente configuración regional esté lista.

Component composition

Keep the sentence together and let <T> preserve the UI shape.

tsx

<T>
  <a href="/pricing">Click here</a> to see more
</T>

Message formatter escape hatches

The default formatter is waysParser. Only switch away from it if you have a concrete reason.

messageFormatter="none" leaves strings alone.
a custom formatter function lets you own interpolation fully.

That should be rare.