Vue d’ensemble

gt-react exporte désormais une fonction t() pour traduire des chaînes de manière synchrone au niveau du module dans le navigateur.

Jusqu’à présent, la traduction de chaînes dans gt-react nécessitait des hooks s’appuyant 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 du module — 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, aucune opération asynchrone, aucune arborescence des composants requise.

Pourquoi cette approche

L'idée au cœur de cette PR est d'expérimenter une approche qui s'éloigne de la traduction via le contexte React. En fonctionnant en dehors de l'arborescence des composants, t() permet des schémas plus intéressants — en particulier, 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'application.
• Rechargement complet de la page pour changer de langue. Comme les traductions sont résolues au chargement du module, changer de paramètre régional 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 contrepartie, l'expérience développeur s'améliore nettement. Plus besoin d'envelopper les chaînes dans des hooks, plus de câblage au niveau des composants, plus de limites asynchrones — juste un appel de fonction.

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

Fonctionnement

t() récupère les traductions de manière synchrone parmi celles qui ont été chargées au préalable. Ces traductions sont chargées par bootstrap(), une nouvelle fonction d’initialisation asynchrone qui charge toutes les traductions pour le paramètre régional actif 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 changer 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 loadTranslations(locale: string) {
  return (await import(`./_gt/${locale}.json`)).default;
}

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

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

La fonction loadTranslations est asynchrone : elle charge d’abord les traductions, puis l’application React est importée et exécutée. C’est ce qui permet à t() d’être disponible au niveau du module : lorsqu’un module appelle t(), les traductions sont déjà chargées.

Cela fonctionne uniquement dans les applications React côté client, car le code au niveau du module est réexécuté lorsque vous le chargez dans le navigateur. Et comme il faut réexécuter les modules pour mettre à jour le contenu traduit, changer de paramètre régional nécessite un rechargement complet de la page.

Variables

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

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

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

Où cela s’insère

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 routeur, 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() fonctionne uniquement dans le navigateur. S’il est appelé sur le server (où window n’est pas défini), il affiche un avertissement et revient à la chaîne source. C’est intentionnel : la traduction côté serveur doit utiliser les hooks existants basés 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.