# node: Gestione degli errori e fallback
URL: https://generaltranslation.com/it/docs/node/guides/error-handling.mdx
---
title: Gestione degli errori e fallback
description: Cosa succede quando le traduzioni non sono disponibili e come gestire la situazione
---

## Comportamento di fallback predefinito

Quando una traduzione non è disponibile — perché l'impostazione regionale non è supportata, il file di traduzione manca o il CDN è irraggiungibile — `gt-node` restituisce la stringa originale nel tuo `defaultLocale`. La tua app non si blocca mai a causa di una traduzione mancante.

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

app.get('/api/greeting', async (req, res) => {
  const gt = await getGT();
  // Se la traduzione in spagnolo non è disponibile, restituisce l'originale inglese
  res.json({ message: gt('Hello, world!') });
});
```

<Callout>
  Questo fallback è automatico. Non è necessario racchiudere le chiamate di traduzione in blocchi try/catch in caso di traduzioni mancanti.
</Callout>


## Impostazioni regionali mancanti

Se arriva una richiesta per un&#39;impostazione regionale che non hai configurato in `locales`, le funzioni di traduzione usano `defaultLocale` come valore di fallback:

```js
initializeGT({
  defaultLocale: 'en',
  locales: ['en', 'es', 'fr'], // Giapponese non incluso
});

// Richiesta con Accept-Language: ja
// gt('Hello!') → restituisce 'Hello!' (fallback in inglese)
```

Per supportare una nuova impostazione regionale, aggiungila all&#39;array `locales` e rigenera le traduzioni:

```bash
npx gt translate
```


## Verificare le impostazioni regionali disponibili

Usa [`getLocales()`](/docs/node/api/get-locales) e [`getDefaultLocale()`](/docs/node/api/get-default-locale) per vedere quali impostazioni regionali sono disponibili a runtime:

```js
import { getLocales, getDefaultLocale } from 'gt-node';

app.get('/api/locales', (req, res) => {
  res.json({
    supported: getLocales(),
    default: getDefaultLocale(),
  });
});
```


## Gestire la traduzione nelle risposte API

Quando sviluppi API, potresti voler indicare esplicitamente quando il contenuto è in una lingua di fallback:

```js
import { getGT, getLocale, getDefaultLocale } from 'gt-node';

app.get('/api/greeting', async (req, res) => {
  const gt = await getGT();
  const locale = getLocale();
  const defaultLocale = getDefaultLocale();

  res.json({
    message: gt('Hello, world!'),
    locale,
    isFallback: locale !== defaultLocale,
  });
});
```


## Debug delle traduzioni

### Verifica quale impostazione regionale è attiva

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

app.use((req, res, next) => {
  console.log(`[i18n] Request locale: ${getLocale()}`);
  next();
});
```


### Verifica che le traduzioni vengano caricate

In fase di sviluppo, `gt-node` traduce on-demand tramite l&#39;API. Se sembra che manchino delle traduzioni:

1. Verifica che `GT_API_KEY` e `GT_PROJECT_ID` siano impostati
2. Verifica che l&#39;impostazione regionale sia inclusa nell&#39;array `locales`
3. Controlla se ci sono errori nei log del server

### Checklist di produzione

Prima di implementare, verifica:

* [ ] `npx gt translate` venga eseguito correttamente nel tuo script di build
* [ ] Tutte le impostazioni regionali di destinazione siano elencate in `gt.config.json`
* [ ] `GT_PROJECT_ID` sia impostato nell&#39;ambiente di produzione
* [ ] `GT_API_KEY` sia impostata nell&#39;ambiente di produzione (per `npx gt translate`)

<Callout type="warn">
  Durante lo sviluppo, le traduzioni avvengono on-demand e potrebbero essere lente. In produzione, pre-genera sempre le traduzioni con `npx gt translate` — vedi i [docs della CLI](/docs/cli/translate).
</Callout>

## Prossimi passaggi

* [Pattern per la traduzione delle stringhe](/docs/node/guides/strings) — i due approcci alla traduzione
* [Archiviazione locale delle traduzioni](/docs/node/guides/local-tx) — includi le traduzioni nel bundle per l&#39;uso offline
* [`getLocale` riferimento API](/docs/node/api/get-locale)