ブランチの使用方法

概要

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

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

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

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

ブランチコンポーネントとは？

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

<Branch>

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

例えば、<Branch>コンポーネントは、アプリケーションの状態やユーザーの設定、その他の動的なデータに基づいて条件付きレンダリングを行うのに最適です。

最も一般的な使い方は、三項演算子や条件演算子の代わりとして利用することです。

<Plural>

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

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

複数形コンポーネントは、しばしば<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.</>}
    // Additional options
    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-next';

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-next';

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-next';

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-next';

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-next はアプリケーションに常に表示するフォールバックコンテンツがあることを保証します。

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

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

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

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

また、英語の場合は singular と plural を指定することもできます。

注意事項

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

次のステップ

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