¿Qué son las traducciones locales?

Las traducciones locales se almacenan en el bundle de tu app, en lugar de obtenerse desde un CDN (Content Delivery Network). Cuando agregas el comando gtx-cli translate a tu proceso de build, 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 (predeterminado): Obtén las traducciones desde 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.

Compromisos

Beneficios de las traducciones locales

• Cargas más rápidas: Las traducciones locales se sirven directamente desde tu aplicación y se cargan más rápido que las servidas desde una CDN (Red de distribución de contenido)
• Sin depender de servicios externos: La capacidad de tu aplicación para cargar traducciones no depende del tiempo de actividad de la CDN. Si no se encuentran traducciones para un locale, la aplicación vuelve automáticamente al idioma predeterminado
• Funciona sin conexión: Las traducciones se empaquetan con tu aplicación

Desventajas de las traducciones locales

• Aumento del tamaño del bundle: Las traducciones locales incrementan el tamaño del bundle de tu app, lo que puede hacer que tarde más en cargar inicialmente
• Gestión de contenido: Para editar una traducción, debes volver a implementar tu app con la nueva versión cada vez que hagas cambios

Configuración

Paso 1: Crear la función de carga

Agrega 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 CDN? Selecciona «No»
• Directorio de traducciones: La CLI 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 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 guardarán en src/_gt/ y se incluirán en el paquete de tu aplicación.

Integración de 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 && <...TU_COMANDO_DE_BUILD...>"
  }
}

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 comunes

Archivos de traducción faltantes

Asegúrate de generar las traducciones antes de compilar:

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

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

Errores de rutas de importación

Haz coincidir tu estructura de directorios en la función load:

// ❌ 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 aplicaciones 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 admitidos