Vue d’ensemble

gt-react exporte désormais une fonction t() pour la traduction synchrone de chaînes au niveau des modules dans le navigateur.

Jusqu’à présent, la traduction de chaînes dans gt-react nécessitait des hooks basés sur le contexte React, comme useGT. Les hooks fonctionnent bien à l’intérieur des composants, mais ils ne couvrent pas un cas courant : traduire des chaînes au niveau des modules — en dehors des composants React, avant le rendu, dans de simples fichiers utilitaires.

t() comble cette lacune. C’est une fonction synchrone que vous pouvez appeler n’importe où dans le code exécuté dans le navigateur :

import { t } from 'gt-react/browser';

const greeting = t('Hello, world!');

Aucun hook, aucun async, aucune arborescence de composants n’est obligatoire.

Pourquoi cette approche

L’idée centrale de cette PR est d’expérimenter une alternative à l’approche de traduction basée sur le contexte React. En fonctionnant en dehors de l’arborescence des composants, t() permet des modèles plus intéressants — notamment la traduction au niveau du module. Les chaînes peuvent être traduites là où elles sont définies, et non là où elles sont affichées.

Cela implique des compromis :

• Côté client uniquement. t() fonctionne uniquement dans les applications React côté client. Il s’appuie sur l’exécution des modules dans le navigateur pour charger les traductions avant le rendu de l’app.
• Rechargement complet de la page pour changer de langue. Comme les traductions sont résolues au chargement du module, changer de locale nécessite de réexécuter les modules — ce qui implique un rechargement complet de la page. Il n’est pas possible de changer de langue à chaud en cours de session.

En revanche, l’expérience développeur s’en trouve nettement améliorée. Plus besoin d’envelopper les chaînes dans des hooks, ni de gérer de logique au niveau des composants, ni de limites asynchrones — juste un appel de fonction.

Les approches existantes basées sur le contexte React (useGT, <T>, etc.) ne vont pas disparaître. C’est une option supplémentaire pour les projets où ces compromis ont du sens.

Comment ça fonctionne

t() résout les traductions de manière synchrone à partir des traductions chargées à l’avance. Ces traductions sont fournies par bootstrap(), une nouvelle fonction d’initialisation asynchrone qui charge toutes les traductions de la locale actuelle avant le rendu de votre application.

Vous devez modifier le point d’entrée de votre application pour exécuter bootstrap() en premier. Il s’agit généralement de main.tsx, mais vous pouvez modifier le point d’entrée dans votre index.html.

// bootstrap.tsx (nouveau point d'entrée)
import gtConfig from '../gt.config.json';
import { bootstrap } from 'gt-react/browser';

async function getTranslations(locale: string) {
  return import(`./_gt/${locale}.json`);
}

await bootstrap({
  ...gtConfig,
  getTranslations,
});

await import('./main.tsx');

La fonction getTranslations est asynchrone : elle charge d’abord les traductions, puis l’application React est importée et exécutée. C’est ainsi que t() est accessible au niveau du module : lorsqu’un module appelle t(), les traductions sont déjà disponibles.

Cela fonctionne uniquement avec des applications React côté client, car le code exécuté au niveau du module est relancé lorsque vous le chargez dans le navigateur. Et comme nous devons relancer les modules pour mettre à jour le contenu traduit, changer de locale nécessite un rechargement complet de la page.

Variables

t() prend en charge l’interpolation de variables, comme msg() :

import { t } from 'gt-react/browser';

t('Hello, {name}!', { name: 'John' });  // → "Hola, John!"

Où cela s’inscrit

t() est le bon choix lorsque vous avez besoin de traductions en dehors de l’arborescence des composants React — fichiers de constantes, fonctions utilitaires, objets de configuration, définitions de routes, ou tout ce qui s’exécute au niveau du module dans le navigateur.

Gardez à l’esprit :

• Cela ne s’intègre pas encore au reste du système gt-react. Vous devez effectuer l’initialisation décrite ci-dessus. Il s’agit d’une approche autonome.
• Côté client uniquement. La traduction côté serveur doit utiliser des hooks basés sur le contexte React, comme useGT.

Notes de conception

t() est uniquement disponible dans le navigateur. S’il est appelé sur le serveur (où window n’est pas défini), il consigne un avertissement et se rabat sur la chaîne source. C’est intentionnel — la traduction côté serveur doit utiliser les hooks existants de React via le hook basé sur le contexte React.

Référence de l’API

Consultez la référence complète de l’API t() pour les paramètres, les types de retour et les détails de configuration.