Aperçu

Ce guide présente les étapes nécessaires pour migrer un projet qui utilise déjà une bibliothèque i18n vers gt-react.

Nous partagerons également quelques conseils et bonnes pratiques pour rendre la migration aussi fluide que possible.

Prérequis

• Un projet qui utilise actuellement une autre bibliothèque i18n.
• Une compréhension de base de la bibliothèque gt-react.

Pourquoi migrer ?

Il existe de nombreuses raisons de migrer votre projet vers gt-react.

En voici quelques-unes :

• Fin des fichiers JSON : Ne gérez plus jamais vos traductions dans des fichiers JSON. Tout votre contenu reste directement dans votre code, là où il a sa place.
• Traductions automatiques : Générez des traductions de haute qualité et adaptées au contexte avec notre outil CLI. Vous n’aurez plus jamais à attendre vos traductions.
• Expérimenter en dev : Expérimentez facilement vos traductions en développement grâce au rechargement à chaud.

Configuration

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>

Stratégies de migration

Option 1 : Migrer l’ensemble de votre projet

C’est l’option la plus directe, mais elle exigera aussi le plus grand nombre de modifications de code en une seule fois.

Après avoir configuré votre projet, recherchez toutes les occurrences de votre ancienne bibliothèque i18n et remplacez-les par gt-react.

Si votre application utilise des hooks React tels que useTranslation, recherchez toutes les occurrences de useTranslation dans votre codebase et remplacez-les par useGT.

Ensuite, remplacez toutes les clés de chaînes par leurs valeurs textuelles réelles.

Par exemple, si votre ancien code ressemble à ceci :

{
  "hello": {
    "description": "Bonjour, le monde !"
  }
}

export default function MyComponent() {
  const { t } = useTranslation()
  return <div>{t('hello.description')}</div>
}

Vous devrez le remplacer par :

export default function MyComponent() {
  const { t } = useGT()
  return <div>{t('Bonjour le monde !')}</div>
}
// OU
export default function MyComponent() {
  return <T>Bonjour le monde !</T>
}

Faites cela pour toutes les instances de votre ancienne bibliothèque i18n.

Option 2 : Migrer entièrement votre projet, tout en continuant d’utiliser les dictionaries de l’ancienne bibliothèque i18n

Supposons que vous souhaitiez migrer votre projet vers gt-react, mais continuer à utiliser les dictionaries de l’ancienne bibliothèque i18n et n’utiliser les fonctionnalités in-line de GT que pour le nouveau contenu.

Dans ce cas, vous pouvez procéder de manière similaire à l’option 1 :

Repérez toutes les occurrences de votre ancienne bibliothèque i18n, comme les hooks useTranslation, et remplacez-les par des hooks useTranslations.

Le hook useTranslations se comporte de façon très similaire aux hooks useTranslation, et vous pouvez l’utiliser de la même manière.

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>
}

Côté configuration, vous devrez créer un fichier dictionary.[js|ts|json] à la racine de votre projet ou dans le répertoire src. Copiez le contenu de votre ancien fichier dictionary dans ce nouveau fichier, puis passez-le au composant GTProvider.

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

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

Consultez le guide dictionaries pour en savoir plus.

Option 3 : Continuer à utiliser l’ancienne bibliothèque i18n pour l’instant et ne migrer qu’une partie de votre projet vers gt-react

Cette option est la plus flexible et demandera le moins de changements de code d’un seul coup.

Dans ce cas, vous pouvez faire quelque chose de similaire à l’option 2, mais ne migrer qu’une partie de votre projet vers gt-react.

Par exemple, vous pouvez continuer à utiliser l’ancienne bibliothèque i18n pour certains composants, et n’utiliser gt-react que pour d’autres ainsi que pour les nouveaux contenus.

Conseils pour la migration

1. Utilisez le hook useGT ou le composant <T> autant que possible

Dans la mesure du possible, nous recommandons d’utiliser le hook useGT ou le composant <T>.

Cela rendra l’édition de votre contenu beaucoup plus simple à l’avenir et rendra votre codebase bien plus lisible.

2. Utilisez le hook useTranslations pour le contenu existant

Le hook useTranslations est un excellent moyen de continuer à utiliser vos dictionaries existantes.

Nous le proposons pour faciliter la migration, mais nous ne recommandons pas de l’utiliser pour du nouveau contenu.

3. Utiliser l’IA

Si vous utilisez l’IA pour vous aider à migrer votre projet, nous mettons à disposition les fichiers LLMs.txt et LLMs-full.txt à l’adresse suivante :

• LLMs.txt
• LLMs-full.txt

Ces fichiers contiennent l’intégralité de cette documentation, afin que votre outil d’IA ait accès à toutes les informations dont il a besoin pour vous aider à migrer votre projet.