# node: tx
URL: https://generaltranslation.com/en-US/docs/node/api/strings/tx.mdx
---
title: tx
description: API reference for the tx runtime string translation function
---

## Overview

The `tx` function translates strings at runtime. Unlike [`getGT`](/docs/node/api/get-gt), which resolves build-time translations, `tx` sends content for on-demand translation — so it can translate strings that are only known at runtime.

```js
import { tx } from 'gt-node';

const translated = await tx('Hello, world!');
```

<Callout>
  **Runtime Translation:**
  `tx` performs translation on demand, which means there is a network request and a delay compared to build-time translation.
  Use [`getGT`](/docs/node/api/get-gt) for strings known at build time, and `tx` only when the content is dynamic or not known ahead of time.
</Callout>

## Reference

### Parameters

| Name | Type | Description |
| ---- | ---- | ----------- |
| `content` | `string` | The string to translate. |
| `options?` | [`RuntimeTranslationOptions`](/docs/next/api/types/runtime-translation-options) | Options to customize translation behavior. |

### Returns

`Promise<string>` — the translated string, or the original string if no translation is needed.

---

## Examples

### Basic usage

```js title="handler.js"
import { withGT, tx } from 'gt-node';

function handleRequest(locale) {
  return withGT(locale, async () => {
    return await tx('Processing complete');
  });
}
```

### With variables

Use `{variableName}` syntax in the string and pass values in the options object:

```js title="handler.js"
import { withGT, tx } from 'gt-node';

function handleStatus(locale, status) {
  return withGT(locale, async () => {
    return await tx('Current status: {status}', { status });
  });
}
```

### With context

Add `$context` to help disambiguate translations:

```js title="handler.js"
const translated = await tx('Spring', {
  $context: 'the season, not a coil',
});
```

### Specifying a locale

Override the locale set by [`withGT`](/docs/node/api/with-gt):

```js title="handler.js"
const translated = await tx('Hello, world!', { $locale: 'fr' });
```

---

## Notes

- `tx` is async and returns a promise. Always `await` the result.
- Translations happen at runtime via network request, so there is a delay compared to build-time translations.
- Use `tx` for content that is only known at runtime (e.g., user-generated content, dynamic data). For static strings, prefer [`getGT`](/docs/node/api/get-gt) or [`msg`](/docs/node/api/strings/msg) / [`getMessages`](/docs/node/api/get-messages).

## Next steps

- See [`getGT`](/docs/node/api/get-gt) for build-time string translation.
- See [`RuntimeTranslationOptions`](/docs/next/api/types/runtime-translation-options) for customizing translation behavior.
- See [String Translation Patterns](/docs/node/guides/strings) for a comparison of all translation approaches.