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>

اگر کسی سب ٹری کو اپنی الگ لوکیل سیشن درکار ہو، تو اسے scoped locale override پر انحصار کرنے کے بجائے اپنا الگ root دیں:

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>

اس nested root کو اپنی منتخب لوکیل، لوڈنگ حالت، اور 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() صرف موجودہ context کے لیے بلاک کرنے والے کام کو ٹریک کرتا ہے۔ LanguageSwitcher جیسے روٹ-لیول کنٹرولز آپ کے لیے پہلے ہی روٹ رن ٹائم کی لوڈنگ حالت پڑھتے ہیں۔

سسپنس

<T> اور useT() جب کوئی غیر-منتقلی ریڈ ابھی زیرِ التوا ہو تو قریب ترین React یا فریم ورک باؤنڈری پر throw کرتے ہیں۔ ایک حقیقی لوکیل منتقلی کے دوران، وہ اسٹور کے فال بیک کے ذریعے پچھلا طے شدہ لوکیل ہی رینڈر کرتے رہتے ہیں، بجائے اس کے کہ suspended ہوں۔ بلاک کرنے والا کام suspenseTimeoutMs تک محدود ہے، جس کے بعد رینڈرنگ بہترین دستیاب فال بیک کے ساتھ جاری رہتی ہے جبکہ ترجمے کی لوڈنگ پسِ منظر میں چلتی رہتی ہے۔

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

یہ روٹ رن ٹائم سے قبول شدہ لوکیلز کی فہرست پڑھتا ہے اور لوڈنگ کی حالتوں کو اس وقت سنبھالتا ہے جب اگلا لوکیل حل ہو رہا ہوتا ہے۔ لوکیل کی منتقلی کے دوران، ترجمہ شدہ UI آخری طے شدہ لوکیل کو اپنے فال بیک کے طور پر استعمال کرتی رہتی ہے جب تک اگلا لوکیل تیار نہ ہو جائے۔

جزوی ترکیب

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.