Resumen

gt-react ahora exporta una función t() para traducir cadenas de forma síncrona a nivel de módulo en el navegador.

Hasta ahora, traducir cadenas en gt-react requería hooks que dependen del contexto de React, como useGT. Los hooks funcionan bien dentro de los componentes, pero no cubren un caso común: traducir cadenas a nivel de módulo — fuera de los componentes de React, antes del renderizado y en archivos de utilidades.

t() cubre ese vacío. Es una función síncrona que puedes llamar en cualquier parte del código del navegador:

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

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

Sin hooks, sin async, sin necesidad de un árbol de componentes.

Por qué este enfoque

La idea central de este PR es experimentar con un enfoque de traducción que se aleja del contexto de React. Al funcionar fuera del árbol de componentes, t() permite patrones más interesantes, especialmente la traducción a nivel de módulo. Las cadenas pueden traducirse donde se definen, no donde se renderizan.

Esto tiene sus contrapartidas:

• Solo en el cliente. t() funciona únicamente en aplicaciones React del lado del cliente. Depende de la ejecución de módulos en el navegador para cargar las traducciones antes de que se renderice la aplicación.
• Recarga completa de la página para cambiar de idioma. Como las traducciones se resuelven cuando se carga el módulo, cambiar la configuración regional requiere volver a ejecutar los módulos, es decir, recargar toda la página. No se pueden intercambiar idiomas dinámicamente a mitad de la sesión.

Por otro lado, la experiencia de desarrollo mejora mucho. No hay que envolver cadenas en hooks, ni pasar lógica por componentes, ni lidiar con límites asíncronos: solo una llamada a función.

Los enfoques existentes basados en el contexto de React (useGT, <T>, etc.) no van a desaparecer. Esta es una opción adicional para proyectos en los que estas contrapartidas tengan sentido.

Cómo funciona

t() resuelve las traducciones de forma síncrona a partir de las traducciones cargadas previamente. bootstrap() se encarga de cargarlas: es una nueva función de inicialización asíncrona que carga todas las traducciones de la configuración regional actual antes de que se renderice tu aplicación.

Debes cambiar el punto de entrada de tu aplicación para ejecutar primero bootstrap(). Normalmente será main.tsx, pero puedes cambiar el punto de entrada en tu index.html.

// bootstrap.tsx (nuevo punto de entrada)
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 función loadTranslations es asíncrona: primero carga las traducciones y luego se importa y ejecuta la aplicación de React. Así es como t() tiene acceso a nivel de módulo: cuando cualquier módulo llama a t(), las traducciones ya están disponibles.

Esto solo funciona en aplicaciones de React del lado del cliente, porque el código a nivel de módulo se vuelve a ejecutar cuando se carga en el navegador. Y como necesitamos volver a ejecutar los módulos para cambiar el contenido traducido, cambiar de configuración regional requiere una recarga completa de la página.

Variables

t() admite la interpolación de variables, igual que msg():

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

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

Dónde encaja

t() es la opción adecuada cuando necesitas traducciones fuera del árbol de componentes de React: archivos de constantes, funciones de utilidad, objetos de configuración, definiciones de rutas o cualquier cosa que se ejecute a nivel de módulo en el navegador.

Ten en cuenta:

• Esto todavía no se integra con el resto del sistema de gt-react. Debes hacer la configuración de inicialización descrita arriba. Es un enfoque independiente.
• Solo del lado del cliente. La traducción del lado del servidor debe usar hooks basados en el contexto de React, como useGT.

Notas de diseño

t() solo funciona en el navegador. Si se llama en el servidor (donde window es undefined), emite una advertencia y usa la cadena fuente. Esto es intencional: la traducción en el servidor debe usar los hooks existentes basados en el contexto de React.

Referencia de la API

Consulta la referencia completa de la API de t() para ver los parámetros, los tipos de retorno y los detalles de configuración.