Dashboard

Dizionari

Come usare i tradizionali modelli 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 migrare 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, {name}!'
  }
};

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

Pattern dei componenti

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

Trade-off

Vantaggi del dizionario

  • Archiviazione centralizzata - Tutte le traduzioni in un unico luogo
  • Standard di settore - Modello familiare rispetto ad altre librerie i18n
  • Compatibile con le migrazioni - Facile portare le traduzioni esistenti

Svantaggi dei dizionari

  • Complessità - Richiede più configurazione e setup
  • Manutenibilità - Separare il contenuto dall’uso rende gli aggiornamenti più difficili
  • Debuggabilità - Più difficile risalire dalle traduzioni ai componenti
  • Leggibilità - Le chiavi non mostrano il contenuto reale

Guida rapida

Passaggio 1: Creare 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": "Benvenuto nella nostra applicazione!"
  },
  "navigation": {
    "home": "Home", 
    "about": "Chi siamo",
    "contact": "Contatti"
  }
}

Quindi lo passi al componente <GTProvider>:

index.js
import dictionary from "./dictionary.js";
import config from "./gt.config.json";

createRoot(document.getElementById("root")!).render(
  <StrictMode>
    <GTProvider {...config} dictionary={dictionary}>
      <App />
    </GTProvider>
  </StrictMode>
);

Passaggio 2: Utilizzo nei componenti

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

import { useTranslations } from 'gt-react';

function MyComponent() {
  const d = useTranslations();
  
  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 tramite prefissi:

dictionary.ts
const dictionary = {
  dashboard: {
    header: {
      welcome: 'Bentornato!',
      lastLogin: 'Ultimo accesso: {date}'
    },
    stats: {
      totalUsers: 'Totale utenti: {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 delle 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)

Per la maggior parte degli utenti è consigliabile usare loadTranslations per generare automaticamente le traduzioni dal dizionario di base:

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

export default dictionary;

Quindi crea una funzione loadTranslations per caricare i file di traduzione generati:

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

Passalo a <GTProvider>:

src/index.tsx
import loadTranslations from './loadTranslations';
import dictionary from './dictionary';

createRoot(document.getElementById("root")!).render(
  <StrictMode>
    <GTProvider 
      {...config} 
      dictionary={dictionary}
      loadTranslations={loadTranslations}
    >
      <App />
    </GTProvider>
  </StrictMode>
);

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

File di traduzione manuale (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/:

es.json
fr.json
de.json

Scegli l’approccio giusto: usa loadTranslations per i nuovi progetti con generazione automatica delle traduzioni, oppure loadDictionary quando esegui la migrazione di 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 && <...IL_TUO_COMANDO_DI_BUILD...>"
  }
}

Comportamento in sviluppo vs produzione

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

In combinazione con i componenti

I dizionari e i componenti <T> possono funzionare insieme:

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

Prossimi passaggi

Come valuti questa guida?

In questa pagina

Dizionario vs traduzione dei componenti
Pattern del dizionario
Pattern dei componenti
Trade-off
Vantaggi del dizionario
Svantaggi dei dizionari
Guida rapida
Passaggio 1: Creare il dizionario
Passaggio 2: Utilizzo nei componenti
Uso delle variabili
Uso dei prefissi
Supporto per più lingue
Traduzione automatica (consigliata)
File di traduzione manuale (migrazione)
Configurazione per la produzione
Processo di build
Comportamento in sviluppo vs produzione
In combinazione con i componenti
Prossimi passaggi
Dizionari