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 recommandations pour que la migration se déroule le plus facilement 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 :

• Plus de fichiers JSON : Ne gérez plus jamais les traductions dans des fichiers JSON. Tout votre contenu reste au plus près de votre code, là où il doit être.
• Traductions automatiques : Générez des traductions de haute qualité, sensibles au contexte, avec notre outil CLI. Vous n’aurez plus jamais à attendre des traductions.
• Expérimentez en dev : Testez facilement des traductions en développement grâce au rechargement à chaud des traductions.

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 entièrement votre projet

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

Après avoir configuré votre projet, vous devrez rechercher toutes les occurrences de votre ancienne bibliothèque i18n et les remplacer 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, vous devrez remplacer toutes les clés de chaînes par leurs valeurs de chaînes effectives.

Par exemple, si votre ancien code ressemble à ceci :

{
  "hello": {
    "description": "Bonjour, 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, monde !')}</div>
}
// OR
export default function MyComponent() {
  return <T>Bonjour, monde !</T>
}

Faites cela pour toutes les occurrences 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’employer les fonctionnalités inline 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, telles que 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 transmettez‑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 modifications de code d’un seul coup.

Dans ce cas, vous pouvez procéder de manière 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 et 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 bien plus simple à l’avenir et votre codebase nettement plus lisible.

2. Utilisez le hook useTranslations pour le contenu existant

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

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 des fichiers LLMs.txt et LLMs-full.txt à l’adresse suivante :

• LLMs.txt
• LLMs-full.txt

Ces files contiennent l’intégralité du contenu de cette documentation, afin que votre outil d’IA ait accès à toutes les informations nécessaires pour vous aider à migrer votre projet.