Nueva Intlayer v7 - ¿Qué hay de nuevo?

¡Bienvenido a Intlayer v7! Esta versión mayor introduce mejoras significativas en rendimiento, seguridad de tipos y experiencia del desarrollador. A continuación, los aspectos destacados, con notas de migración y ejemplos prácticos.

Aspectos destacados

• Estrategia de caché para compilaciones más rápidas
• Generación mejorada de tipos TypeScript con tipos específicos por localización
• Optimización del paquete: Localizaciones como cadenas en lugar de enum
• Nuevos modos de enrutamiento: prefix-no-default, prefix-all, no-prefix, search-params
• Almacenamiento de localización conforme al GDPR con localStorage por defecto
• Configuración flexible de almacenamiento: cookies, localStorage, sessionStorage o múltiples
• Tamaño del paquete del Editor Visual un 30% más pequeño
• Opciones mejoradas de configuración del middleware
• Comportamiento actualizado del comando fill para una mejor gestión de contenido
• Mayor estabilidad con actualizaciones completas del archivo de declaración de contenido
• Gestión inteligente de reintentos para mayor precisión en las traducciones
• Paralelización para un procesamiento de traducción más rápido
• División inteligente para manejar archivos grandes dentro de los límites del contexto de IA

Rendimiento: Caché para compilaciones más rápidas

En lugar de reconstruir las declaraciones de contenido con esbuild en cada compilación, la versión 7 implementa una estrategia de caché que acelera el proceso de construcción.

npx intlayer build

El nuevo sistema de caché:

• Almacena las declaraciones de contenido compiladas para evitar procesamiento redundante
• Detecta cambios y reconstruye solo los archivos modificados
• Reduce significativamente los tiempos de compilación en proyectos grandes

TypeScript: Generación de tipos específicos por localización

Los tipos de TypeScript ahora se generan por localización, proporcionando una tipificación más fuerte y eliminando los tipos unión entre todas las localizaciones.

Comportamiento en v6:

const content = getIntlayer("my-title-content", "en");// typeof content = { title: "My title" } | { title: "Mon titre" } | { title: "Mi título" }

Comportamiento en v7:

const content = getIntlayer("my-title-content", "en");// typeof content = { title: "My title" }

Beneficios:

• Autocompletado más preciso en tu IDE
• Mejor seguridad de tipos sin contaminación entre locales
• Rendimiento mejorado al reducir la complejidad de tipos

Optimización del paquete: Locales como cadenas

El tipo Locales ya no es un enum, lo que significa que ahora es totalmente tree-shakeable y no inflará tu paquete con miles de registros de locales no usados.

v6:

import { Locales } from "intlayer";// Enum que incluye todos los locales -> no es tree-shakeableconst locale: Locales = Locales.ENGLISH;

v7:

import { Locales, Locale } from "intlayer";// Tipo cadena -> totalmente tree-shakeableconst locale: Locale = Locales.ENGLISH;

Debido a que Locales ya no es un enum, deberás cambiar el tipo de Locales a Locale para obtener el locale como tipo.

Consulta los detalles de implementación para más información.

Nuevos modos de enrutamiento para mayor flexibilidad

v7 introduce una configuración unificada routing.mode que reemplaza las opciones anteriores prefixDefault y noPrefix, ofreciendo un control más granular sobre la estructura de las URLs.

Modos de enrutamiento disponibles

• prefix-no-default (por defecto): El locale por defecto no tiene prefijo, los demás locales sí
  • /dashboard (en) o /fr/dashboard (fr)
• prefix-all: Todos los locales tienen un prefijo
  • /en/dashboard (en) o /fr/dashboard (fr)
• no-prefix: Sin prefijos de locale en las URLs (locale manejado vía almacenamiento/headers)
  • /dashboard para todos los locales
• search-params: Locale pasado como parámetro de consulta
  • /dashboard?locale=en o /dashboard?locale=fr

Configuración básica

// intlayer.config.tsexport default {  internationalization: {    locales: ["en", "fr", "es"],    defaultLocale: "en",  },  routing: {    mode: "prefix-no-default", // por defecto  },};

Cumplimiento GDPR: almacenamiento en localStorage / cookies

v7 prioriza la privacidad del usuario usando localStorage como mecanismo de almacenamiento predeterminado en lugar de cookies. Este cambio ayuda con el cumplimiento del GDPR al evitar los requisitos de consentimiento de cookies para las preferencias de locale.

Opciones de configuración de almacenamiento

El nuevo campo routing.storage también está disponible además de las opciones anteriores middleware.cookieName y middleware.serverSetCookie, ofreciendo configuraciones flexibles de almacenamiento:

// Desactivar almacenamientostorage: false// Tipos simples de almacenamientostorage: 'cookie'storage: 'localStorage'storage: 'sessionStorage'// Cookie con atributos personalizadosstorage: {  type: 'cookie',  name: 'custom-locale',  domain: '.example.com',  secure: true,  sameSite: 'strict'}// localStorage con clave personalizadastorage: {  type: 'localStorage',  name: 'custom-locale'}// Múltiples tipos de almacenamiento para redundanciastorage: ['cookie', 'localStorage']

Ejemplo de configuración compatible con GDPR

Para aplicaciones en producción que necesitan equilibrar funcionalidad con cumplimiento de GDPR:

// intlayer.config.tsexport default {  internationalization: {    locales: ["en", "fr", "es"],    defaultLocale: "en",  },  routing: {    mode: "prefix-no-default",    storage: [      {        type: "localStorage", // Almacenamiento principal (no se necesita consentimiento)        name: "user-locale",      },      {        type: "cookie", // Almacenamiento opcional en cookies (requiere consentimiento)        name: "user-locale",        secure: true,        sameSite: "strict",        httpOnly: false,      },    ],  },};

Habilitar / deshabilitar el almacenamiento en cookies

Ejemplo usando React / Next.js:

Se puede definir globalmente:

<IntlayerProvider isCookieEnabled={false}>  <App /></IntlayerProvider>

Se puede sobrescribir localmente para cada hook:

const { setLocale } = useLocale({ isCookieEnabled: false });setLocale("en");

Nota: Las cookies están habilitadas por defecto. Nota: Consulta los requisitos de cookies del GDPR para tu caso específico.

Editor Visual: paquete un 30% más pequeño

El paquete del Editor Visual ha sido optimizado para ser un 30% más pequeño que la versión anterior, gracias a:

• Mejoras en el rendimiento del editor de código
• Eliminación de dependencias innecesarias en los paquetes principales de Intlayer
• Mejor tree-shaking y empaquetado de módulos

Esto se traduce en tiempos de descarga más rápidos y un mejor rendimiento en tiempo de ejecución para tu aplicación.

Comando fill: comportamiento actualizado para una mejor gestión de contenido

v7 introduce un comportamiento mejorado para el comando fill, proporcionando una gestión de contenido más predecible y flexible:

Nuevo comportamiento de fill

• fill: true - Reescribe el archivo actual con contenido completado para todos los locales
• fill: "ruta/al/archivo" - Completa el archivo especificado sin modificar el archivo actual
• fill: false - Desactiva completamente el auto-fill

Soporte mejorado para estructuras de contenido complejas

El comando fill ahora soporta estructuras complejas de declaración de contenido, incluyendo:

• Objetos compuestos: Declaraciones de contenido que hacen referencia a otros objetos
• Contenido desestructurado: Contenido que usa patrones de desestructuración
• Referencias anidadas: Objetos que se llaman entre sí en jerarquías complejas
• Estructuras de contenido dinámicas: Contenido con propiedades condicionales o computadas

Beneficios

• Intención más clara: El comportamiento ahora es más explícito sobre qué se modifica
• Mejor separación: Los archivos de contenido pueden mantenerse separados de las traducciones completadas
• Flujo de trabajo mejorado: Los desarrolladores tienen más control sobre dónde se almacenan las traducciones
• Soporte para estructuras complejas: Maneja arquitecturas de contenido sofisticadas con múltiples objetos interconectados

Ejemplo de uso

// Reescribe el archivo actual con todos los localesconst content = {  key: "example",  fill: true, // Reescribe este archivo  content: {    title: "Hello World",  },};// Llena un archivo separado sin modificar el archivo actualconst content = {  key: "example",  fill: "./translations.json", // Crea/actualiza translations.json  content: {    title: "Hello World",  },};// Deshabilita el auto-llenadoconst content = {  key: "example",  fill: false, // Sin auto-llenado  content: {    title: "Hello World",  },};// Estructura de contenido compleja con objetos compuestosconst sharedContent = {  buttons: {    save: "Guardar",    cancel: "Cancelar",  },};const content = {  key: "complex-example",  fill: true,  content: {    // Referencias a otros objetos    sharedContent,    // Contenido desestructurado    ...sharedContent,    // Referencias anidadas    sections: [      {        ...sharedContent.buttons,        header: "Sección 1",      },    ],  },};

Estabilidad mejorada y gestión de traducciones

v7 introduce varias mejoras para hacer que la traducción de contenido sea más confiable y eficiente:

Actualizaciones completas de archivos de declaración de contenido

El sistema ahora actualiza archivos .content.{ts,js,cjs,mjs} en lugar de actualizaciones parciales, asegurando:

• Integridad de datos: La reescritura completa de archivos previene actualizaciones parciales que podrían corromper el contenido
• Consistencia: Todos los locales se actualizan de forma atómica, manteniendo la sincronización
• Confiabilidad: Reduce el riesgo de archivos de contenido incompletos o mal formados

Gestión inteligente de reintentos

Nuevos mecanismos de reintento evitan enviar contenido en formatos incorrectos y previenen que todo el proceso de llenado se interrumpa si una solicitud falla.

Paralelización para un procesamiento más rápido

Las operaciones de traducción ahora se ejecutan en una cola para correr en paralelo. Esto acelera significativamente el proceso.

Segmentación inteligente para archivos grandes

Estrategias avanzadas de segmentación manejan archivos de contenido grandes sin exceder las ventanas de contexto de la IA:

Ejemplo de flujo de trabajo

// Archivo de contenido grande se segmenta automáticamenteconst content = {  key: "large-documentation",  fill: true,  content: {    // Contenido grande dividido automáticamente para el procesamiento por IA    introduction: "..." // más de 5000 caracteres    sections: [      // Múltiples secciones grandes    ]  }};

El sistema automáticamente:

1. Analiza el tamaño y la estructura del contenido
2. Divide el contenido en partes apropiadas
3. Procesa las partes en paralelo
4. Valida y reintenta si es necesario
5. Reconstruye el archivo completo

Notas de migración desde la versión v6

Configuraciones eliminadas

• middleware.cookieName: Reemplazado por routing.storage
• middleware.serverSetCookie: Reemplazado por routing.storage
• middleware.prefixDefault: Reemplazado por routing.mode
• middleware.noPrefix: Reemplazado por routing.mode

Mapeo de migración

Mapeo de configuración

Ejemplo de migración

Antes (v6):

export default {#### Mapeo de configuración| Configuración v6           | Configuración v7                                     || -------------------------- | ---------------------------------------------------- || `autoFill: xxx`            | `fill: xxx`                                          || `prefixDefault: false`     | `mode: 'prefix-no-default'`                          || `prefixDefault: true`      | `mode: 'prefix-all'`                                 || `noPrefix: true`           | `mode: 'no-prefix'`                                  || `cookieName: 'my-locale'`  | `storage: { type: 'cookie', name: 'my-locale' }`     || `serverSetCookie: 'never'` | `storage: false` o eliminar la cookie del array de almacenamiento |#### Ejemplo de migración**Antes (v6):**```typescriptexport default {  middleware: {    headerName: "x-intlayer-locale",    cookieName: "intlayer-locale",    prefixDefault: false,    basePath: "",    serverSetCookie: "always",    noPrefix: false,  },};

Después (v7):

export default {  routing: {    mode: "prefix-no-default",    storage: "localStorage", // o 'cookie' si necesitas almacenamiento en cookie    headerName: "x-intlayer-locale",    basePath: "",  },};

Mapeo del contenido del diccionario

Ejemplo de migración

Antes (v6):

const content = {  key: "example",  autoFill: true, // Reescribe este archivo  content: {    title: "Hola Mundo",  },};

Después (v7):

const content = {  key: "example",  fill: true, // Reescribe este archivo  content: {    title: "Hola Mundo",  },};

Notas de migración de v5 a v6

Consulta las notas de migración de v5 a v6 para más información.

Enlaces útiles

• Referencia de configuración
• Documentación del Middleware
• Tipos de TypeScript
• Directrices de cookies GDPR