Using Variables

Overview

Variable components in gt-react allow you to insert dynamic content into translations. These components include:

• <Var>: For rendering variables.
• <Num>: For formatting numbers.
• <Currency>: For formatting currency values.
• <DateTime>: For formatting dates and times.

In this guide, we will cover:

What are variable components?

Variable components are used to wrap dynamic content such as user names, numerical values, dates, and currencies.

These components allow you to format and render dynamic values in a way that aligns with your user's locale, without requiring any external translations.

Use variable components in conjunction with the <T> component to ensure that dynamic content is displayed accurately and consistently.

Each variable component has different behavior:

• <Var>: Renders any content dynamically, such as user names or identifiers.
• <Num>: Formats numerical values according to locale-specific rules.
• <Currency>: Formats currency values with symbols and localization rules.
• <DateTime>: Formats dates and times using locale-specific conventions.

While JSX content and strings are translated via the General Translation API, variable components are completely handled locally.

The <Num>, <Currency>, and <DateTime> components use the JS i18n API to format the content according to the user's locale.

How to use variable components

Basic Usage

The usage for all variable components is the same.

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>

Simply wrap the variable component around the content you want to display.

Using Variable Components in <T>

By themselves, variable components don't do much, since they require knowledge of the user's locale to format the content.

Thus, you should use variable components with <T> components.

The <T> component will not only handle the translation of the surrounding content, but also pass the correct locale to its child variable components.

<T>
  The current time is <DateTime>{time}</DateTime>.
</T>

Variable localization

The <Num>, <Currency>, and <DateTime> components include built-in localization support. These components automatically format their content based on your user's selected locale, or based on additional options passed as props.

For example:

• <Num> displays numbers with localized decimal separators.
• <Currency> displays values with localized currency symbols and positioning.
• <DateTime> displays dates and times according to locale-specific rules.

You can also override the default locale and formatting options by passing props directly to these components.

Data Privacy

Variable components handle all formatting locally; therefore, none of their children are sent to the General Translation APIs for translation (when used with <T> components). This is perfect for keeping sensitive data, such as user names or account numbers, private and secure.

Each variable component handles formatting differently and should be used for specific types of content:

• <Var>: Anything private that does not require formatting
  • User names, account numbers, etc.
• <Num>: Private numerical values that should be formatted according to locale
  • Order quantities, age, distance, etc.
• <Currency>: Private currency values that should be formatted according to locale
  • Transaction amounts, account balances, etc.
• <DateTime>: Private date and time values that should be formatted according to locale
  • Account creation dates, order timestamps, etc.

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

Examples

<Var>

Because the <Var> component does not do any formatting, it should always be used in conjunction with a <T> component.

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>
  );
}

Variable components also isolate data, so they can be used to render dynamic content that is not part of a translation.

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

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

In the example above, the isAdmin ternary operator makes the Dashboard component dynamic.

Without the <Var>, component, this would be an invalid use of the <T> component.

<Num>

The <Num> component can be used as a child of a <T> component or as a standalone component.

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>

The <Currency> component can be used as a child of a <T> component or as a standalone component.

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>

The <DateTime> component can be used as a child of a <T> component or as a standalone component.

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()
  );
}

Common Pitfalls

Ignoring Localization Options

For <Currency>, make sure to pass the currency prop to specify the currency type. This ensures that the correct currency symbol and formatting are used when displaying the value.

Other components, such as <Num> and <DateTime>, also have optional props that allow you to customize the formatting as well.

Notes

• Variable components isolate data, so they can be used to render dynamic content that is not part of a translation.
• Variable components do not send data to the General Translation APIs, so they are perfect for keeping sensitive data private and secure.
• Variable components can be used either as a child of a <T> component or as a standalone component.

Next Steps

• Explore conditional logic in Branching Components.
• Learn more about formatting options for specific variable components in the API Reference:
  • <Num>
  • <Currency>
  • <DateTime>
  • <Var>