Dashboard

Stringhe

Come internazionalizzare semplici stringhe di testo con useGT e getGT

La traduzione delle stringhe offre accesso diretto alle traduzioni del testo senza JSX, ideale per attributi, proprietà degli oggetti e valori di testo semplice. Usa useGT nei componenti sincroni e getGT nei componenti asincroni.

Uso sincrono vs asincrono

  • Componenti sincroni: hook useGT per componenti React
  • Componenti asincroni: funzione async getGT per componenti asincroni

Guida rapida

Componenti sincrone

import { useGT } from 'gt-next';

function MyComponent() {
  const t = useGT();
  return (
    <input 
      placeholder={t('Inserisci il tuo indirizzo email')}
      title={t('Campo indirizzo email')}
    />
  );
}

Componenti asincroni

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

async function MyServerComponent() {
  const t = await getGT();
  return (
    <input 
      placeholder={t('Inserisci il tuo indirizzo email')}
      title={t('Campo indirizzo email')}
    />
  );
}

Quando utilizzare la traduzione delle stringhe

La traduzione delle stringhe è ideale quando ti serve testo semplice invece del JSX:

Attributi HTML

const t = useGT();

<input 
  placeholder={t('Cerca prodotti…')}
  aria-label={t('Campo di ricerca dei prodotti')}
  title={t('Digita per cercare nel nostro catalogo')}
/>

Proprietà dell’oggetto

const t = useGT();

const user = {
  name: 'John',
  role: 'admin',
  bio: t('Sviluppatore software con 5 anni di esperienza in React'),
  status: t('Attualmente disponibile per progetti')
};

Configurazione e costanti

const t = useGT();

const navigationItems = [
  { label: t('Home'), href: '/' },
  { label: t('Prodotti'), href: '/products' },
  { label: t('Contatti'), href: '/contact' }
];

Quando usare <T> invece

Usa il componente <T> per contenuti JSX:

// ✅ Use <T> for JSX content
<T><p>Benvenuti nel <strong>nostro store</strong>!</p></T>

// ✅ Use string translation for plain text
<input placeholder={t('Cerca prodotti')} />

Uso delle variabili

Variabili di base

Sostituisci i segnaposto con valori dinamici:

const t = useGT();
const itemCount = 5;

// String with placeholder
const message = t('Hai {count} articoli nel carrello', { count: itemCount });
// Risultato: "Hai 5 articoli nel carrello"

Più variabili

const t = useGT();
const order = { id: 'ORD-123', total: 99.99, date: '2024-01-15' };

const confirmation = t(
  'Ordine {orderId} di ${total} effettuato il {date}',
  { 
    orderId: order.id, 
    total: order.total, 
    date: order.date 
  }
);

Formato dei messaggi ICU

Per una formattazione avanzata, usa la sintassi ICU:

const t = useGT();
translate('Nel carrello {count, plural, =0 {non ci sono articoli} =1 {c’è un articolo} other {ci sono {count} articoli}}', { count: 10 });

Scopri di più sull’ICU Message Format nella documentazione di Unicode.

Esempi

Campi del form

import { useGT } from 'gt-next';

function ContactForm() {
  const t = useGT();
  
  return (
    <form>
      <input 
        type="email"
        placeholder={t('Inserisci il tuo indirizzo e-mail')}
        aria-label={t('Campo di inserimento dell’e-mail')}
      />
      <textarea 
        placeholder={t('Raccontaci del tuo progetto...')}
        aria-label={t('Descrizione del progetto')}
      />
      <button type="submit">
        {t('Invia messaggio')}
      </button>
    </form>
  );
}
import { useGT } from 'gt-next';

function Navigation() {
  const t = useGT();
  
  const menuItems = [
    { label: t('Home'), href: '/', icon: 'home' },
    { label: t('Chi siamo'), href: '/about', icon: 'info' },
    { label: t('Servizi'), href: '/services', icon: 'briefcase' },
    { label: t('Contatti'), href: '/contact', icon: 'mail' }
  ];

  return (
    <nav>
      {menuItems.map((item) => (
        <a key={item.href} href={item.href} title={item.label}>
          <Icon name={item.icon} />
          {item.label}
        </a>
      ))}
    </nav>
  );
}

Factory di contenuti dinamici

// utils/productData.js
export function getProductMessages(t) {
  return {
    categories: [
      { id: 'electronics', name: t('Elettronica') },
      { id: 'clothing', name: t('Abbigliamento') },
      { id: 'books', name: t('Libri') }
    ],
    statusMessages: {
      available: t('Disponibile e pronta per la spedizione'),
      backordered: t('Attualmente in backorder - spedisce tra 2-3 settimane'),  
      discontinued: t('Questo articolo è stato dismesso')
    },
    errors: {
      notFound: t('Prodotto non trovato'),
      outOfStock: t('Spiacenti, questo articolo è attualmente esaurito')
    }
  };
}

// components/ProductCard.jsx
import { useGT } from 'gt-next';
import { getProductMessages } from '../utils/productData';

function ProductCard({ product }) {
  const t = useGT();
  const messages = getProductMessages(t);
  
  return (
    <div>
      <h3>{product.name}</h3>
      <p>{messages.statusMessages[product.status]}</p>
      <span>{messages.categories.find(c => c.id === product.categoryId)?.name}</span>
    </div>
  );
}

Server Component con metadati

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

export async function generateMetadata({ params }) {
  const t = await getGT();
  
  return {
    title: t('Catalogo prodotti - Trova quello che ti serve'),
    description: t('Sfoglia la nostra vasta selezione di prodotti di alta qualità'),
    openGraph: {
      title: t('Acquista i nostri prodotti'),
      description: t('Scopri offerte imperdibili sui prodotti più apprezzati')
    }
  };
}

export default async function ProductPage() {
  const t = await getGT();
  
  return (
    <div>
      <h1>{t('Prodotti in evidenza')}</h1>
      <p>{t('Scopri i nostri prodotti più recenti e popolari')}</p>
    </div>
  );
}

Problemi comuni

Contenuto dinamico a runtime

Le stringhe devono essere note in fase di build: non è possibile tradurre contenuti dinamici.

// ❌ Il contenuto dinamico non funzionerà
function MyComponent() {
  const [userMessage, setUserMessage] = useState('');
  const t = useGT();
  
  return <p>{t(userMessage)}</p>; // Questo non funzionerà
}

// ✅ Usa stringhe predefinite
function MyComponent() {
  const [messageType, setMessageType] = useState('welcome');
  const t = useGT();
  
  const messages = {
    welcome: t('Benvenuto nella nostra app!'),
    goodbye: t('Grazie per la visita!')
  };
  
  return <p>{messages[messageType]}</p>;
}

Violazioni delle regole degli hook

Segui le regole degli hook di React quando utilizzi useGT:

// ❌ Non chiamare gli hook in modo condizionale
function MyComponent({ showMessage }) {
  if (showMessage) {
    const t = useGT(); // Violazione delle regole degli hook
    return <p>{t('Ciao!')}</p>;
  }
  return null;
}

// ✅ Chiama sempre gli hook al livello superiore
function MyComponent({ showMessage }) {
  const t = useGT();
  
  if (showMessage) {
    return <p>{t('Ciao!')}</p>;
  }
  return null;
}

Sincrono vs Asincrono: possibili confusioni

Usa la funzione giusta per il tipo di componente:

// ❌ Errato: useGT in un componente asincrono
export default async function AsyncComponent() {
  const t = useGT(); // Non funzionerà
  return <p>{t('Ciao')}</p>;
}

// ✅ Corretto: getGT in un componente asincrono  
export default async function AsyncComponent() {
  const t = await getGT();
  return <p>{t('Ciao')}</p>;
}

// ✅ Corretto: useGT in un componente sincrono
export default function SyncComponent() {
  const t = useGT();
  return <p>{t('Ciao')}</p>;
}

Per contenuti realmente dinamici che richiedono una traduzione a runtime, consulta la Guida ai contenuti dinamici.

Prossimi passaggi

Come valuti questa guida?

In questa pagina

Uso sincrono vs asincrono
Guida rapida
Componenti sincrone
Componenti asincroni
Quando utilizzare la traduzione delle stringhe
Attributi HTML
Proprietà dell’oggetto
Configurazione e costanti
Quando usare <T> invece
Uso delle variabili
Variabili di base
Più variabili
Formato dei messaggi ICU
Esempi
Campi del form
Menu di navigazione
Factory di contenuti dinamici
Server Component con metadati
Problemi comuni
Contenuto dinamico a runtime
Violazioni delle regole degli hook
Sincrono vs Asincrono: possibili confusioni
Prossimi passaggi
Stringhe