# gt-next: General Translation Next.js SDK: Dizionari
URL: https://generaltranslation.com/it/docs/next/guides/dictionaries.mdx
---
title: Dizionari
description: Come usare i tradizionali modelli di traduzione basati su dizionari
---

I dizionari offrono un approccio tradizionale per organizzare le traduzioni in oggetti annidati con coppie chiave-valore. Sebbene i [componenti `<T>`](/docs/next/guides/t) siano l&#39;approccio consigliato, i dizionari possono essere utili per migrare da altre librerie i18n o quando preferisci un archivio centralizzato delle traduzioni.

<Callout>
  **Raccomandazione:** Usa i [componenti `<T>`](/docs/next/guides/t) per i nuovi progetti. I dizionari sono supportati principalmente per la migrazione e la compatibilità con i flussi di lavoro di traduzione esistenti.
</Callout>

## Traduzione tramite dizionario vs traduzione dei componenti

### Pattern del dizionario

```tsx
// dictionary.ts
export default {
  greetings: {
    hello: 'Hello, world!',
    welcome: 'Welcome, {name}!'
  }
};

// Utilizzo del componente
function MyComponent() {
  const t = useTranslations();
  return <div>{t('greetings.hello')}</div>;
}
```


### Pattern del componente

```tsx
// Utilizzo diretto del componente - consigliato
function MyComponent() {
  return <T><div>Hello, world!</div></T>;
}
```


## Compromessi

### Vantaggi del dizionario

* **Archiviazione centralizzata** - Tutte le traduzioni in un unico posto
* **Standard di settore** - Un modello già familiare in altre librerie di i18n
* **Facile migrazione** - Semplice portare le traduzioni esistenti

### Svantaggi del dizionario

* **Complessità** - Richiede più set-up e configurazione
* **Manutenibilità** - Separare il contenuto dal suo utilizzo rende gli aggiornamenti più difficili
* **Debuggabilità** - È più difficile ricondurre le traduzioni ai componenti
* **Leggibilità** - Le chiavi non mostrano il contenuto reale

## Guida rapida

### Passaggio 1: Crea un dizionario

Crea un file di dizionario nella directory principale del progetto o nella directory `src`:

```ts title="dictionary.ts"
const dictionary = {
  greetings: {
    hello: 'Hello, world!',
    welcome: 'Welcome to our app!'
  },
  navigation: {
    home: 'Home',
    about: 'About',
    contact: 'Contact'
  }
};

export default dictionary;
```

Oppure usa il formato JSON:

```json title="dictionary.json"
{
  "greetings": {
    "hello": "Hello, world!",
    "welcome": "Welcome to our app!"
  },
  "navigation": {
    "home": "Home", 
    "about": "About",
    "contact": "Contact"
  }
}
```

La funzione [`withGTConfig`](/docs/next/api/config/with-gt-config) rileverà automaticamente il file del dizionario nella directory principale del progetto o nella directory `src`.


### Passaggio 2: Uso nei componenti

L&#39;hook [`useTranslations`](/docs/next/api/dictionary/use-translations) ti permette di accedere alle voci del dizionario:

#### Componenti client

```tsx
import { useTranslations } from 'gt-next';

function MyComponent() {
  const t = useTranslations();
  
  return (
    <div>
      <h1>{t('greetings.hello')}</h1>
      <p>{t('greetings.welcome')}</p>
    </div>
  );
}
```


#### Componenti server

```tsx
import { getTranslations } from 'gt-next/server';

async function MyServerComponent() {
  const d = await getTranslations();
  
  return (
    <div>
      <h1>{t('greetings.hello')}</h1>
      <p>{t('greetings.welcome')}</p>
    </div>
  );
}
```


## Uso delle variabili

Aggiungi le variabili alle voci del dizionario usando la sintassi `{variable}`:

```ts title="dictionary.ts"
const dictionary = {
  user: {
    greeting: 'Hello, {name}!',
    itemCount: 'You have {count} items',
    orderTotal: 'Total: ${amount}'
  }
};
```

```tsx
function UserDashboard() {
  const t = useTranslations();
  
  return (
    <div>
      <h1>{t('user.greeting', { name: 'Alice' })}</h1>
      <p>{t('user.itemCount', { count: 5 })}</p>
      <p>{t('user.orderTotal', { amount: 99.99 })}</p>
    </div>
  );
}
```


## Uso dei prefissi

Limita l&#39;accesso al dizionario a sezioni specifiche tramite prefissi:

```ts title="dictionary.ts"
const dictionary = {
  dashboard: {
    header: {
      welcome: 'Welcome back!',
      lastLogin: 'Last login: {date}'
    },
    stats: {
      totalUsers: 'Total Users: {count}',
      activeUsers: 'Active Users: {count}'
    }
  }
};
```

```tsx
function DashboardHeader() {
  // Il prefisso limita l'accesso a 'dashboard.header'
  const t = useTranslations('dashboard.header');
  
  return (
    <header>
      <h1>{t('welcome')}</h1> {/* -> dashboard.header.welcome */}
      <p>{t('lastLogin', { date: 'Today' })}</p> {/* -> dashboard.header.lastLogin */}
    </header>
  );
}

function DashboardStats() {
  // Prefisso diverso per la sezione stats
  const t = useTranslations('dashboard.stats');
  
  return (
    <div>
      <p>{t('totalUsers', { count: 1000 })}</p> {/* -> dashboard.stats.totalUsers */}
      <p>{t('activeUsers', { count: 150 })}</p> {/* -> dashboard.stats.activeUsers */}
    </div>
  );
}
```


## Supporto multilingue

### Traduzione automatica (consigliata)

La maggior parte degli utenti dovrebbe utilizzare [`loadTranslations`](/docs/next/api/config/load-translations) per generare automaticamente le traduzioni dal dizionario di base:

```ts title="dictionary.ts"  
const dictionary = {
  common: {
    save: 'Save',
    cancel: 'Cancel',
    delete: 'Delete'
  },
  forms: {
    required: 'This field is required',
    email: 'Please enter a valid email'
  }
};

export default dictionary;
```

Crea una funzione `loadTranslations` per caricare i file di traduzione generati:

```js title="src/loadTranslations.ts"
export default async function loadTranslations(locale) {
  const translations = await import(`../public/locales/${locale}.json`);
  return translations.default;
}
```

[`withGTConfig`](/docs/next/api/config/with-gt-config) rileva automaticamente il file `loadTranslations.[js|ts]` nella directory `src/` o nella radice del progetto.

GT genera automaticamente le traduzioni nelle altre lingue in base al dizionario di base. Esegui `npx gt translate` per generare le traduzioni per tutte le lingue configurate.


### File di traduzione gestiti manualmente (migrazione)

Per migrare da altre librerie i18n o da una gestione manuale delle traduzioni, usa [`loadDictionary`](/docs/next/api/config/load-dictionary):

```ts title="src/loadDictionary.ts"
export default async function loadDictionary(locale: string) {
  const translations = await import(`../public/locales/${locale}.json`);
  return translations.default;
}
```

Questo carica i file di traduzione JSON dalla directory `public/locales/`:

<Files>
  <Folder name="my-app" defaultOpen={true}>
    <Folder name="public" defaultOpen={true}>
      <Folder name="locales" defaultOpen={true}>
        <File name="es.json" />

        <File name="fr.json" />

        <File name="de.json" />
      </Folder>
    </Folder>

    <Folder name="src">
      <File name="loadDictionary.ts" />
    </Folder>
  </Folder>
</Files>

<Callout>
  **Scegli l&#39;approccio giusto:** usa [`loadTranslations`](/docs/next/api/config/load-translations) per i nuovi progetti con generazione automatica delle traduzioni, oppure [`loadDictionary`](/docs/next/api/config/load-dictionary) se stai migrando file di traduzione esistenti.
</Callout>


## Setup di produzione

### Processo di build

Aggiungi la traduzione al processo di build:

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


### Comportamento in sviluppo e in produzione

* **Sviluppo**: voci del dizionario tradotte on-demand con API key di sviluppo
* **Produzione**: tutte le traduzioni del dizionario vengono precompilate durante la fase di build

## Combinare con i componenti

I dizionari e i [componenti `<T>`](/docs/next/guides/t) possono essere usati insieme:

```tsx
function MixedApproach() {
  const t = useTranslations();
  
  return (
    <div>
      {/* Dizionario per cadene semplici */}
      <h1>{t('page.title')}</h1>
      
      {/* Componente `<T>` per JSX complesso */}
      <T>
        <p>This is a <strong>complex message</strong> with <a href="/link">links</a>.</p>
      </T>
      
      {/* Dizionario per le etichette del form */}
      <label>{t('forms.email')}</label>
    </div>
  );
}
```

## Passaggi successivi

<Callout>
  **Guardalo in azione:** Dai un&#39;occhiata all&#39;[app di esempio del pattern del dizionario](https://github.com/gt-examples/dictionary-pattern) per una demo funzionante — [anteprima live](https://dictionary-pattern.generaltranslation.dev).
</Callout>

* [Guida alle lingue](/docs/next/guides/languages) - Configura le lingue supportate e le impostazioni delle impostazioni regionali
* [Guida ai contenuti dinamici](/docs/next/guides/dynamic-content) - Gestisci le esigenze di traduzione a runtime
* Riferimenti API:
  * [Hook `useTranslations`](/docs/next/api/dictionary/use-translations)
  * [Funzione `getTranslations`](/docs/next/api/dictionary/get-translations)