Variable Components

Overview

Variable Components in gt-next allow you to insert dynamic or private content into translations. When combined with dictionaries, these components enable flexible and secure translations for content that includes user-specific or localized dynamic data.

This guide will show you how to use variable components like <Var>, <Num>, <Currency>, and <DateTime> within dictionaries.

Why Use Variable Components with Dictionaries?

Using variable components with dictionaries allows you to:

• Insert Dynamic Content: Include variables like user names, numbers, dates, or currencies in your translations.
• Secure Sensitive Data: Ensure private information stays on the server.
• Leverage Localization: Format numbers, dates, and currencies based on the user's locale.

This approach combines the scalability of dictionaries with the flexibility of variable components.

Adding Variable Components to Dictionaries

You can use variable components inside dictionary templates by including them as part of your dictionary entries. These components work seamlessly with both string and JSX content.

Example: Adding Variables to a Dictionary

In this example, we can see how to add variables to a dictionary using variable components.

import { Var, Num, Currency, DateTime } from 'gt-next';
 
const dictionary = {
  greetings: {
    // Includes a variable for the user's name
    hello: <>Hello, <Var name="username" />!</>,
    // You can also provide a fallback value
    hello2: <>Hello, <Var name="username">Alice</Var>!</>,
  },
  cart: {
    // Includes a dynamic number
    totalItems: <>You have <Num name="totalItems" /> items in your cart.</>,
    // Formats currency dynamically
    totalPrice: <>Your total is <Currency currency="USD" name="totalPrice" />.</>,
    // Formats date dynamically
    orderDate: <>Your order was placed on <DateTime name="orderDate" />.</>,
  },
};
export default dictionary;

Accessing Variable Templates

Variable Components in Template Dictionaries require you to pass dynamic data when fetching the translation. This is done through the options parameter in methods like useGT() or getGT().

Example: Client-Side Usage with useGT()

import { useGT } from 'gt-next/client';
 
export default function UserGreeting({ user }) {
  const t = useGT();
 
  return (
    <div>
        {t('greetings.hello', { username: user.name })} {/* Inserts the user's name */}
    </div>
  );
}

Example: Server-Side Usage with getGT()

import { getGT } from 'gt-next/server';
 
export default async function handler(req, res) {
  const t = await getGT();
  const user = { name: 'Bob' }; // Example user data
 
  res.send(
    t('greetings.hello', { username: user.name }) // Inserts the user's name
  );
}

Best Practices

Use Meaningful Variable Names

When defining variables in your dictionary, use descriptive names that indicate their purpose (e.g., username, orderDate).

Avoid Overloading Entries

Keep dictionary entries concise. Avoid combining too many variables or complex JSX structures in a single entry.

Notes

• Variable Components ensure that sensitive and dynamic content is rendered locally.
• Combine Variable Components with Branching Components for more advanced logic.
• Use the options parameter in useGT() or getGT() to pass dynamic data when accessing dictionary entries.

Next Steps

• Explore how to use Branching Components for conditional logic in translations.
• Learn more about Template Dictionary Design Pattern.
• Review the API Reference for Variable Components.