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>

Kung kailangan ng subtree ang sarili nitong locale session, bigyan ito ng sarili nitong root sa halip na umasa sa isang scoped locale override:

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>

Ang nested root na iyon ay magkakaroon ng sarili nitong napiling locale, loading state, at hydrated store.

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() ay sumusubaybay lang sa blocking work para sa kasalukuyang context. Ang mga kontrol sa root-level tulad ng LanguageSwitcher ay binabasa na ang root runtime loading state para sa iyo.

Suspense

<T> at useT() ay nagti-throw papunta sa pinakamalapit na hangganan ng React o framework kapag may hindi pa tapos na read na hindi transition. Sa panahon ng totoong paglipat ng locale, patuloy nilang nirirender ang nakaraang naayos na locale sa pamamagitan ng store fallback sa halip na mag-suspend. Ang blocking work ay nililimitahan ng suspenseTimeoutMs, at pagkatapos noon ay magpapatuloy ang rendering gamit ang pinakamahusay na available na fallback habang ang paglo-load ng translation ay nagpapatuloy sa background.

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

Binabasa nito ang tinatanggap na listahan ng locale mula sa root runtime at hinahawakan ang mga state ng paglo-load habang nire-resolve ang susunod na locale. Sa panahon ng paglipat ng locale, patuloy na ginagamit ng isinaling UI ang huling naayos na locale bilang fallback nito hanggang maging handa ang susunod na locale.

Komposisyon ng bahagi

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.