Faites traduire le contenu de votre application React en quelques minutes.

Prérequis : React, connaissances de base en JavaScript

Installation

Installez les paquets gt-react et gtx-cli :

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

Configuration

GTProvider

Le composant GTProvider fournit le contexte de traduction à vos composants React. Il gère l’état du locale, les traductions, et permet d’utiliser les hooks useGT et useTranslations.

Ajoutez GTProvider à votre composant App racine :

import { GTProvider } from 'gt-react';

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

Créez un fichier gt.config.json à la racine de votre projet :

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

Personnalisez les locales de votre projet. Consultez les locales prises en charge pour connaître les options.

Variables d’environnement

Ajoutez ceci à votre fichier d’environnement pour activer le rechargement à chaud en développement :

VITE_GT_API_KEY="your-dev-api-key"
VITE_GT_PROJECT_ID="your-project-id"

REACT_APP_GT_API_KEY="your-dev-api-key"
REACT_APP_GT_PROJECT_ID="your-project-id"

GATSBY_GT_API_KEY="your-dev-api-key"
GATSBY_GT_PROJECT_ID="your-project-id"

REDWOOD_ENV_GT_API_KEY="your-dev-api-key"
REDWOOD_ENV_GT_PROJECT_ID="your-project-id"

Obtenez des API Keys gratuites sur dash.generaltranslation.com ou exécutez :

npx gtx-cli auth

Utilisation

Vous pouvez maintenant commencer à internationaliser votre contenu. Deux approches principales s’offrent à vous :

Contenu JSX avec <T>

Encapsulez des éléments JSX pour les traduire à l’aide du composant <T> :

import { T } from 'gt-react';

function Welcome() {
  return (
    <T>
      <h1>Bienvenue dans notre application !</h1>
    </T>
  );
}

Pour les contenus dynamiques, utilisez des composants de variables comme <Var> :

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

function Greeting({ user }) {
  return (
    <T>
      <p>Bonjour, <Var>{user.name}</Var> !</p>
    </T>
  );
}

Consultez le guide sur l’utilisation du composant <T> pour en savoir plus.

Chaînes simples avec useGT

Pour les attributs, les libellés et le texte en clair avec le hook useGT :

import { useGT } from 'gt-react';

function ContactForm() {
  const t = useGT();
  
  return (
    <input 
      placeholder={t('Saisissez votre e-mail')}
      aria-label={t('Champ de saisie pour l'e-mail')}
    />
  );
}

Consultez le guide sur la traduction de chaînes pour en savoir plus.

Tester votre application

Testez vos traductions en changeant de langue :

1. Ajoutez un menu déroulant de sélection de locale avec <LocaleSelector> :

   import { LocaleSelector } from 'gt-react';
   
   function App() {
     return <LocaleSelector />;
   }

2. Lancez votre serveur de développement :

   npmyarnbunpnpm

   npm run dev 

   yarn run dev 

   bun run dev 

   pnpm run dev 

3. Ouvrez localhost:3000 et changez la langue via le menu déroulant de sélection de locale.

En développement, les traductions sont effectuées à la demande (un bref temps de chargement peut apparaître). En production, tout est pré‑traduit.

Dépannage

Déploiement

En production, vous devez prétraduire le contenu, car la traduction à l’exécution est désactivée (sauf pour les fonctions <Tx> et tx).

1. Obtenez une clé d’API de production sur dash.generaltranslation.com.

   Les clés de production commencent par gtx-api- (à la différence des clés de développement qui commencent par gtx-dev-). En savoir plus sur les différences entre environnements.

2. Ajoutez ces variables à votre environnement CI/CD :

   GT_PROJECT_ID=your-project-id
   GT_API_KEY=gtx-api-your-production-key

   Ne préfixez jamais les clés de production avec le préfixe des variables publiques de votre framework (comme VITE_, REACT_APP_, etc.) : elles doivent rester côté serveur uniquement.

3. Exécutez la commande de traduction pour traduire votre contenu :

   npx gtx-cli translate

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

   Consultez le guide de référence de l’outil CLI pour plus d’informations.

4. Mettez à jour votre script de build pour lancer la traduction avant la construction :

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

Prochaines étapes

• Guide du composant <T> - Analyse approfondie du composant <T> et de la traduction JSX
• Guide de traduction de chaînes - Utiliser useGT pour traduire des chaînes
• Composants de variables - Gérer du contenu dynamique avec <Var>, <Num>, etc.