Panoramica

Questa guida illustra i passaggi necessari per migrare a gt-react un progetto che utilizza già una libreria i18n.

Forniremo anche suggerimenti e consigli per rendere la migrazione il più fluida possibile.

Prerequisiti

• Un progetto che utilizza un'altra libreria i18n.
• Conoscenze di base sulla libreria gt-react.

Perché migrare?

Ci sono molti motivi per cui potresti voler migrare il tuo progetto a gt-react.

Eccone alcuni:

• Addio ai file JSON: Non dovrai più gestire le traduzioni in file JSON. Tutti i contenuti vivono accanto al tuo codice, dove è più naturale.
• Traduzioni automatiche: Genera traduzioni di alta qualità e sensibili al contesto con il nostro CLI. Non dovrai più attendere le traduzioni.
• Sperimenta in locale: Sperimenta facilmente le traduzioni in sviluppo grazie all’hot-reloading.

Configurazione

npm i gt-react
npm i gtx-cli

yarn add gt-react
yarn add --dev gtx-cli

bun add gt-react
bun add --dev gtx-cli

pnpm add gt-react
pnpm add --save-dev gtx-cli

{
  "defaultLocale": "en",
  "locales": ["en", "fr", "es"]
}

import { GTProvider } from 'gt-react'
import config from './gt.config.json'

<GTProvider {...config}>
  <App />
</GTProvider>

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-react.

Se la tua app utilizza hook di React come useTranslation, cerca tutte le occorrenze di useTranslation nel codice e sostituiscile con useGT.

Poi dovrai sostituire tutte le chiavi delle stringhe con i rispettivi valori testuali.

Ad 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

Mettiamo che tu voglia migrare il progetto a gt-react, ma desideri continuare a usare i dizionari della vecchia libreria i18n e usare le funzionalità inline di GT solo per i nuovi contenuti.

In questo caso, puoi fare qualcosa di simile all’opzione 1:

Individua tutte le istanze della vecchia libreria i18n, come gli hook useTranslation, e sostituiscile con gli hook useTranslations.

L’hook useTranslations si comporta in modo molto simile a useTranslation e lo puoi usare 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-react'
export default function MyComponent() {
  const t = useTranslations()
  return <div>{t('hello.description')}</div>
}

Per la configurazione, dovrai creare un file dictionary.[js|ts|json] nella root del progetto o nella directory src. Copia il contenuto del vecchio file di dizionario in questo nuovo file, quindi passalo al componente GTProvider.

import { GTProvider } from 'gt-react'
import dictionary from './dictionary.json'
import config from './gt.config.json'

<GTProvider {...config} dictionary={dictionary}>
  <App />
</GTProvider>

Consulta la guida dictionaries per ulteriori dettagli.

Opzione 3: Continua a usare per ora la vecchia libreria i18n e migra solo una parte del progetto a gt-react

Questa è l’opzione più flessibile e richiede il minor numero di modifiche al codice in un’unica tornata.

In questo caso, puoi fare qualcosa di simile all’Opzione 2, ma migrare solo una parte del progetto a gt-react.

Per esempio, puoi continuare a utilizzare la vecchia libreria i18n per alcuni componenti e usare gt-react solo per altri e per i nuovi contenuti.

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à l’editing dei contenuti molto più semplice in futuro e il tuo codebase molto più leggibile.

2. Usa l’hook useTranslations per i contenuti esistenti

L’hook useTranslations è un ottimo modo per continuare a utilizzare i dizionari che già hai.

Lo mettiamo a disposizione per semplificare la migrazione, ma non ne consigliamo l’uso per i nuovi contenuti.

3. Uso dell’IA

Se stai usando l’IA per migrare il tuo progetto, mettiamo a disposizione i file LLMs.txt e LLMs-full.txt ai seguenti indirizzi:

• LLMs.txt
• LLMs-full.txt

Questi file contengono l’intero contenuto di questa documentazione, così il tuo strumento di IA avrà accesso a tutte le informazioni necessarie per aiutarti a migrare il progetto.