tx()

Overview

The tx() function is a server-side function for translating strings.

await tx('Hello, world!', {id: 'exampleId'}); // returns 'Hola, mundo!'

String translation only (no jsx).
Server side components only.
High performance caching.
Support variable injections.
Static content only, dynamically constructed strings are invalid.

You can leverage caching by passing an id parameter to tx(). This helps optimize translation performance by reusing previously fetched translations.

Reference

Parameters

Prop	Type	Default
`content`	`string`	-
`options?`	`Object`	`{}`
`options.id?`	`string`	-
`options.locale?`	`string`	-
`options.context?`	`string`	-
`options.variables?`	`Record<string, any>`	-
`options.variableOptions?`	`Record<string, Intl.NumberFormatOptions\|Intl.DateTimeFormatOptions>`	-

Name	Description
`content`	The string that needs to be translated.
`options`	Translation options to customize the behavior of `tx()`.
`options.id`	A unique identifier for the content, used for caching and fetching translations.
`options.locale`	The target locale for translation. Defaults to the current locale if not provided.
`options.context`	Additional context for the translation process, which may influence the translation's outcome.
`options.variables`	A map of variables to inject into the translated content.
`options.variableOptions`	Options for formatting numbers and dates using `Intl.NumberFormat` or `Intl.DateTimeFormat`.

Returns

A promise that resolves to a string containing the translated content, or the original content if no translation is needed.

Example

Basic Usage

You can use tx() to translate strings.

src/components/translateGreeting.jsx

import { tx } from 'gt-next/server';
 
export default async function translateGreeting() {
    return await tx("Hello, world!", { id: 'translateGreeting' }); 
}

Specifying Translation Options

You can customize the translation by providing a target locale and a context to be considered when translating.

TranslateWithOptions.jsx

import { tx } from 'gt-next/server';
 
export default async function TranslateWithOptions() {
    return await tx("Hello, world!", {
        id: 'TranslateWithOptions',
        locale: 'es', 
        context: 'Translate informally'
    });
}

Using Variables

In order to pass values to your string, you must (1) assign an identifier and (2) reference the identifier in the variables field.

In this example, we have created a variable with the identifier {price}. We have assigned it a value price: 29.99, and given it options price: { style: 'currency', currency: 'MXN' }.

translateWithVariables.js

import { tx } from 'gt-next/server';
 
export default async function translateWithVariables() {
    return await tx("The price is {price}", {
        id: 'translateWithVariables',
        locale: 'es-MX', 
        variables: { price: 29.99 },  
        variableOptions: { price: { style: 'currency', currency: 'MXN' } }  
    });
}

Notes

The tx() function is asynchronous and must be awaited.
It is designed exclusively for server-side usage and cannot be used in client-side components.
Supports advanced features like variable injection rendering for flexible localization workflows.
It is strongly recommended that you take advantage of caching by passing a unique id parameter.

Next Steps

Learn more about using variables in translations with Variable Components.
For JSX translations, see useElement(), useGT() or getGT().
Explore locale management with i18n Configuration.

tx()

On this page