変数の使用

概要

gt-next のバリアブルコンポーネントを使うことで、翻訳内に動的なコンテンツを挿入できます。 これらのコンポーネントには以下が含まれます：

• <Var>：変数を表示するためのものです。
• <Num>：数値をフォーマットするためのものです。
• <Currency>：通貨の値をフォーマットするためのものです。
• <DateTime>：日付や時刻をフォーマットするためのものです。

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

バリアブルコンポーネントとは？

バリアブルコンポーネントは、ユーザー名、数値、日付、通貨などの動的なコンテンツをラップするために使用されます。

これらのコンポーネントを使うことで、外部の翻訳を必要とせずに、ユーザーのロケールに合わせて動的な値をフォーマットし表示することができます。

動的なコンテンツを正確かつ一貫して表示するために、<T>コンポーネントと組み合わせてバリアブルコンポーネントを使用してください。

各バリアブルコンポーネントには異なる動作があります：

• <Var>: ユーザー名や識別子など、あらゆるコンテンツを動的に表示します。
• <Num>: ロケール固有のルールに従って数値をフォーマットします。
• <Currency>: 通貨記号やローカライズルールを用いて通貨の値をフォーマットします。
• <DateTime>: ロケール固有の慣習に従って日付や時刻をフォーマットします。

JSXコンテンツや文字列はGeneral Translation APIを通じて翻訳されますが、バリアブルコンポーネントは完全にローカルで処理されます。

<Num>、<Currency>、<DateTime>コンポーネントは、ユーザーのロケールに合わせてコンテンツをフォーマットするためにJS i18n APIを使用します。

変数コンポーネントの使用方法

基本的な使用方法

すべての変数コンポーネントの使用方法は同じです。

const user = {
  name: 'John',
  age: 30,
  balance: 1000,
  birthday: new Date('1990-01-01'),
}
<div>
  <Var>{user.name}</Var>
  <Num>{user.age}</Num>
  <Currency>{user.balance}</Currency>
  <DateTime>{user.birthday}</DateTime>
</div>

表示したいコンテンツを変数コンポーネントで囲むだけです。

<T>での変数コンポーネントの使用

変数コンポーネント単体では、コンテンツをフォーマットするためにユーザーのロケールの知識が必要なため、あまり機能しません。

そのため、変数コンポーネントは<T>コンポーネントと一緒に使用する必要があります。

<T>コンポーネントは、周囲のコンテンツの翻訳を処理するだけでなく、子の変数コンポーネントに正しいロケールを渡します。

<T>
  現在の時刻は<DateTime>{time}</DateTime>です。
</T>

変数のローカライゼーション

<Num>、<Currency>、<DateTime>コンポーネントには、組み込みのローカライゼーションサポートが含まれています。 これらのコンポーネントは、ユーザーが選択したロケール、またはpropsとして渡された追加オプションに基づいて、コンテンツを自動的にフォーマットします。

例えば：

• <Num>は、ローカライズされた小数点区切り文字で数値を表示します。
• <Currency>は、ローカライズされた通貨記号と位置で値を表示します。
• <DateTime>は、ロケール固有のルールに従って日付と時刻を表示します。

これらのコンポーネントに直接propsを渡すことで、デフォルトのロケールとフォーマットオプションを上書きすることもできます。

データプライバシー

変数コンポーネントはすべてのフォーマットをローカルで処理するため、（<T>コンポーネントと一緒に使用される場合）その子要素はGeneral Translation APIに翻訳のために送信されません。 これは、ユーザー名やアカウント番号などの機密データをプライベートで安全に保つのに最適です。

各変数コンポーネントは異なる方法でフォーマットを処理し、特定のタイプのコンテンツに使用する必要があります：

• <Var>：フォーマットが不要なプライベートなもの
  • ユーザー名、アカウント番号など
• <Num>：ロケールに応じてフォーマットされるべきプライベートな数値
  • 注文数量、年齢、距離など
• <Currency>：ロケールに応じてフォーマットされるべきプライベートな通貨値
  • 取引金額、アカウント残高など
• <DateTime>：ロケールに応じてフォーマットされるべきプライベートな日付と時刻の値
  • アカウント作成日、注文タイムスタンプなど

<T>
  <Var>
    <T>Hello, world!</T>
    Goodbye, World!
  </Var>
</T>

例

<Var>

<Var>コンポーネントは書式設定を行わないため、必ず<T>コンポーネントと一緒に使用してください。

import { T, Var } from 'gt-next';

export default function UserGreeting({ user }) {
  return (
    <T>
      Hello, <Var>{user.name}</Var>!
      Your address is <Var>{user.addr}</Var>
    </T>
  );
}

変数コンポーネントはデータも分離するため、翻訳の一部ではない動的なコンテンツを表示するためにも使用できます。

import { T, Var } from 'gt-next';

export default function Dashboard({ isAdmin }) {
  return (
    <T>
      Your Dashboard:
      <Var>{isAdmin ? <AdminDashboard /> : <UserDashboard />}</Var>
    </T>
  );
}

上記の例では、isAdminの三項演算子によってDashboardコンポーネントが動的になります。

<Var>コンポーネントがない場合、これは<T>コンポーネントの無効な使い方になります。

<Num>

<Num>コンポーネントは、<T>コンポーネントの子として、または単独のコンポーネントとして使用できます。

import { T, Num } from 'gt-next';
import { Badge } from '@components/custom/cart/Badge';

export default function OrderSummary() {
  const quantity = 10;
  return (
    <>
      <T>
        You have <Num>{quantity}</Num> items in your cart.
      </T>
      <Badge>
        <Num>{quantity}</Num> // This is the same as using quantity.toLocaleString()
      </Badge>
    </>
  );
}

<Currency>

<Currency>コンポーネントは、<T>コンポーネントの子として、または単独のコンポーネントとして使用できます。

import { T, Currency } from 'gt-next';
import { Badge } from '@components/custom/cart/Badge';

export default function OrderSummary() {
  const total = 1000;
  return (
    <>
      <T>
        Your total is <Currency currency={"USD"}>{total}</Currency>.
      </T>
      <Badge>
        <Currency currency={"USD"}>{total}</Currency> // This will be formatted as $1,000
      </Badge>
    </>
  );
}

<DateTime>

<DateTime>コンポーネントは、<T>コンポーネントの子として、または単独のコンポーネントとして使用できます。

import { T, DateTime } from 'gt-next';

export default function OrderSummary() {
  const date = new Date();
  return (
    <T>
      Your order was placed on <DateTime>{date}</DateTime>.
    </T>
    <DateTime>{date}</DateTime> // This is the same as using date.toLocaleDateString() or date.toLocaleTimeString()
  );
}

よくある落とし穴

ローカライズオプションの無視

<Currency> を使用する場合は、currency プロップを渡して通貨の種類を指定してください。 これにより、値を表示する際に正しい通貨記号と書式が使用されます。

他のコンポーネント（<Num> や <DateTime> など）にも、書式をカスタマイズできるオプションのプロップがあります。

注意事項

• Variable コンポーネントはデータを分離するため、翻訳の一部ではない動的コンテンツのレンダリングに使用できます。
• Variable コンポーネントはデータを General Translation API に送信しないため、機密データを安全かつプライベートに保つのに最適です。
• Variable コンポーネントは、<T> コンポーネントの子として、または単独のコンポーネントとして使用できます。

次のステップ

• Branching Components で条件付きロジックを探求しましょう。
• APIリファレンスで特定の変数コンポーネントの書式設定オプションについてさらに学びましょう:
  • <Num>
  • <Currency>
  • <DateTime>
  • <Var>