Dashboard

Dizionari

Come utilizzare i modelli tradizionali di traduzione basati su dizionari

I dizionari offrono un approccio tradizionale per organizzare le traduzioni in oggetti nidificati con coppie chiave-valore. Sebbene i componenti <T> siano l’approccio consigliato, i dizionari possono essere utili per la migrazione da altre librerie i18n o quando si preferisce una gestione centralizzata delle traduzioni.

Raccomandazione: Usa i componenti <T> per i nuovi progetti. I dizionari sono supportati principalmente per la migrazione e la compatibilità con i flussi di lavoro di traduzione esistenti.

Dizionario vs traduzione dei componenti

Pattern del dizionario

// dictionary.ts
export default {
  greetings: {
    hello: 'Ciao, mondo!',
    welcome: 'Benvenuto/a, {name}!'
  }
};

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

Pattern del componente

// Uso diretto del componente - consigliato
function MyComponent() {
  return <T><div>Ciao, mondo!</div></T>;
}

Compromessi

Vantaggi del dizionario

  • Archivio centralizzato - Tutte le traduzioni in un unico posto
  • Standard del settore - Schema familiare di altre librerie i18n
  • Facile da migrare - Facile portare le traduzioni esistenti

Svantaggi del dizionario

  • Complessità - Richiede più configurazione e impostazioni iniziali
  • Manutenibilità - Separare il contenuto dall’uso rende gli aggiornamenti più complicati
  • Debuggabilità - È più difficile risalire dalle traduzioni ai componenti
  • Leggibilità - Le chiavi non mostrano il contenuto effettivo

Guida rapida

Passaggio 1: Crea il dizionario

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

dictionary.ts
const dictionary = {
  greetings: {
    hello: 'Ciao, mondo!',
    welcome: 'Benvenuto nella nostra app!'
  },
  navigation: {
    home: 'Home',
    about: 'Chi siamo',
    contact: 'Contatti'
  }
};

export default dictionary;

Oppure utilizza il formato JSON:

dictionary.json
{
  "greetings": {
    "hello": "Ciao, mondo!",
    "welcome": "Benvenuti nella nostra app!"
  },
  "navigation": {
    "home": "Home", 
    "about": "Chi siamo",
    "contact": "Contatti"
  }
}

La funzione withGTConfig rileverà automaticamente il file del dizionario nella radice del progetto o nella directory src.

Passaggio 2: Uso nei componenti

L’hook useTranslations consente di accedere alle voci del dizionario:

Componenti client

import { useTranslations } from 'gt-next';

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

Componenti server

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

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

Uso delle variabili

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

dictionary.ts
const dictionary = {
  user: {
    greeting: 'Ciao, {name}!',
    itemCount: 'Hai {count} articoli',
    orderTotal: 'Totale: ${amount}'
  }
};
function UserDashboard() {
  const d = useTranslations();
  
  return (
    <div>
      <h1>{d('user.greeting', { name: 'Alice' })}</h1>
      <p>{d('user.itemCount', { count: 5 })}</p>
      <p>{d('user.orderTotal', { amount: 99.99 })}</p>
    </div>
  );
}

Uso dei prefissi

Limita l’accesso al dizionario a sezioni specifiche usando i prefissi:

dictionary.ts
const dictionary = {
  dashboard: {
    header: {
      welcome: 'Bentornato!',
      lastLogin: 'Ultimo accesso: {date}'
    },
    stats: {
      totalUsers: 'Utenti totali: {count}',
      activeUsers: 'Utenti attivi: {count}'
    }
  }
};
function DashboardHeader() {
  // Il prefisso limita l’accesso a 'dashboard.header'
  const d = useTranslations('dashboard.header');
  
  return (
    <header>
      <h1>{d('welcome')}</h1> {/* -> dashboard.header.welcome */}
      <p>{d('lastLogin', { date: 'Oggi' })}</p> {/* -> dashboard.header.lastLogin */}
    </header>
  );
}

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

Supporto per più lingue

Traduzione automatica (consigliata)

La maggior parte degli utenti dovrebbe utilizzare loadTranslations per generare automaticamente le traduzioni dal dizionario base:

dictionary.ts
const dictionary = {
  common: {
    save: 'Salva',
    cancel: 'Annulla',
    delete: 'Elimina'
  },
  forms: {
    required: 'Questo campo è obbligatorio',
    email: 'Inserisci un indirizzo e-mail valido'
  }
};

export default dictionary;

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

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

withGTConfig rileva automaticamente il file loadTranslations.[js|ts] dalla directory src/ o dalla radice del progetto.

GT genera automaticamente le traduzioni per altre lingue a partire dal tuo dizionario di base. Esegui npx gtx-cli translate per generare le traduzioni per tutte le lingue configurate.

File di traduzione manuali (migrazione)

Per migrare da altre librerie i18n o gestire manualmente le traduzioni, usa loadDictionary:

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/ del tuo progetto:

es.json
fr.json
de.json

Scegli l’approccio giusto: usa loadTranslations per i nuovi progetti con generazione automatica delle traduzioni, oppure loadDictionary quando migri file di traduzione esistenti.

Configurazione per la produzione

Processo di build

Aggiungi le traduzioni alla pipeline di build:

package.json
{
  "scripts": {
    "build": "npx gtx-cli translate && <...YOUR_BUILD_COMMAND...>"
  }
}

Comportamento in sviluppo vs produzione

  • Sviluppo: Voci del dizionario tradotte on demand con la chiave API di sviluppo
  • Produzione: Tutte le traduzioni del dizionario pre-generate durante la fase di build

Uso insieme ai componenti

I dizionari e i <T> components possono essere usati insieme:

function MixedApproach() {
  const d = useTranslations();
  
  return (
    <div>
      {/* Dizionario per stringhe semplici */}
      <h1>{d('page.title')}</h1>
      
      {/* Componente T per JSX complesso */}
      <T>
        <p>Questo è un <strong>messaggio complesso</strong> con dei <a href="/link">link</a>.</p>
      </T>
      
      {/* Dizionario per le etichette dei form */}
      <label>{d('forms.email')}</label>
    </div>
  );
}

Prossimi passi

Come valuti questa guida?

In questa pagina

Dizionario vs traduzione dei componenti
Pattern del dizionario
Pattern del componente
Compromessi
Vantaggi del dizionario
Svantaggi del dizionario
Guida rapida
Passaggio 1: Crea il dizionario
Passaggio 2: Uso nei componenti
Componenti client
Componenti server
Uso delle variabili
Uso dei prefissi
Supporto per più lingue
Traduzione automatica (consigliata)
File di traduzione manuali (migrazione)
Configurazione per la produzione
Processo di build
Comportamento in sviluppo vs produzione
Uso insieme ai componenti
Prossimi passi
Dizionari