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 maintenable, avec une parité fonctionnelle par rapport à d’autres bibliothèques i18n populaires.

Le SDK peut être utilisé de manière autonome, sans la plateforme General Translation, et se comporte de manière 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 (réseau de distribution de contenu)

Concepts

Il y a cinq concepts essentiels à comprendre concernant le SDK.

Le composant <GTProvider>

Le composant <GTProvider> fournit le contexte de traduction à votre application, y compris la langue courante 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é aussi haut que possible dans l’arborescence des composants, par exemple dans votre composant App à la racine.

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

Le composant <T>

Le composant <T> est la méthode recommandée pour traduire le contenu de votre application.

C’est un composant React qui peut envelopper n’importe quel élément JSX et qui restituera 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 le formatage dynamique du contenu.

Consultez le guide du composant <T> pour découvrir les différentes façons d’utiliser le composant <T>.

Le hook useGT

Le hook useGT est un hook React qui peut s’utiliser de manière similaire au composant <T>, avec certains compromis.

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

const t = useGT();

t('Bonjour, monde !');

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

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

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

Consultez le guide strings 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 partagé, comme les libellés de navigation, les messages de formulaire ou tout texte apparaissant à plusieurs endroits dans votre application.

// Marquer les chaînes de caractères 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 shared strings 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 d’une clé donnée.

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

const translate = useTranslations();
translate('hello.world');

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 : Démarrage rapide
• Découvrez comment traduire du contenu JSX avec le composant <T> : Guide de traduction JSX
• Découvrez comment traduire des chaînes avec le hook useGT : Guide de traduction des chaînes
• Découvrez comment utiliser les chaînes partagées avec la fonction msg : Guide des chaînes partagées