Migrazione
Scopri come migrare un progetto a gt-next
Panoramica
Questa guida illustra i passaggi necessari per migrare a gt-next un progetto che utilizza già una libreria i18n.
Forniremo anche suggerimenti e consigli per rendere la migrazione il più semplice possibile.
Prerequisiti
- Un progetto che utilizza attualmente un’altra libreria i18n.
- Una conoscenza di base della libreria
gt-next.
Perché migrare?
Ci sono molti motivi per cui potresti voler migrare il tuo progetto a gt-next.
Eccone alcuni:
- Addio file JSON: Non dovrai più gestire le traduzioni nei file JSON. Tutti i contenuti restano accanto al tuo codice, dove hanno senso.
- Traduzioni automatiche: Genera traduzioni di alta qualità e sensibili al contesto con il nostro strumento CLI. Non dovrai più aspettare le traduzioni.
- Sperimenta in dev: Sperimenta facilmente le traduzioni in sviluppo grazie all’hot reloading delle traduzioni.
Configurazione
Installa gt-next e lo strumento da riga di comando gtx-cli.
npm i gt-next gtx-cliyarn add gt-next
yarn add --dev gtx-clibun add gt-next
bun add --dev gtx-clipnpm add gt-next
pnpm add --save-dev gtx-cliCrea un file gt.config.json nella root del progetto con una proprietà defaultLocale e un array locales.
{
"defaultLocale": "en",
"locales": ["en", "fr", "es"]
}Quindi aggiungi il componente <GTProvider> al layout principale della tua app.
import { GTProvider } from 'gt-next'
export default function RootLayout({ children }) {
return (
<html>
<body>
<GTProvider>
{children}
</GTProvider>
</body>
</html>
)
}Poi aggiungi withGTConfig al file next.config.js.
import withGTConfig from 'gt-next/config'
const nextConfig = {
// Le tue opzioni next.config.ts
}
export default withGTConfig(nextConfig, {
// La tua configurazione di GT
})Per istruzioni più dettagliate, consulta la guida rapida.
A questo punto hai 3 opzioni:
- Migrare completamente l’intero progetto a
gt-nexte rimuovere la vecchia libreria i18n. - Migrare completamente il progetto, ma continuare a usare i dizionari della vecchia libreria i18n.
- Continuare a usare per ora la vecchia libreria i18n e migrare solo una parte del progetto a
gt-next.
Per maggiori dettagli su ciascuna opzione, vedi la sezione strategie di migrazione.
Strategie di migrazione
Opzione 1: Migrare completamente l’intero progetto
Questa opzione è la più semplice, ma richiederà anche il maggior numero di modifiche al codice in un’unica soluzione.
Dopo aver configurato il progetto, dovrai cercare tutte le occorrenze della vecchia libreria i18n e sostituirle con gt-next.
Se la tua app utilizza hook di React come useTranslations, cerca tutte le occorrenze di useTranslations nel tuo codebase e sostituiscile con useGT.
Quindi dovrai sostituire tutte le chiavi delle stringhe con i rispettivi valori testuali.
Per esempio, se il tuo vecchio codice è simile a questo:
{
"hello": {
"description": "Ciao, mondo!"
}
}export default function MyComponent() {
const { t } = useTranslation()
return <div>{t('hello.description')}</div>
}Dovrai sostituirlo con:
export default function MyComponent() {
const t = useGT()
return <div>{t('Ciao, mondo!')}</div>
}
// OPPURE
export default function MyComponent() {
return <T>Ciao, mondo!</T>
}Esegui questa operazione per tutte le istanze della tua vecchia libreria i18n.
Opzione 2: Migra completamente il progetto, ma continua a usare i dizionari della vecchia libreria i18n
Supponiamo che tu voglia migrare il progetto a gt-next, ma preferisca continuare a usare i dizionari della vecchia libreria i18n
e utilizzare le funzionalità inline di GT solo per i nuovi contenuti.
In questo caso, puoi procedere in modo simile all’opzione 1:
Individua tutte le occorrenze della tua vecchia libreria i18n, come gli hook useTranslations, e sostituiscile con gli hook useTranslations di gt-next.
L’hook useTranslations si comporta in modo molto simile agli hook useTranslations delle altre librerie i18n e puoi usarlo allo stesso modo.
import { useTranslation } from 'react-i18next'
export default function MyComponent() {
const { t } = useTranslation()
return <div>{t('hello.description')}</div>
}import { useTranslations } from 'gt-next'
export default function MyComponent() {
const t = useTranslations()
return <div>{t('hello.description')}</div>
}Per la configurazione, crea un file dictionary.[js|ts|json] nella root del progetto o nella directory src.
Copia il contenuto del tuo vecchio dizionario in questo nuovo file.
La funzione di inizializzazione withGTConfig in next.config.js rileverà automaticamente il file del dizionario nella root del progetto o nella directory src.
Consulta la guida dictionaries per maggiori dettagli.
Opzione 3: Continua a usare la vecchia libreria i18n per ora e migra solo una parte del tuo progetto a gt-next
Questa opzione è la più flessibile e richiede il minor numero di modifiche al codice in un’unica soluzione.
In questo caso puoi fare qualcosa di simile all’opzione 2, ma migrare solo una parte del progetto a gt-next.
Ad esempio, puoi continuare a usare la vecchia libreria i18n per alcuni componenti e usare gt-next solo per altri e per i nuovi contenuti.
Questa opzione non è consigliata, perché dovrai gestire due librerie i18n diverse nel progetto, cosa che può essere complessa e causare bug.
Consigli per la migrazione
1. Usa l’hook useGT o il componente <T> il più possibile
Quando possibile, consigliamo di usare l’hook useGT o il componente <T>.
Questo renderà molto più semplice, in futuro, modificare i contenuti e migliorerà la leggibilità della codebase.
2. Usa l’hook useTranslations per i contenuti esistenti
L’hook useTranslations è un ottimo modo per continuare a usare i tuoi dizionari esistenti.
Lo offriamo per semplificare la migrazione, ma non consigliamo di usarlo per nuovi contenuti.
3. Uso dell’IA
Se stai usando l’IA per aiutarti a migrare il tuo progetto, mettiamo a disposizione i file LLMs.txt e LLMs-full.txt qui:
Come valuti questa guida?