¿Qué son las traducciones locales?

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

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-next obtiene las traducciones del CDN de General Translation. Al traducir tu app usando nuestra API, las traducciones se guardan automáticamente en nuestro CDN.

Compensaciones

Beneficios de las local translations

• Tiempos de carga más rápidos: Las local translations se sirven directamente desde tu app, por lo que cargan más rápido que las traducciones servidas desde una CDN (red de distribución de contenido)
• Sin dependencia de servicios externos: La capacidad de tu app para cargar traducciones no depende del tiempo de actividad de la CDN. Si no se encuentran traducciones para un locale, la app vuelve automáticamente al idioma predeterminado
• Funciona sin conexión: Las traducciones se incluyen en el paquete de tu app

Desventajas de las local translations

• Mayor tamaño del bundle: Las local translations aumentan el tamaño del bundle de tu app, lo que podría hacer que tarde más en cargar inicialmente
• 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 translations = await import(`../public/_gt/${locale}.json`);
  return translations.default;
}

withGTConfig detecta automáticamente el archivo loadTranslations.[js|ts] en el directorio src/ o en la raíz del proyecto.

Paso 2: Configurar la CLI

Ejecuta el comando de configuración y elige 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: Ingresa ./public/_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 3: 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 public/_gt/ y se empaquetarán con tu aplicación.

Integración con el proceso de build

Proceso de compilación de Next.js

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 la aplicación  
  run: npm run build

Problemas frecuentes

Archivos de traducción faltantes

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

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

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

Errores en la ruta de importación

Alinea tu estructura de directorios en la función load:

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

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

Tamaño de paquete grande

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

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

Próximos pasos

• Guía de middleware - Detección de idioma y enrutamiento
• Guía de idiomas - Configurar los idiomas compatibles
• Referencia de API: