¿Qué son las traducciones locales?

Las traducciones locales se almacenan en el paquete (bundle) de tu app, en lugar de obtenerse de un CDN (Content Delivery Network). Cuando agregas el comando gtx-cli translate a tu proceso de compilación, se generan traducciones en formato JSON. El paso final es incorporar estas traducciones en tu app para que puedan usarse.

Hay dos maneras de hacerlo:

1. En el bundle de tu app (local): Guarda las traducciones en el bundle de tu app después de generarlas
2. En un CDN (opción predeterminada): Obtén las traducciones de un CDN en tiempo de ejecución

De forma predeterminada, gt-react obtiene las traducciones del CDN de General Translation. Al traducir tu app usando nuestra API, las traducciones se guardan automáticamente en nuestro CDN.

Equilibrios

Beneficios de las traducciones locales

• Tiempos de carga más rápidos: Las traducciones locales se sirven directamente desde tu app y cargan más rápido que las servidas desde una red de distribución de contenido (CDN)
• Sin depender de servicios externos: La capacidad de tu app para cargar traducciones no depende de la disponibilidad de la CDN. Si no se encuentran traducciones para un locale, la app recurre automáticamente al idioma predeterminado
• Funciona sin conexión: Las traducciones se incluyen con tu app

Desventajas de las traducciones locales

• Aumento del tamaño del bundle: Las traducciones locales aumentan el tamaño del bundle de tu app, lo que puede hacer que la carga inicial sea más lenta
• Gestión de contenido: Para editar una traducción, debes volver a desplegar tu app con la nueva traducción cada vez que hagas cambios

Configuración

Paso 1: Crear la función de carga

Añade un archivo loadTranslations.[js|ts] en ./src con el siguiente contenido:

export default async function loadTranslations(locale: string) {
  const t = await import(`./_gt/${locale}.json`);
  return t.default;
}

Paso 2: Configurar GTProvider

Pasa loadTranslations como prop al componente <GTProvider>:

import { GTProvider } from 'gt-react';
import loadTranslations from './loadTranslations';

export default function App() {
  return (
    <GTProvider loadTranslations={loadTranslations} locales={['es', 'fr']}>
      <YourApp />
    </GTProvider>
  );
}

Paso 3: Configurar la CLI

Ejecuta el comando de configuración y selecciona el almacenamiento local:

npx gtx-cli configure

Cuando se te solicite:

• ¿Guardar en la CDN (red de distribución de contenido)? Selecciona «No».
• Directorio de traducciones: La CLI (interfaz de línea de comandos) usará automáticamente ./src/_gt.

Como alternativa, puedes configurar manualmente el archivo gt.config.json para usar traducciones locales. Consulta la documentación de configuración de la CLI para obtener más información.

Paso 4: Generar traducciones

Ahora, cuando ejecutes el comando translate, las traducciones se descargarán automáticamente y se incorporarán a tu código:

npx gtx-cli translate

Las traducciones se almacenarán en src/_gt/ y se empaquetarán con tu aplicación.

Integración de la compilación

Proceso de compilación de React

Añade la generación de traducciones a tu script de compilación:

{
  "scripts": {
    "build": "npx gtx-cli translate && <...YOUR_BUILD_COMMAND...>"
  }
}

Canalización de CI/CD

# .github/workflows/deploy.yml
- name: Generar traducciones
  run: npx gtx-cli translate
  
- name: Compilar aplicación  
  run: npm run build

Problemas frecuentes

Archivos de traducción faltantes

Asegúrate de generar las traducciones antes de la compilación:

# ❌ Compila sin traducciones
<...YOUR_BUILD_COMMAND...>

# ✅ Genera primero las traducciones
npx gtx-cli translate && <...YOUR_BUILD_COMMAND...>

Errores en las rutas de importación

Asegúrate de que la función load refleje tu estructura de directorios:

// ❌ Ruta incorrecta
const t = await import(`../translations/${locale}.json`);

// ✅ Ruta correcta para src/_gt
const t = await import(`./_gt/${locale}.json`);

Paquete de gran tamaño

Considera dividir el código en apps con muchos idiomas:

// Cargar traducciones solo cuando sea necesario
export default async function loadTranslations(locale: string) {
  // Solo cargar si el locale está activo
  if (locale === getCurrentLocale()) {
    const translations = await import(`./_gt/${locale}.json`);
    return translations.default;
  }
  return {};
}

Próximos pasos

• Guía de idiomas - Configura los idiomas compatibles