Variable Components

Overview

Variable Components in gt-next allow you to insert dynamic, untranslatable content into translations. These components include:

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

These components are used inside <T> components or as part of template dictionary entries to ensure dynamic content is displayed accurately and consistently.

In this reference, we will cover:

What Variable Components are and how they work.
Design patterns for using Variable Components in your applications.
Some examples of how to use each Variable Component.
Common pitfalls to avoid when working with Variable Components.

Variable Components are used to wrap dynamic content. This includes user names, numerical values, dates, and currencies. These components are essential for maintaining the integrity of localized content, as they allow you to format and display dynamic values in a way that aligns with the user's locale.

Each Variable Component has specialized behavior:

<Var>: Displays general variables, 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 APIs, Variable Components are completely handled locally. This means that the content within these components is never sent to the translation service, ensuring data privacy and security.

While the <Var> component is used for as a catch all for general variables, the <Num>, <Currency>, and <DateTime> components are used for specific types of data that require localization formatting. For these, we use the JS I18n API to format the content according to the user's locale.

Design Patterns

Wrapping Variable Components in `<T>`

Variable Components are often wrapped within a <T> component or as part of a dictionary entry. This ensures that the surrounding content is translated while the variable content is rendered dynamically and unaltered.

import { T, Var } from 'gt-next';
 
export default function UserGreeting({ user }) {
  return (
    <T id="greeting">
      Hello, <Var>{user.name}</Var>!
    </T>
  );
}

Variable Components and Localization

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

For example:

<Num> can display numbers with localized decimal separators.
<Currency> can format values with the correct currency symbol and positioning.
<DateTime>can format 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

As mentioned above, Variable Components handle all reformatting locally; therefore, no information is sent to the General Translation APIs for translation. 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 private content:

<Var>: Private information that does not change format based on locale: e.g., user names, account numbers.
<Num>: Private numerical values that should be formatted according to locale: e.g., order quantities, age, distance.
<Currency>: Private currency values that should be formatted according to locale: e.g., transaction amounts, account balances.
<DateTime>: Private date and time values that should be formatted according to locale: e.g., account creation dates, order timestamps.

It should be noted that the same is not true for Branching Components and <T> components, which do send data to the General Translation APIs for translation.

Examples

`<Var>` Example

Because the <Var> component does not reformat content, it is almost exclusively wrapped in a <T> component.

In this example we see that passing a variable to the value field or passing a variable as a child of the <Var> component have the same effect. As with any other component, the <Var> component can be used to wrap any arbitrary JSX content.

import { T, Var } from 'gt-next';
 
export default function UserGreeting({ user }) {
  return (
    <T id="greeting">
      Hello, <Var>{user.name}</Var>!
      Your address is <Var value={user.addr} />
    </T>
  );
}

`<Num>` Example

Unlinke the <Var> component, the <Num> component is used to format numerical values according to locale-specific rules. In this example, we can see how the <Num> component can be used both as a child of a <T> component and as a standalone component.

import { T, Num } from 'gt-next';
import { Badge } from '@components/custom/cart/Badge';
 
export default function OrderSummary({ order }) {
  return (
    <>
      <T id="orderSummary">
        You have <Num value={order.quantity} /> items in your cart.
      </T>
      <Badge>
        <Num>{order.quantity}</Num>
      </Badge>
    </>
  );
}

`<Currency>` Example

The <Currency> component takes a numeric value and formats it according to the provided currency string. In this example, we see how the <Currency> component can be used both as a child of a <T> component and as a standalone component.

import { T, Currency } from 'gt-next';
import { Badge } from '@components/custom/cart/Badge';
 
export default function OrderSummary({ order }) {
  return (
    <>
      <T id="orderSummary">
        Your total is <Currency currency={curr}>{order.total}</Currency>.
      </T>
      <Badge>
        <Currency value={order.total} currency={curr} />
      </Badge>
    </>
  );
}

`<DateTime`> Example

The <DateTime> component formats date and time values according to the user's locale. Again, we see how the <DateTime> component can be used both as a child of a <T> component and as a standalone component.

import { T, DateTime } from 'gt-next';
 
export default function OrderSummary({ order }) {
  return (
    <T id="orderSummary">
      Your order was placed on <DateTime value={order.date} />
    </T>
    <DateTime>{order.date}</DateTime>
  );
}

Variable Components are essential for maintaining displaying dynamic and private content in translations.
All reformatting is done locally ensuring that no sensitive data is sent to the General Translation APIs.
Components like <Num>, <Currency>, and <DateTime> provide localization features to ensure accurate formatting whereas the <Var> component is used for general variables that do not require reformatting.

Next Steps

Explore conditional logic in Branching Components.
Learn more about formatting options for specific Variable Components in the API Reference.