Introduction

Le SDK React de General Translation est une bibliothèque d’internationalisation (i18n) open source pour les applications React.

Il fournit un ensemble complet d’outils pour internationaliser votre application React de façon simple et facile à maintenir, avec une parité fonctionnelle par rapport aux autres bibliothèques i18n populaires.

Le SDK peut être utilisé de manière autonome, sans la plateforme General Translation, et se comporte de façon similaire aux autres bibliothèques i18n.

Cependant, il s’intègre aussi à notre plateforme pour offrir des fonctionnalités avancées :

• Rechargement à chaud des traductions en développement
• Traductions automatiques par IA
• Synchronisation des traductions avec la plateforme General Translation
• Intégration native avec notre CDN de traduction

Concepts

Cinq concepts principaux sont à connaître concernant le SDK.

Le composant <GTProvider>

Le composant <GTProvider> fournit à votre application le contexte de traduction, notamment la langue en cours et les traductions associées.

import { GTProvider } from 'gt-react';

function App() {
  return (
    <GTProvider>
      <div>
        {/* Contenu de votre application */}
      </div>
    </GTProvider>
  );
}

Important : Le provider doit envelopper toute votre application et être placé le plus haut possible dans l’arborescence des composants, par exemple dans votre composant App racine.

Consultez la référence de l’API de GTProvider pour en savoir plus.

Le composant <T>

Le composant <T> est la manière recommandée de traduire le contenu de votre application.

C’est un composant React qui peut envelopper n’importe quel élément JSX et rend automatiquement le contenu de l’élément dans une langue prise en charge.

Exemples

<T>
  <div>Bonjour le monde !</div>
</T>

<T>
  <div>
    <h1> Voici une image </h1>
    <img src="https://example.com/image.png" alt="Exemple" />
  </div>
</T>

<T>
  Le formatage peut être effectué facilement avec le composant `<T>`.
  <Num>{1000}</Num>
  <DateTime>{new Date()}</DateTime>
  <Currency currency="USD">{1000}</Currency>
</T>

Le composant <T> fonctionne avec des composants variables comme <Num>, <DateTime> et <Currency> pour formater dynamiquement le contenu.

Consultez le guide du composant <T> pour découvrir les différentes manières d’utiliser le composant <T>.

Le hook useGT

Le hook useGT est un hook React qui s’utilise de façon similaire au composant <T>, avec certains compromis.

Ce hook renvoie une fonction permettant de traduire des chaînes de caractères.

const t = useGT();

t('Bonjour le monde !');

Comparé au composant <T>, le hook useGT offre plus de flexibilité dans votre codebase.

Par exemple, si vous avez une structure de données complexe avec des chaînes imbriquées, il serait plus difficile d’utiliser un composant <T>.

const t = useGT();
const data = {
  title: t('Bonjour le monde !'),
  description: t('Ceci est une description'),
};

Consultez le guide sur les chaînes pour en savoir plus sur le hook useGT.

La fonction msg

La fonction msg sert à marquer pour traduction les chaînes utilisées dans plusieurs composants ou stockées dans des objets de configuration.

Elle est particulièrement utile pour le contenu mutualisé, comme les libellés de navigation, les messages de formulaire ou tout texte apparaissant à plusieurs endroits dans votre application.

// Marquer les chaînes pour la traduction
import { msg } from 'gt-react';

const navItems = [
  { label: msg('Accueil'), href: '/' },
  { label: msg('À propos'), href: '/about' },
  { label: msg('Contact'), href: '/contact' }
];

// Décoder et utiliser les chaînes marquées
import { useMessages } from 'gt-react';

function Navigation() {
  const m = useMessages();
  
  return (
    <nav>
      {navItems.map(item => (
        <a key={item.href} href={item.href}>
          {m(item.label)}
        </a>
      ))}
    </nav>
  );
}

La fonction msg encode des chaînes avec des métadonnées de traduction, et useMessages les décode.

Consultez le guide sur les chaînes partagées pour en savoir plus sur la fonction msg.

Le hook useTranslations

Le hook useTranslations est un hook React qui renvoie une fonction permettant de récupérer les traductions associées à une clé donnée.

const dictionary = {
  hello: {
    world: 'Bonjour le monde !',
  },
};

const translate = useTranslations();
translate('bonjour.monde');

Ce comportement est similaire à celui d’autres bibliothèques de traduction, comme react-i18next et next-intl.

Consultez le guide dictionaries pour en savoir plus sur le hook useTranslations.

Consultez la référence de l’API useTranslations pour plus d’informations.

Prochaines étapes

• Découvrez comment configurer votre projet React avec le SDK : Guide de démarrage rapide
• Apprenez à traduire du contenu JSX avec le composant <T> : Guide de traduction JSX
• Apprenez à traduire des chaînes avec le hook useGT : Guide de traduction des chaînes
• Découvrez les chaînes mutualisées avec la fonction msg : Guide des chaînes mutualisées