ブランチの使用

概要

gt-react の分岐コンポーネントは、特定の条件に基づいて動的にコンテンツをレンダリングすることを可能にします。これらのコンポーネントには以下が含まれます：

• <Branch>: 一致する branch プロップに基づいてコンテンツをレンダリングします。
• <Plural>: 指定された数値の複数形ルールに基づいてコンテンツをレンダリングします。

どちらのコンポーネントも、ローカライズされたアプリケーションにおける条件分岐ロジックや動的コンテンツの管理に強力なツールを提供します。

このガイドでは、以下の内容を解説します：

ブランチコンポーネントとは何ですか？

ブランチコンポーネントは、特定の条件や値に基づいて、どのコンテンツをレンダリングするかを動的に選択します。

<Branch>

<Branch> コンポーネントは、提供された branch 値に基づいて異なるコンテンツをレンダリングすることができます。 一致するブランチが見つからない場合、フォールバックの children コンテンツがレンダリングされます。

例えば、<Branch> コンポーネントは、アプリケーションの状態、ユーザー設定、または任意の動的データに基づく条件付きレンダリングに最適です。

最も一般的な使用例は、三項演算子または条件演算子の代わりに使用することです。

<Plural>

<Plural> コンポーネントは <Branch> の機能を拡張し、複数形と数の一致を自動的に処理します。 提供された n 値を使用して、ロケール固有のルールに基づいてどの複数形を表示するかを決定します。

例えば、<Plural> コンポーネントは「1つのアイテム」と「2つのアイテム」のように、単数形と複数形のテキストを動的にレンダリングするのに理想的です。

複数形コンポーネントは、数字とそれに対応するテキストをローカライズするために、しばしば <Num> コンポーネントと組み合わせて使用されます。

<T> との使用

<Branch> と <Plural> コンポーネントは、動的コンテンツを翻訳用にサニタイズするために <T> コンポーネント内で使用する必要があります。

<T> コンポーネント内で使用すると、コンテンツは自動的に翻訳され、ユーザーが選択した言語でレンダリングされます。

単独で使用すると、翻訳せずにコンテンツをそのままレンダリングします。

ブランチコンポーネントの使い方

<Branch>を使った分岐ロジック

<Branch>コンポーネントは、branch値に基づいて柔軟にコンテンツを切り替えるために使用されます。

複数の可能なブランチを定義でき、コンポーネントは一致するブランチキーに対応するコンテンツをレンダリングします。

さらに、<Branch>コンポーネントと組み合わせて他の変数コンポーネントを使用することもできます。

const branch: 'option1' | 'option2' = 'option1';
<T>
  <Branch 
    branch={branch}
    option1={<p>Option 1</p>}
    option2={<p>Option 2</p>}
  >
    Fallback content
  </Branch>
</T>

<Branch>コンポーネントは<T>コンポーネント内で使用する必要があります。これにより、コンテンツが自動的に翻訳されます。

詳細についてはAPIリファレンスをご覧ください。

<Plural>を使った複数形

<Plural>コンポーネントは、nの値に基づいて複数形のロジックを自動化します。 このコンポーネントは、指定された数値とロケールに応じて適切な複数形を動的に選択します。

const count: number = 1;
<T>
  <Plural
    n={count}
    singular={<><Num>{1}</Num> item.</>}
    plural={<><Num>{count}</Num> items.</>}
    // 追加オプション
    zero={<><Num>{count}</Num> items.</>}
    one={<><Num>{count}</Num> item.</>}
    two={<><Num>{count}</Num> items.</>}
    few={<><Num>{count}</Num> items.</>}
    many={<><Num>{count}</Num> items.</>}
    other={<><Num>{count}</Num> items.</>}
    dual={<><Num>{count}</Num> items.</>}
  />
</T>

利用可能な複数形はロケールによって異なり、Unicode CLDR複数形ルールに従います。

詳細についてはAPIリファレンスをご覧ください。

ブランチコンポーネントを使用するタイミング

ブランチコンポーネントは、アプリケーション内の動的コンテンツを管理するために重要です。

条件に基づいて異なるコンテンツを表示する必要がある場合は、<Branch>を使用してください。

これらの条件は、変数コンポーネント、ブール値、または関数に基づくことができます。

例えば、コードに三項演算子や条件付きレンダリングがある場合、<Branch>を使用してそれを置き換えることができます。

const isActive = true;
// Ternary operator
<Branch branch={isActive} true={<p>The user is active.</p>} false={<p>The user is inactive.</p>}>
  <p>Status unknown.</p>
</Branch>

// Conditional rendering
<Branch branch={isActive} true={<p>The user is active.</p>}>
  <></>
</Branch>

// Ternary operator
const isActive = true;
{isActive ? <p>The user is active.</p> : <p>The user is inactive.</p>}

// Conditional rendering
{isActive && <p>The user is active.</p>}

正しい複数形でコンテンツをレンダリングしたい場合は、<Plural>を使用してください。

const count = 1;
<Plural n={count} one={<p>1 item</p>} other={<p>{count} items</p>} />

const count = 1;
{count === 1 ? <p>1 item</p> : <p>{count} items</p>}

例

<Branch>

import { T, Branch, Var } from 'gt-react';

export default function UserStatus() {
  const [status, setStatus] = useState<'active' | 'inactive' | undefined>(undefined);
  const [name, setName] = useState<string>('John Doe');
  return (
    <T>
      <Branch
        branch={status}
        active={<p>The user <Var>{name}</Var> is active.</p>}
        inactive={<p>The user <Var>{name}</Var> is inactive.</p>}
      >
        <p>Status unknown.</p>
      </Branch>
    </T>
  );
}

上記の例では、<Branch>コンポーネントはstatusの値に応じて3つの表示内容を動的に切り替えます。

statusが"active"の場合、コンポーネントは次のように表示します：

<p>The user <Var>{name}</Var> is active.</p>

statusが"inactive"の場合、コンポーネントは次のように表示します：

<p>The user <Var>{name}</Var> is inactive.</p>

statusが"active"でも"inactive"でもない場合、フォールバックの内容が表示されます：

<p>Status unknown.</p>

<Branch>コンポーネントが <T> コンポーネントでラップされているため、表示される内容は自動的に文脈に応じて翻訳されます。

この例では、ユーザーのサブスクリプションプランに応じて異なる説明を表示します。

import { Branch } from 'gt-react';

export default function SubscriptionDetails() {
  const [plan, setPlan] = useState<'free' | 'premium' | 'enterprise' | undefined>(undefined);
  return (
    <Branch
      branch={plan}
      free={<p>You are on the Free plan. Upgrade to unlock more features!</p>}
      premium={<p>You are enjoying the Premium plan with full access to features.</p>}
      enterprise={<p>You are on the Enterprise plan. Contact support for tailored solutions.</p>}
    >
      <p>No subscription plan detected.</p>
    </Branch>
  );
}

• branchプロップは、どのプランのメッセージを表示するかを決定します。
• planが"free"、"premium"、または"enterprise"の場合、それぞれに対応したメッセージが表示されます。
• planがこれらの値のいずれにも一致しない場合、フォールバックの内容（"No subscription plan detected."）が表示されます。

<Plural>

<Plural>コンポーネントは、nの値に基づいて単数形と複数形の内容を動的に切り替えます。 この例では、ユーザーの受信箱にある未読メッセージの数を表示します。

import { T, Plural, Num } from 'gt-react';

export default function UnreadMessages() {
  const [unreadCount, setUnreadCount] = useState<number>(1);
  return (
    <T>
      <Plural
        n={unreadCount}
        one={<>You have <Num>{unreadCount}</Num> unread message.</>}
        other={<>You have <Num>{unreadCount}</Num> unread messages.</>}
      />
    </T>
  );
}

• nプロップは未読メッセージの数を指定します。
• unreadCountが1の場合、コンポーネントは "You have 1 unread message." を表示します。
• それ以外の値の場合は、"You have X unread messages."（Xは<Num>でフォーマットされたunreadCountの値）を表示します。

よくある落とし穴

ブランチ値の欠落

ブランチ値が提供されていない、またはどのキーとも一致しない場合、<Branch> コンポーネントはフォールバックの子コンテンツをレンダリングします。 可能なブランチキーが branch プロップに渡される値と一致することを常に確認してください。

import { Branch } from 'gt-react';

export default function StatusMessage({ status }) {
  return (
    <Branch
      branch={status}
      active={<p>The user is active.</p>}
      inactive={<p>The user is inactive.</p>}
    >
      <p>Status unknown.</p>
    </Branch>
  );
}

もし status が undefined または active や inactive 以外の値である場合、フォールバックコンテンツの "Status unknown." が表示されます。

複数形の欠落

デフォルト言語に必要なすべての複数形を指定することを忘れないでください。 これにより gt-react はアプリケーションが常にフォールバックコンテンツを表示できるようにします。

例えば、英語がデフォルト言語の場合、英語のすべての複数形を提供する必要があります。

import { Plural, Num } from 'gt-react';

<Plural
  n={count}
  one={<>You have <Num>{count}</Num> unread message.</>}
  other={<>You have <Num>{count}</Num> unread messages.</>}
/>

ここでは、英語の one と other の複数形を提供しています。

あるいは、英語の場合は singular と plural を提供することもできます。

メモ

• ブランチコンポーネントは、アプリケーション内の動的でローカライズされたコンテンツを管理するために不可欠です。
• <Branch>コンポーネントは非常に柔軟性があり、さまざまな条件や状態に適応できます。
• <Plural>コンポーネントは、ロケール固有のルールに自動的に準拠することで複数形化を簡素化します。
• エラー処理とユーザーエクスペリエンスを向上させるために、常にフォールバックのchildrenプロップを含めてください。

次のステップ

• 詳細については、APIリファレンスの <Branch> および <Plural> をご覧ください。
• 複数形ルールや分岐ロジックについては、Unicode CLDR Pluralization Rules でさらに学ぶことができます。
• Variable Components の使い方を探ってみましょう。