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

Prérequis : React, notions de base en JavaScript

Installation

Installez les packages 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 de la locale, les traductions et permet d’utiliser les hooks useGT et useTranslations.

Ajoutez le GTProvider au composant racine de votre application :

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 ce qui suit à 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 vos 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>

Enveloppez 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 le contenu dynamique, utilisez des composants 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 brut 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 e-mail')}
    />
  );
}

Consultez le guide sur la traduction des 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 langue à l'aide de <LocaleSelector> :

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

2. Démarrez votre serveur de développement :

   npmyarnbunpnpm

   npm run dev 

   yarn run dev 

   bun run dev 

   pnpm run dev 

3. Accédez à localhost:3000 et changez de langue via le menu déroulant.

En développement, les traductions se font à la demande (un bref 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- (contrairement aux clés de développement qui commencent par gtx-dev-). En savoir plus sur les différences d’environnement.

2. Ajoutez-la à 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 de variable publique de votre framework (comme VITE_, REACT_APP_, etc.) — elles doivent rester exclusivement côté serveur.

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

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

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

Prochaines étapes

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