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>

サブツリーに独自のロケールセッションが必要な場合は、スコープ付きの 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>

そのネストされたルートは、独自の選択済みロケール、読み込み状態、そしてハイドレート済みストアを持ちます。

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() は、現在のコンテキストに対するブロッキング作業のみを追跡します。LanguageSwitcher のようなルートレベルのコントロールは、すでにルートのランタイム読み込み状態を読み取っています。

サスペンス

<T> と useT() は、トランジションではない読み取りがまだ保留中の場合、最も近い React またはフレームワークの境界へスローします。実際のロケール遷移中は、サスペンドする代わりに、ストアのフォールバックを介して直前に確定したロケールの描画を維持します。ブロッキング作業は 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 は次のロケールの準備が整うまで、最後に確定したロケールをフォールバックとして使い続けます。

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.