React API

tyndale-react は、Tyndale アプリで使われるランタイムプロバイダー、翻訳フック、フォーマット用コンポーネント、サーバーヘルパーを提供します。

プロバイダーとコンテキスト

`TyndaleProvider`

プレーンな React アプリ向けのルートプロバイダーです。ロケールファイルを読み込み、翻訳状態を公開し、すべてのフックとコンポーネントを動作させます。

import { TyndaleProvider } from 'tyndale-react';

export function App() {
  return (
    <TyndaleProvider defaultLocale="en" locale="fr">
      <Routes />
    </TyndaleProvider>
  );
}

プロパティ

defaultLocale: string
locale?: string
basePath?: string — デフォルトは /_tyndale
initialTranslations?: Record<string, string>
initialManifest?: Manifest | null
onLocaleChange?: (locale: string) => void
children: React.ReactNode

initialTranslations を省略した場合、プロバイダーはブラウザで {basePath}/{locale}.json と manifest.json を取得します。

`TyndaleContext`

現在のロケール、マニフェスト、読み込み済み翻訳、読み込み状態、changeLocale() 関数を保持する React コンテキストです。

カスタムなコンテキストアクセスが必要な場合のみ直接使用してください。ほとんどのアプリでは、以下のフックを使うことを推奨します。

`useTyndaleContext()`

TyndaleContext を読み取り、プロバイダーがマウントされていない場合は例外を投げます。

import { useTyndaleContext } from 'tyndale-react';

function LocaleBadge() {
  const { locale, defaultLocale, isLoading } = useTyndaleContext();
  return <span>{isLoading ? 'Loading…' : `${locale} / ${defaultLocale}`}</span>;
}

コアフック

`useTranslation()`

補間をサポートした翻訳関数を返します。

import { useTranslation } from 'tyndale-react';

function Greeting({ name }: { name: string }) {
  const t = useTranslation();
  return <p>{t('Hello, {name}!', { name })}</p>;
}

シグネチャ:

(source: string, vars?: Record<string, string | number>) => string

`useLocale()`

現在のロケール文字列を返します。

import { useLocale } from 'tyndale-react';

const locale = useLocale();

プロバイダーの外側では空文字列を返し、開発時には警告をログ出力します。

`useChangeLocale()`

アクティブなロケールを変更する関数を返します。

import { useChangeLocale } from 'tyndale-react';

function LocaleSwitcher() {
  const changeLocale = useChangeLocale();

  return <button onClick={() => changeLocale('es')}>Español</button>;
}

プレーンな React では、新しいロケール JSON を取得してプロバイダーの状態を更新します。tyndale-next では、同じフックが代わりにルート変更をトリガーします。

`useDictionary(filenameKey)`

辞書ファイルの辞書エントリをプレーンオブジェクトとして返します。

import { useDictionary } from 'tyndale-react';

function Nav() {
  const labels = useDictionary('common');
  return <a href="/docs">{labels.docs}</a>;
}

シグネチャ:

(filenameKey: string) => Record<string, string>

このフックは type: 'dictionary' を持つマニフェストエントリを参照し、翻訳が見つからない場合は辞書キーにフォールバックします。

サーバーヘルパー

`getTranslation(options)`

ディスクからロケールファイルを読み込み、翻訳関数を返す非同期サーバーヘルパーです。

tyndale-react とサーバー専用サブパスの両方から利用できます。

import { getTranslation } from 'tyndale-react/server';

const t = await getTranslation({
  locale: 'fr',
  defaultLocale: 'en',
  outputPath: 'public/_tyndale',
});

const title = t('Welcome, {name}!', { name: 'Ada' });

オプション:

locale: string
defaultLocale?: string
outputPath: string

locale === defaultLocale の場合、ファイル読み込みをスキップし、補間を適用したソース文字列を返します。

メッセージマーカー

`msg(source)`

コンポーネントのレンダー外で抽出対象としてリテラル文字列をマークし、レンダー時に解決される React 要素を返します。

import { msg } from 'tyndale-react';

const nav = [{ href: '/', label: msg('Home') }];

`msgString(source)`

抽出対象としてリテラル文字列をマークし、React 要素ではなくプレーン文字列を返します。

import { msgString } from 'tyndale-react';

export const copy = {
  docs: msgString('Documentation'),
};

msgString() は、プレーンな TypeScript モジュール、Astro frontmatter、サーバーユーティリティなどの非 React コンテキストで使用してください。

翻訳とフォーマット用コンポーネント

`<T>`

子要素をシリアライズし、翻訳済みの wire format を参照して、翻訳結果をレンダーすることで JSX コンテンツを翻訳します。

import { T, Var } from 'tyndale-react';

<T>
  Hello, <Var name="name">{name}</Var>!
</T>

翻訳がない場合は、元の子要素をレンダーします。

`<Var>`

<T> 内の動的な値をマークします。

import { T, Var } from 'tyndale-react';

<T>
  Hello, <Var name="name">{name}</Var>!
</T>

`<Num>`

Intl.NumberFormat で数値をフォーマットします。<T> 内では名前付きプレースホルダーとしても機能します。

import { T, Num } from 'tyndale-react';

<T>
  You have <Num name="count" value={count} /> unread messages.
</T>

`<Currency>`

アクティブなロケールで通貨をフォーマットします。

import { Currency } from 'tyndale-react';

<Currency value={49.99} currency="USD" />

`<DateTime>`

Intl.DateTimeFormat で日付またはタイムスタンプをフォーマットします。

import { DateTime } from 'tyndale-react';

<DateTime value={new Date()} options={{ dateStyle: 'long' }} />

`<Plural>`

アクティブなロケールに対して正しい複数形ブランチを選択します。<T> 内では ICU 複数形構文にシリアライズされます。

import { Plural } from 'tyndale-react';

<Plural count={count} one="1 item" other="{count} items" />

高度なヘルパー

これらは公開エクスポートですが、抽出出力や wire-format の内部仕様と連携する場合を除き、ほとんどのアプリでは必要ありません。

`computeHash(content)` / `hash(content)`

翻訳参照に使われる、Tyndale の正規化済み SHA-256 ハッシュを計算します。

import { computeHash } from 'tyndale-react';

const id = computeHash('Welcome to our app.');

`escapeWireFormat(text)` / `unescapeWireFormat(text)`

Tyndale wire format 用にリテラルテキストをエスケープまたは復元します。

`serializeChildren(children)` / `deserializeWireFormat(...)`

React の子要素を Tyndale wire format に変換し、逆変換します。

`parseIcuPlural(input)`

ICU 複数形ブロックを、その変数名とブランチに解析します。

これらは、Tyndale のシリアライズされた翻訳フォーマットを中心にツールや高度なランタイム連携を構築する場合にのみ使用してください。

React API

プロバイダーとコンテキスト

TyndaleProvider

TyndaleContext

useTyndaleContext()

コアフック

useTranslation()

useLocale()

useChangeLocale()

useDictionary(filenameKey)

サーバーヘルパー

getTranslation(options)

メッセージマーカー

msg(source)

msgString(source)