Démarrage rapide

Aperçu

Ce guide de démarrage rapide vous accompagnera dans l'internationalisation de votre application React avec gt-react.

À la fin de ce guide, vous aurez une application React entièrement internationalisée.

Dans ce guide, nous couvrirons les points suivants :

Installation

Configuration

Utilisation

Test de votre application

Déploiement

Prérequis

Un projet React utilisant un framework pris en charge (Next.js, Vite, etc.)
Connaissances de base de React et JavaScript

Installation

Installez les packages gt-react et gtx-cli :

npm i gt-react
npm i --save-dev 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

Configuration automatique : Nous avons un assistant de configuration expérimental qui peut vous aider à configurer votre projet avec gt-react.

Essayez-le en exécutant npx gtx-cli@latest. Vous devrez toujours internationaliser manuellement les chaînes de caractères, mais cela vous aidera à commencer.

Consultez le guide de référence de l'Assistant de configuration pour plus d'informations.

Alternativement, si vous souhaitez que votre outil d'IA comme Claude Code, Cursor, ou Windsurf configure automatiquement votre projet, vous pouvez utiliser notre serveur mcp.

Configuration

`GTProvider`

Le cœur de gt-react est le composant GTProvider.

Il est responsable de :

Gérer la langue actuelle de l'utilisateur
Fournir les traductions pertinentes à votre application
Fournir le contexte aux hooks pour accéder aux traductions
Fournir le contexte aux hooks pour changer la langue de l'utilisateur

Tout d'abord, ajoutez le composant GTProvider à votre application. Il doit être placé aussi haut que possible dans l'arborescence de vos composants.

src/App.tsx

import { GTProvider } from 'gt-react';

export default function App() {
  return (
    <GTProvider>
      <App />
    </GTProvider>
  );
}

Ensuite, créez un fichier gt.config.json à la racine de votre projet. Ce fichier est utilisé pour configurer à la fois l'outil gtx-cli et la bibliothèque gt-react.

gt.config.json

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

Vous devez personnaliser les champs defaultLocale et locales pour correspondre à votre projet. Consultez la liste des langues prises en charge pour plus d'informations.

Enfin, transmettez le fichier gt.config.json dans les props du provider.

import gtConfig from './gt.config.json';

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

Transmettre le fichier gt.config.json permet d'assurer la cohérence de la configuration dans toute votre application et avec l'outil CLI.

Vous pouvez également spécifier chaque prop individuellement dans le composant GTProvider.

<GTProvider
  defaultLocale="en"
  locales={["fr", "es"]}
>

Variables d'environnement

Définissez les variables d'environnement suivantes :

VITE_GT_API_KEY="" # Votre clé API développeur General Translation
VITE_GT_PROJECT_ID="" # L'identifiant de votre projet General Translation

GATSBY_GT_API_KEY="" # Votre clé API développeur General Translation
GATSBY_GT_PROJECT_ID="" # L'identifiant de votre projet General Translation

REDWOOD_ENV_GT_API_KEY="" # Votre clé API développeur General Translation
REDWOOD_ENV_PROJECT_ID="" # L'identifiant de votre projet General Translation

NEXT_PUBLIC_GT_API_KEY="" # Votre clé API développeur General Translation
NEXT_PUBLIC_GT_PROJECT_ID="" # L'identifiant de votre projet General Translation

REACT_APP_GT_API_KEY="" # Votre clé API développeur General Translation
REACT_APP_GT_PROJECT_ID="" # L'identifiant de votre projet General Translation

De nombreux frameworks React ont chacun une manière unique d'exporter les variables d'environnement vers le client. En environnement de développement, GT_API_KEY et GT_PROJECT_ID doivent être exportées vers le client.

Nous avons déjà ajouté la prise en charge de quelques bibliothèques, mais n'hésitez pas à nous signaler si votre framework ne figure pas dans la liste en créant une issue sur notre dépôt GitHub.

Assurez-vous que votre variable de clé API n'est définie que dans votre environnement de développement ! Elle ne doit pas être définie en production.

Vous pouvez obtenir gratuitement une clé API et un identifiant de projet en créant un compte General Translation.

Après avoir créé un compte, rendez-vous sur la page Development API Keys pour obtenir votre clé API de développement et l'identifiant de votre projet.

Vous pouvez également utiliser la commande de l'outil CLI npx gtx-cli auth pour générer une clé API et un identifiant de projet pour votre projet, qui seront enregistrés dans votre fichier .env.local.

Utilisation

Super ! Si vous avez suivi les étapes ci-dessus, votre projet React est maintenant configuré pour utiliser gt-react.

L'étape suivante consiste à internationaliser votre contenu.
Ici, nous allons donner un bref aperçu des différentes façons de traduire le contenu dans votre application.

Composant `<T>`

Le composant <T> est le composant principal pour traduire le contenu JSX dans votre application.

Pour l'utiliser, il suffit d'entourer le JSX que vous souhaitez traduire avec le composant <T>.

import { T } from 'gt-react';
<T>
  <div>Votre contenu</div>
</T>

Si vous avez du contenu dynamique, vous devrez utiliser les composants de variable pour passer les valeurs dynamiques.

import { T, Var } from 'gt-react';

<T>
  <div>Bonjour, <Var>{name}</Var> !</div>
</T>

Consultez le guide Traduire du JSX pour plus d'informations.

Hook `useGT`

Le hook useGT est un hook React qui retourne une fonction pouvant être utilisée pour traduire des chaînes de caractères.

import { useGT } from 'gt-react';

const translate = useGT();
translate('Hello, world!');

Consultez le guide Traduire des chaînes pour plus d'informations.

Utiliser la fonctionnalité de traduction avec rechargement à chaud sera utile pour internationaliser votre application.

Pour l'activer, assurez-vous d'avoir défini les variables d'environnement GT_API_KEY et GT_PROJECT_ID dans votre environnement de développement.

Tester Votre Application

Félicitations ! 🥳 Si vous avez suivi les étapes ci-dessus, votre application est maintenant multilingue ! Voyons-la en action.

Voir Votre Application dans une Langue Différente

Ajoutez le composant <LocaleSelector> à votre application. Cela vous permettra de sélectionner une langue différente pour votre application.

Astuce : Vous pouvez également ignorer cette étape et simplement changer votre langue dans les paramètres de votre navigateur.

Démarrez votre application React en mode développement.

npm run dev

yarn run dev

bun run dev

pnpm run dev

Ouvrez votre application dans votre navigateur préféré (généralement à http://localhost:3000).

Dépannage

Déploiement

Parfait ! Si vous êtes satisfait de vos traductions et de la fonctionnalité de votre application, vous pouvez maintenant déployer votre application.

Le comportement de gt-react en production est légèrement différent du développement. Plus précisément, aucune traduction ne sera effectuée à l'exécution.

Cela signifie que vous devrez traduire votre contenu avant de déployer votre application, dans le processus de construction.

Heureusement, l'outil gtx-cli dispose d'une commande translate qui peut être utilisée pour traduire automatiquement votre contenu.

Tout d'abord, vous devrez obtenir une clé API de Production depuis la plateforme General Translation.

Veuillez noter que cette clé est différente de votre clé API de Développement, et commence par gtx-api-, au lieu de gtx-dev-.

Lisez à propos de la différence entre les clés de Développement et de Production ici.

Ajoutez cette variable d'environnement à votre pipeline CI/CD.

GT_PROJECT_ID=<your-project-id>
GT_API_KEY=<your-production-api-key>

Assurez-vous que GT_API_KEY n'est PAS préfixée avec NEXT_PUBLIC_ ou VITE_, selon votre framework !

Si c'est le cas, vous risquez d'exposer votre clé API au public.

Exécutez la commande translate pour traduire votre contenu.

npx gtx-cli translate

Vous pouvez configurer le comportement de la commande translate avec le fichier gt.config.json.

Consultez le guide de référence de l'Outil CLI pour plus d'informations.

Ajoutez la commande translate à votre processus de construction.

package.json

{
  "scripts": {
    "build": "npx gtx-cli translate && <...YOUR_BUILD_COMMAND...>"
  }
}

Résumé

Dans ce guide, nous avons couvert comment configurer votre projet React avec gt-react
Nous avons brièvement couvert les différentes façons de traduire le contenu dans votre application.
Nous avons également couvert comment déployer votre application après avoir internationalisé votre contenu.

Prochaines étapes

Découvrez comment traduire du contenu JSX avec le composant <T> : Traduire du JSX
Découvrez comment traduire des chaînes de caractères avec le hook useGT : Traduire des chaînes
Apprenez à utiliser les traductions locales : Traductions locales

Démarrage rapide

Et si je ne veux pas utiliser la plateforme General Translation ?

La langue de mon application ne change pas, même si j'ai changé la langue de mon navigateur.

Pourquoi les nouvelles langues prennent-elles beaucoup de temps à charger ?

Pourquoi certaines choses se traduisent et d'autres non ?

Pourquoi certaines traductions sont-elles inexactes ?

Et si je n'utilise pas la plateforme General Translation ?

Sur cette page