変数の使用

概要

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

• <Var>：変数の表示用。
• <Num>：数値のフォーマット用。
• <Currency>：通貨のフォーマット用。
• <DateTime>：日付や時刻のフォーマット用。

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

変数コンポーネントとは何ですか？

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

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

動的なコンテンツが正確かつ一貨して表示されるようにするために、<T>コンポーネントと組み合わせて変数コンポーネントを使用してください。

各変数コンポーネントには異なる動作があります：

• <Var>: ユーザー名や識別子などの任意のコンテンツを動的にレンダリングします。
• <Num>: ロケール固有のルールに従って数値をフォーマットします。
• <Currency>: 通貨記号とローカライゼーションルールを使用して通貨の値をフォーマットします。
• <DateTime>: ロケール固有の規則を使用して日付と時刻をフォーマットします。

JSXコンテンツと文字列は一般翻訳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-react';

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

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

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 APIs に送信しないため、機密データを安全かつプライベートに保つのに最適です。
• Variable コンポーネントは、<T> コンポーネントの子として、または単独のコンポーネントとして使用できます。

次のステップ

• 分岐コンポーネントで条件付きロジックを探索する。
• 特定の変数コンポーネントのフォーマットオプションについてAPIリファレンスでさらに学ぶ：
  • <Num>
  • <Currency>
  • <DateTime>
  • <Var>