Resumen

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

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

t() cubre esa necesidad. 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 y sin necesidad de un árbol de componentes.

Por qué este enfoque

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

Esto implica ciertas contrapartidas:

• Solo del lado del cliente. t() funciona solo en aplicaciones React del lado del cliente. Se basa en la ejecución de módulos en el navegador para cargar las traducciones antes de que la aplicación se renderice.
• Recarga completa de la página para cambiar de idioma. Como las traducciones se resuelven en el momento en que se carga el módulo, cambiar de configuración regional requiere volver a ejecutar los módulos, lo que implica una recarga completa de la página. No es posible cambiar de idioma dinámicamente a mitad de la sesión.

Por otro lado, la experiencia del desarrollador mejora mucho. Sin envolver cadenas en hooks, sin configuraciones adicionales a nivel de componente, sin 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 tienen sentido.

Cómo funciona

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

Necesitas cambiar el punto de entrada de la aplicación para ejecutar primero bootstrap(). Normalmente sería 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 getTranslations(locale: string) {
  return import(`./_gt/${locale}.json`);
}

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

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

La función getTranslations es asíncrona: primero carga las traducciones y luego importa y ejecuta la aplicación de React. Así es como t() puede acceder a ellas en el nivel de módulo: para 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 en el nivel de módulo se vuelve a ejecutar al cargarse 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, al 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 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), muestra una advertencia y vuelve a la cadena de origen. Esto es intencional: la traducción del lado del 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.