Panoramica
Panoramica dell’SDK Next.js di General Translation
Introduzione
Il General Translation Next.js SDK è una libreria open source per l’internazionalizzazione (i18n) delle applicazioni Next.js.
Offre un set completo di strumenti per internazionalizzare la tua applicazione Next.js in modo semplice e facile da mantenere, con funzionalità alla pari delle altre librerie i18n più diffuse. Basato sul React SDK, aggiunge funzionalità specifiche per Next.js.
L’SDK può essere usato in modo autonomo, senza la piattaforma General Translation, e si comporta in modo simile ad altre librerie i18n.
Inoltre si integra con la nostra piattaforma per funzionalità avanzate:
- Hot reload delle traduzioni in sviluppo
- Traduzioni automatiche con AI
- Sincronizzazione delle traduzioni con la piattaforma General Translation
- Integrazione nativa con il nostro CDN di traduzione
- Traduzione on‑demand dei componenti React in produzione (lato server)
Concetti
Ci sono 6 concetti principali da conoscere sull’SDK.
Inizializzazione con withGTConfig
Il componente <GTProvider>
Il componente <T>
L’hook useGT
La funzione msg per le stringhe condivise
(Opzionale) L’hook useTranslations
Inizializzazione con withGTConfig
La funzione withGTConfig inizializza l’SDK nella tua applicazione Next.js.
Aggiungila al file next.config.[js|ts] per configurare l’SDK:
import { withGTConfig } from 'gt-next/config';
const nextConfig = {
// Opzioni per il tuo next.config.ts
};
export default withGTConfig(nextConfig, {
// Configurazione GT
});Consulta la documentazione di riferimento dell’API withGTConfig per ulteriori informazioni.
Il componente <GTProvider>
Il componente <GTProvider> fornisce il contesto di traduzione all’applicazione, inclusi la lingua corrente e le relative traduzioni.
import { GTProvider } from 'gt-next';
export default function RootLayout({ children }) {
return (
<html>
<body>
<GTProvider>
{children}
</GTProvider>
</body>
</html>
);
}Importante: Il provider dovrebbe avvolgere l’intera applicazione ed essere posizionato il più in alto possibile nell’albero dei componenti, ad esempio nel layout radice.
Il provider è necessario solo per le funzionalità lato client. Le applicazioni esclusivamente lato server non ne hanno bisogno, ma può comunque essere incluso.
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ò avvolgere 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 si può effettuare facilmente con il componente `<T>`.
<Num>{1000}</Num>
<DateTime>{new Date()}</DateTime>
<Currency currency="USD">{1000}</Currency>
</T>Il componente <T> funziona con componenti variabili 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 utilizzato in modo analogo al componente <T>, con alcuni compromessi.
L’hook restituisce una funzione che può essere usata per tradurre le stringhe.
const t = useGT();
t('Ciao, mondo!');Rispetto al componente <T>, l’hook useGT offre maggiore flessibilità nella tua codebase.
Ad esempio, se hai una struttura dati complessa con stringhe annidate, l’utilizzo di un componente <T> risulterebbe più complicato.
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 etichette di navigazione, messaggi dei form o qualsiasi testo che compare in più punti dell’applicazione.
// Contrassegna le stringhe per la traduzione
import { msg } from 'gt-next';
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-next';
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 (oppure getMessages per i componenti server) 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 da usare per ottenere le traduzioni di una chiave specifica.
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.
Sconsigliamo di utilizzare l'hook useTranslations nella tua applicazione. Un uso frequente dell'hook useTranslations renderà la tua codebase più difficile da mantenere
e porterà a un notevole debito tecnico.
In alternativa, consigliamo di utilizzare il componente <T> o l'hook useGT.
Se stai passando da un'altra libreria i18n, l'hook useTranslations è un sostituto plug‑and‑play e può essere utile per migrare la codebase in modo incrementale.
Consulta la guida dictionaries per saperne di più sull'hook useTranslations.
Consulta la documentazione di riferimento di useTranslations per ulteriori informazioni.
Prossimi passi
- Scopri come configurare il tuo progetto Next.js con l’SDK: Guida rapida
- Scopri come tradurre contenuti JSX con il componente
<T>: Guida alla traduzione in JSX - Scopri come tradurre le stringhe con l’hook
useGT: Guida alla traduzione delle stringhe - Scopri come utilizzare le stringhe condivise con la funzione
msg: Guida alle stringhe condivise
Come valuti questa guida?