# node: Guida rapida a Node.js
URL: https://generaltranslation.com/it/docs/node/tutorials/quickstart.mdx
---
title: Guida rapida a Node.js
description: Aggiungi più lingue al tuo server Node.js in meno di 10 minuti
---

Al termine di questa guida, il tuo server Node.js risponderà con contenuti tradotti in base alla lingua della richiesta, utilizzando stringhe inline o registrate in precedenza.

**Prerequisiti:**

* Un server Node.js (Express, Fastify o simili)
* Node.js 18+

<Callout type="info">
  **Vuoi un Setup automatico?** Esegui `npx gt@latest` per configurare tutto con la [procedura guidata di Setup](/docs/cli/init). Questa guida tratta il Setup manuale.
</Callout>

***

## Passaggio 1: Installa i pacchetti

`gt-node` è la libreria che gestisce le traduzioni sul server. `gt` è lo strumento CLI che prepara le traduzioni per l&#39;ambiente di produzione.

<Tabs items={['npm', 'yarn', 'bun', 'pnpm']}>
  <Tab value="npm">
    ```bash
    npm i gt-node
    npm i -D gt
    ```
  </Tab>

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

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

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

***

## Passaggio 2: Crea un file di configurazione delle traduzioni

Crea un file **`gt.config.json`** nella directory principale del progetto. Questo indica alla libreria quali lingue supporta il progetto:

```json title="gt.config.json"
{
  "defaultLocale": "en",
  "locales": ["es", "fr", "ja"]
}
```

* **`defaultLocale`** — la lingua in cui sono scritte le stringhe del tuo server.
* **`locales`** — le lingue in cui vuoi tradurre. Scegline una dall&#39;[elenco delle impostazioni regionali supportate](/docs/platform/supported-locales).

***


## Passaggio 3: Inizializza General Translation

Chiama **`initializeGT`** una sola volta all&#39;inizio del file di ingresso del server, prima di usare qualsiasi funzione di traduzione:

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

initializeGT({
  defaultLocale: 'en',
  locales: ['en', 'es', 'fr', 'ja'],
  projectId: process.env.GT_PROJECT_ID,
});
```

In questo modo la libreria viene configurata con le lingue supportate e le credenziali del progetto.

***


## Passaggio 4: Imposta il contesto dell&#39;impostazione regionale per ogni richiesta

Ogni richiesta deve sapere quale lingua usare. Usa **`withGT`** per avvolgere gli handler delle richieste: usa l&#39;archiviazione locale asincrona, quindi le funzioni di traduzione selezionano automaticamente l&#39;impostazione regionale corretta:

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

app.use((req, res, next) => {
  const locale = req.headers['accept-language']?.split(',')[0] || 'en';
  withGT(locale, () => next());
});
```

***


## Passaggio 5: Traduci le stringhe inline

Per tradurre le stringhe direttamente all&#39;interno degli handler delle richieste, usa **`getGT`**:

```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, world!'),
    welcome: gt('Welcome, {name}!', { name: 'Alice' }),
  });
});
```

`getGT` restituisce una funzione di traduzione associata all’impostazione regionale della richiesta corrente.

***


## Passaggio 6: Preregistra le stringhe costanti (facoltativo)

Per le stringhe definite fuori dagli handler di richiesta — come messaggi di errore, etichette di enum o costanti — usa **`msg`** per registrarle a livello di modulo, quindi **`getMessages`** per risolvere le traduzioni a runtime:

```js title="messages.js"
import { msg } from 'gt-node';

export const GREETING = msg('Hello, world!');
export const WELCOME = msg('Welcome, {name}!');
export const NOT_FOUND = msg('Resource not found.');
```

```js title="handler.js"
import { getMessages } from 'gt-node';
import { GREETING, WELCOME, NOT_FOUND } from './messages.js';

app.get('/api/status', async (req, res) => {
  const m = await getMessages();
  res.json({
    greeting: m(GREETING),
    welcome: m(WELCOME, { name: 'Alice' }),
  });
});

app.use(async (req, res) => {
  const m = await getMessages();
  res.status(404).json({ error: m(NOT_FOUND) });
});
```

Questo approccio è utile quando le stesse stringhe vengono usate in più handler.

***


## Passaggio 7: Configura le variabili d&#39;ambiente (facoltativo)

Per vedere le traduzioni durante lo sviluppo, ti servono le chiavi API di General Translation. Queste abilitano la **traduzione su richiesta**: il server traduce i contenuti in tempo reale mentre sviluppi.

Crea un file **`.env`**:

```bash title=".env"
GT_API_KEY="your-api-key"
GT_PROJECT_ID="your-project-id"
```

Ottieni le tue chiavi gratuite su [dash.generaltranslation.com](https://dash.generaltranslation.com/signup) oppure esegui:

```bash
npx gt auth
```

<Callout type="warn">
  Non esporre mai `GT_API_KEY` pubblicamente e non salvarla nel controllo del codice sorgente.
</Callout>

<Accordions>
  <Accordion title="Posso usare gt-node senza chiavi API?">
    Sì. Senza chiavi API, `gt-node` funziona come una normale libreria i18n. Non avrai la traduzione su richiesta in fase di sviluppo, ma potrai comunque:

    * Fornire manualmente i tuoi file di traduzione
    * Usare tutte le funzioni di traduzione (`getGT`, `msg`, `getMessages`, ecc.)
    * Eseguire `npx gt generate` per creare modelli di file di traduzione, quindi tradurli autonomamente
  </Accordion>
</Accordions>

***


## Passaggio 8: Verificalo in azione

Avvia il server e fai delle prove con diversi header `Accept-Language`:

```bash
# Predefinito (inglese)
curl http://localhost:3000/api/greeting

# Spagnolo
curl -H "Accept-Language: es" http://localhost:3000/api/greeting

# Francese
curl -H "Accept-Language: fr" http://localhost:3000/api/greeting
```

Dovresti vedere risposte tradotte in ciascuna lingua.

<Callout type="info">
  In fase di sviluppo, le traduzioni avvengono su richiesta — la prima volta che viene richiesta una nuova lingua potresti notare un breve ritardo. In produzione, le traduzioni sono generate in anticipo e si caricano istantaneamente.
</Callout>

***


## Passaggio 9: Esempio completo

Ecco un server Express completo con tutti gli elementi riuniti:

```js title="server.js"
import express from 'express';
import { initializeGT, withGT, getGT, msg, getMessages } from 'gt-node';

// Inizializza GT prima di tutto il resto
initializeGT({
  defaultLocale: 'en',
  locales: ['en', 'es', 'fr', 'ja'],
  projectId: process.env.GT_PROJECT_ID,
});

// Pre-registra le stringhe costanti
const NOT_FOUND = msg('Resource not found.');

const app = express();

// Imposta il contesto dell'impostazione regionale per ogni richiesta
app.use((req, res, next) => {
  const locale = req.headers['accept-language']?.split(',')[0] || 'en';
  withGT(locale, () => next());
});

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

// Traduzione dei messaggi pre-registrati
app.use(async (req, res) => {
  const m = await getMessages();
  res.status(404).json({ error: m(NOT_FOUND) });
});

app.listen(3000, () => console.log('Server running on port 3000'));
```

***


## Passaggio 10: Esegui il deployment in produzione

In produzione, le traduzioni vengono generate in anticipo durante la fase di build (senza chiamate API in tempo reale). Aggiungi il comando `translate` allo script di build:

```json title="package.json"
{
  "scripts": {
    "build": "npx gt translate && <YOUR_BUILD_COMMAND>"
  }
}
```

Configura le variabili d&#39;ambiente di **produzione** nel tuo provider di hosting:

```bash
GT_PROJECT_ID=your-project-id
GT_API_KEY=gtx-api-your-production-key
```

<Callout type="warn">
  Non esporre mai pubblicamente la tua `GT_API_KEY`.
</Callout>

Tutto qui: il tuo server ora è multilingue. 🎉

***


## Risoluzione dei problemi

<Accordions>
  <Accordion title="Le traduzioni sono lente in fase di sviluppo">
    È normale. In fase di sviluppo, le traduzioni avvengono su richiesta (i contenuti vengono tradotti in tempo reale tramite l&#39;API). Questo ritardo **non si verifica in produzione** — tutte le traduzioni vengono generate in anticipo da `npx gt translate`.
  </Accordion>

  <Accordion title="Alcune traduzioni sono imprecise">
    Un testo ambiguo può portare a traduzioni imprecise. Per esempio, &quot;apple&quot; potrebbe indicare il frutto o l&#39;azienda. Aggiungi l&#39;opzione `$context` per chiarire:

    ```js
    gt('Apple', { $context: 'the technology company' });
    ```

    Sia `getGT()` sia `msg()` supportano l&#39;opzione `$context`.
  </Accordion>
</Accordions>

***

## Passaggi successivi

* [**`initializeGT`**](/docs/node/api/initialize-gt) — Opzioni di configurazione complete
* [**`withGT`**](/docs/node/api/with-gt) — Contesto dell&#39;impostazione regionale nelle richieste
* [**`getGT`**](/docs/node/api/get-gt) — Traduzione inline di stringhe
* [**`msg` &amp; `getMessages`**](/docs/node/api/get-messages) — Traduzione dei messaggi pre-registrati
* [**CLI**](/docs/cli/translate) — Riferimento per il flusso di lavoro di traduzione