Variables

Sometimes you need to include content that shouldn't be translated but could change in your content. For example, imagine you are displaying a welcome page. You might want to address your user by their first name:

const firstname = "Alice" // or "Bob", "Charlie", etc.
return (
    <p>
        Welcome to our site, {firstname}!
    </p>
)

<Var>

In your dictionary, you can use the <Var> component to signify a variable which will be translated around.

// dictionary.js
 
import { Var } from 'gt-next' // or 'gt-react'
 
const dictionary = {
    "my_id": <>Welcome to our site, <Var name="firstname"/>!</>
}
 
export default dictionary;

<Var> takes an optional name prop which specifies the variable name. To supply a variable with t(), you can write:

const firstname = "Alice" // or "Bob", "Charlie", etc.
return t('my_id', { firstname })

The children of the <Var> component will remain untranslated and can change without forcing a retranslation. Anything you include as the children of the <Var> in the dictionary will be the default value, rendered if no value is supplied in the t() function.

// dictionary.js
 
import { Var } from 'gt-next' // or 'gt-react'
 
const dictionary = {
    "my_id": <>Welcome to our site, <Var name="firstname">valued customer!</Var>!</>
}
 
export default dictionary;

The value provided for <Var> can be anything, including additional JSX:

t("my_id", { firstname: <b>Alice</b> }) // <>Welcome to our site, <b>Alice</b>!</>

<Num>, <DateTime>, and <Currency>

Sometimes variables need to be localized in some way — for example, in US English (en-US) dates are written month first, with slashes: MM/DD/YY. In German (de) they are written day first, with periods: DD.MM.YY. In addition to <Var>, there are the specialized variable types <Num> for numbers, <DateTime> for dates, and <Currency> for currencies.

// dictionary.js
 
import { Var, Num, DateTime, Currency } from 'gt-next' // or 'gt-react'
 
const dictionary = {
    "my_id": <>Welcome to our site, <Var name="firstname">valued customer!</Var>!</>,
    "num_example": <>You have <Num/> new messages.</>,
    "datetime_example": <>Today is <DateTime/>.</>,
    "currency_example": <>This product costs <Currency/>.</>
}
 
export default dictionary;

If a an entry in the dictionary has two variables, for example:

{ 
    "two_var_example": <>The movie is called <i><Var name="movie"/></i> and a ticket costs <Currency name="price"/>.</> 
}

Then you would supply two values to t():

t('two_var_example', { movie: "Terminator 2: Judgement Day", price: 10 })

Variable names

If no name prop is provided, variable components will default to the following names:

This means that

"datetime_example": <>Today is <DateTime/>.</>

Would be supplied a variable like:

t("datetime_example", { date: new Date() })

Variable options

The specialized variables <Num>, <DateTime>, and <Currency> take an options prop, which conforms to the Intl.NumberFormatOptions (opens in a new tab) standard in the case of <Num> and <Currency>, and the Intl.DateTimeFormatOptions (opens in a new tab) standards in the case of <DateTime>.

For example:

// displays a percentage, rounded to a whole number
"num_example_two": (
    <>
        Your progress is about 
        <Num 
            name="count" 
            options={{style: "percent", maximumFractionDigits: 0}}
        />.
    </>
)

Additionally, the <Currency> component takes an optional currency prop which corresponds to an ISO-4217 (opens in a new tab) currency code. By default, the currency is USD ($).

// displays the price in euros (€), rounded to the nearest whole number
"currency_example_two": (
    <>
        This plan costs
        <Currency 
            currency="EUR"
            options={{maximumFractionDigits: 0}}
        />.
    </>
)

Variables in strings

To include a variable in a string, include the name in braces ({}). For example:

"greeting": "Welcome to our site, {firstname}!"

Then use the t() function like:

t("greeting", { firstname: "Alice" })

To include the { or } characters in a string, use the escape character ^:

"with_escaped_brace": "Many programming languages use braces like ^{ and ^}"

t("with_escaped_brace") // Does not display the ^ characters

Variable types in strings

To include types in a string variable, add the type you need after a comma, within the braces:

"example_with_currency": "This product costs {cost, currency}"

t("example_with_currency", { cost: 10 })

Variable string options

Use dictionary metadata to add advanced Intl.NumberFormatOptions and Intl.DateTimeFormat options to the variables within strings.