# gt-node: General Translation Node.js SDK: Quickstart
URL: https://generaltranslation.com/en-US/docs/node/quickstart.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: Install the General Translation gt-node library and translate your first Node.js service.

`gt-node` translates strings in Node.js servers and services. You initialize it once, bind the locale for each incoming request, and translate strings in your handlers.

Use `gt-node` for backend services such as Express or Fastify APIs. For React apps use [`gt-react`](/docs/react/react-quickstart); for Next.js use [`gt-next`](/docs/react/nextjs-quickstart).

*Note: `gt-node` requires Node.js 18 or later. Per-request locale binding uses `AsyncLocalStorage` from `node:async_hooks`.*

## What gt-node does [#what-it-does]

`gt-node` gives you:

- **String translation** with [`getGT`](/docs/node/reference/functions/get-gt), for handler-local strings.
- **Registered messages** with [`msg`](/docs/node/reference/functions/msg) and [`getMessages`](/docs/node/reference/functions/get-messages), for shared constants and errors.
- **Runtime translation** with [`tx`](/docs/node/reference/functions/tx), for dynamic content.
- **Per-request locale** binding with [`withGT`](/docs/node/reference/functions/with-gt), plus helpers to detect the request locale.

## Quickstart [#quickstart]
Install the library, initialize it, bind a locale per request, and translate a string.

### 1. Install `gt-node`

Install `gt-node` and Express as dependencies and the [`gt` CLI](/docs/cli/quickstart) as a dev dependency.

<Tabs items={['npm', 'yarn', 'bun', 'pnpm']}>
  <Tab value="npm">
    ```bash
    npm install gt-node express && npm install gt --save-dev
    ```
  </Tab>

  <Tab value="yarn">
    ```bash
    yarn add gt-node express && yarn add --dev gt
    ```
  </Tab>

  <Tab value="bun">
    ```bash
    bun add gt-node express && bun add --dev gt
    ```
  </Tab>

  <Tab value="pnpm">
    ```bash
    pnpm add gt-node express && pnpm add --save-dev gt
    ```
  </Tab>
</Tabs>

*Note: The server code below uses ES module `import` syntax. Set `"type": "module"` in your `package.json` so Node.js can run it.*

### 2. Initialize the library

Make your project ID and development API key available to the Node.js process:

```bash
export GT_PROJECT_ID="your-project-id"
export GT_DEV_API_KEY="gtx-dev-..."
```

Call [`initializeGT`](/docs/node/reference/functions/initialize-gt) once at startup, before handling requests. Pass your locales directly. When credential fields are omitted, `gt-node` reads `GT_PROJECT_ID`, `GT_API_KEY`, and `GT_DEV_API_KEY` from the environment; it does not read `gt.config.json` automatically.

```ts title="server.js"
import { initializeGT } from 'gt-node';

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

### 3. Bind the request locale

Wrap each request in [`withGT`](/docs/node/reference/functions/with-gt) so translation functions know the target locale. Use [`getRequestLocale`](/docs/node/reference/functions/get-request-locale) to detect it from the `Accept-Language` header.

```js title="server.js"
import express from 'express';
import { withGT, getRequestLocale } from 'gt-node';

const app = express();
app.use((req, res, next) => withGT(getRequestLocale(req), () => next()));
```

### 4. Translate a string

Inside a handler, await [`getGT`](/docs/node/reference/functions/get-gt) to get a translation function for the request's locale, then translate strings. Interpolate values with ICU placeholders.

```js title="server.js"
import { getGT } from 'gt-node';

app.get('/api/greeting', async (req, res) => {
  const gt = await getGT();
  res.json({ message: gt('Hello, {name}!', { name: 'Alice' }) });
});

app.listen(3000, () => console.log('Listening on http://localhost:3000'));
```

### 5. Run and verify

Combine the snippets from steps 2–4 into one `server.js` file, then start the server. Before you generate translations, the handler returns your source string, which confirms the service is wired up correctly.

```bash
node server.js
```

In another terminal, send a request:

```bash
curl http://localhost:3000/api/greeting
```

```json title="Output"
{"message":"Hello, Alice!"}
```

### 6. Generate translations

Run the CLI before you deploy to production so translations are available at runtime.

```bash
npx gt translate
```

*Note: [`gt translate`](/docs/cli/reference/commands/translate) reads a `gt.config.json` and requires a project ID and API key. Run [`npx gt init`](/docs/cli/reference/commands/init) first to create them.*

(See [Translating strings](/docs/node/guides/translating-strings) for when to use [`getGT`](/docs/node/reference/functions/get-gt), [`msg`](/docs/node/reference/functions/msg), and [`tx`](/docs/node/reference/functions/tx), and [Configuring gt-node](/docs/node/guides/configuring) for credentials and delivery).

## Next steps

- /docs/node/guides/translating-strings
- /docs/node/guides/detecting-locale
- /docs/node/guides/configuring
- /docs/node/guides/storing-translations

## Sitemap

See the full [sitemap](https://generaltranslation.com/sitemap.md) for all pages.