¿Qué son las traducciones locales?

Las traducciones locales se almacenan en el 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 build, este genera traducciones en formato JSON. El paso final es integrar estas traducciones 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 de un CDN en tiempo de ejecución

De forma predeterminada, gt-next obtiene las traducciones del CDN de General Translation. Al traducir tu app con 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 que se entregan desde un CDN
• Sin depender de servicios externos: La capacidad de tu aplicación para cargar traducciones no depende del tiempo de actividad del CDN. Si no se encuentran traducciones para un locale, la aplicación recurre automáticamente al idioma predeterminado
• Funciona sin conexión: Las traducciones se incluyen en el paquete de 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 cargarse al inicio
• Gestión de contenido: Para editar una traducción, debes volver a desplegar tu app con la nueva versió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 selecciona el almacenamiento local:

npx gtx-cli configure

Cuando se te solicite:

• ¿Guardar en el CDN? Selecciona «No»
• Directorio de traducciones: Introduce ./public/_gt

También 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 agregarán a tu base de código:

npx gtx-cli translate

Las traducciones se guardarán en public/_gt/ y se empaquetarán con tu aplicación.

Integración de la compilación

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 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...>

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

Errores en la ruta de importación

Haz que coincida 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`);

Bundle de gran tamaño

Considera dividir el código (code splitting) para 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(`../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 - Configuración de idiomas compatibles
• Referencia de API: