Introduzione

Il General Translation React SDK è una libreria open source per l’internazionalizzazione (i18n) delle applicazioni React.

Offre un set completo di strumenti per internazionalizzare le applicazioni React in modo semplice e facile da mantenere, con funzionalità alla pari delle altre librerie i18n più diffuse.

L’SDK può essere usato in modo indipendente, senza la piattaforma General Translation, e si comporta in modo simile alle altre librerie i18n.

Inoltre, si integra con la nostra piattaforma per funzionalità avanzate:

• Hot reload delle traduzioni in ambiente di sviluppo
• Traduzioni automatiche tramite IA
• Sincronizzazione delle traduzioni con la piattaforma General Translation
• Integrazione nativa con la nostra CDN di traduzione

Concetti

Ci sono 5 concetti principali da conoscere sull’SDK.

Il componente <GTProvider>

Il componente <GTProvider> fornisce il contesto di traduzione all’applicazione, inclusa la lingua corrente e le relative traduzioni.

import { GTProvider } from 'gt-react';

function App() {
  return (
    <GTProvider>
      <div>
        {/* Contenuto dell'applicazione */}
      </div>
    </GTProvider>
  );
}

Importante: Il provider deve avvolgere l’intera applicazione e va posizionato il più in alto possibile nell’albero dei componenti, ad esempio nel componente App di root.

Consulta la documentazione dell’API di GTProvider per maggiori informazioni.

Il componente <T>

Il componente <T> è il metodo consigliato per tradurre i contenuti nella tua applicazione.

È un componente React che può racchiudere qualsiasi elemento JSX e renderizza automaticamente il contenuto dell’elemento in una lingua supportata.

Esempi

<T>
  <div>Ciao, mondo!</div>
</T>

<T>
  <div>
    <h1> Ecco un’immagine </h1>
    <img src="https://example.com/image.png" alt="Esempio" />
  </div>
</T>

<T>
  La formattazione può essere eseguita facilmente con il componente `<T>`.
  <Num>{1000}</Num>
  <DateTime>{new Date()}</DateTime>
  <Currency currency="USD">{1000}</Currency>
</T>

Il componente <T> è compatibile con componenti di variabile come <Num>, <DateTime> e <Currency> per la formattazione dinamica dei contenuti.

Consulta la guida al componente <T> per scoprire i diversi modi di utilizzare il componente <T>.

L’hook useGT

L’hook useGT è un hook React che può essere usato in modo simile al componente <T>, con alcuni compromessi.

L’hook restituisce una funzione che può essere usata per tradurre stringhe.

const t = useGT();

t('Ciao, mondo!');

Rispetto al componente <T>, l’hook useGT offre maggiore flessibilità nella tua base di codice.

Ad esempio, se hai una struttura dati complessa con stringhe annidate, un componente <T> risulterebbe più difficile da usare.

const t = useGT();
const data = {
  title: t('Ciao, mondo!'),
  description: t('Questa è una descrizione'),
};

Consulta la guida strings per saperne di più sull’hook useGT.

La funzione msg

La funzione msg viene utilizzata per contrassegnare le stringhe da tradurre usate in più componenti o archiviate in oggetti di configurazione.

È particolarmente utile per contenuti condivisi come le etichette di navigazione, i messaggi dei form o qualsiasi testo che compare in più punti della tua applicazione.

// Contrassegna le stringhe per la traduzione
import { msg } from 'gt-react';

const navItems = [
  { label: msg('Home'), href: '/' },
  { label: msg('Chi siamo'), href: '/about' },
  { label: msg('Contatti'), href: '/contact' }
];

// Decode and use the marked strings
import { useMessages } from 'gt-react';

function Navigation() {
  const m = useMessages();
  
  return (
    <nav>
      {navItems.map(item => (
        <a key={item.href} href={item.href}>
          {m(item.label)}
        </a>
      ))}
    </nav>
  );
}

La funzione msg codifica le stringhe con metadati di traduzione e useMessages le decodifica.

Consulta la guida sulle stringhe condivise per saperne di più sulla funzione msg.

L’hook useTranslations

L’hook useTranslations è un hook React che restituisce una funzione con cui recuperare le traduzioni per una determinata chiave.

const dictionary = {
  hello: {
    world: 'Ciao, mondo!',
  },
};

const translate = useTranslations();
translate('hello.world');

Questo comportamento è simile a quello di altre librerie di traduzione, come react-i18next e next-intl.

Consulta la guida dictionaries per saperne di più sull'hook useTranslations.

Consulta il riferimento API di useTranslations per ulteriori informazioni.

Prossimi passi

• Scopri come configurare il tuo progetto React con l’SDK: Avvio rapido
• Scopri come tradurre contenuti JSX con il componente <T>: Guida alla traduzione di JSX
• Scopri come tradurre le stringhe con l’hook useGT: Guida alla traduzione delle stringhe
• Scopri le stringhe condivise con la funzione msg: Guida alle stringhe condivise