# node: getTranslations
URL: https://generaltranslation.com/en-US/docs/node/api/get-translations.mdx
---
title: getTranslations
description: API reference for the getTranslations dictionary translation function
---

## Overview

`getTranslations` returns a translation function `t` that resolves entries from a [dictionary](/docs/next/guides/dictionaries).
Use it to translate pre-defined strings by their dictionary key.

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

const t = await getTranslations();
t('greeting.hello'); // "Hello!"
```

<Callout>
  **Request context required:**
  `getTranslations` must be called within a [`withGT`](/docs/node/api/with-gt) callback so it knows which locale to use.
</Callout>

## Reference

### Parameters

None.

### Returns

A promise that resolves to a translation function `t`:

```ts
Promise<TFunctionType>
```

The `t` function accepts a dictionary key and optional interpolation options:

| Name | Type | Description |
| --- | --- | --- |
| `id` | `string` | The dot-separated path to a dictionary entry. |
| `options?` | `DictionaryTranslationOptions` | Variables for interpolation. |

**Returns:** `string` — the translated (or source-language fallback) text.

If the key does not exist in the source dictionary, `t()` throws an error.
If the key exists in the source dictionary but has no translation for the current locale, `t()` returns the source text.

### `t.obj()`

Returns an entire subtree of the dictionary as an object instead of a single string.

```ts
t.obj(id: string): DictionaryObjectTranslation
```

| Name | Type | Description |
| --- | --- | --- |
| `id` | `string` | The dot-separated path to a dictionary subtree. |

**Returns:** A nested object matching the dictionary structure, with translated values where available and source-language fallbacks elsewhere.

---

## Setup

### Automatic (recommended)

Create a `dictionary.json` file in your project root:

```json title="dictionary.json"
{
  "greeting": {
    "hello": "Hello!"
  },
  "user": {
    "welcome": "Welcome, {name}!"
  }
}
```

When you run `npx gtx translate`, the CLI automatically detects `dictionary.json` and translates it for your configured locales.

Then initialize GT with the dictionary:

```ts
import { initializeGT } from 'gt-node';
import dictionary from './dictionary.json';

initializeGT({
  dictionary,
  defaultLocale: 'en-US',
  locales: ['en-US', 'es', 'fr'],
});
```

### Custom dictionary loader

If you manage your own translated dictionaries, pass a `loadDictionary` function to [`initializeGT`](/docs/node/api/initialize-gt):

```ts
import { initializeGT } from 'gt-node';
import dictionary from './dictionary.json';

initializeGT({
  dictionary,
  loadDictionary: async (locale) => {
    const dict = await import(`./locales/${locale}.json`);
    return dict.default;
  },
});
```

Translations loaded via `loadDictionary` take precedence over GT-generated translations.

---

## Examples

### Basic usage

```ts
import { getTranslations } from 'gt-node';

const t = await getTranslations();
t('greeting.hello'); // "Hello!"
```

### Variable interpolation

```ts
const t = await getTranslations();
t('user.welcome', { name: 'Alice' }); // "Welcome, Alice!"
```

### Object lookup with `t.obj()`

```ts
const t = await getTranslations();

const errors = t.obj('errors');
// { notFound: "Page not found", unauthorized: "Access denied" }
```

---

## Notes

- `getTranslations` is the dictionary-based counterpart to [`getMessages`](/docs/node/api/get-messages), which is used for inline `msg()` strings.
- For the Next.js equivalent, see [`getTranslations` in gt-next](/docs/next/api/dictionary/get-translations).