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.

Tabla de contenidos

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 bundlee 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 runtime para tu aplicación.

Formateo automático de código: configuración de formatCommand

v7 introduce la opción formatCommand en la configuración del editor, permitiéndote formatear automáticamente los archivos de contenido cuando son escritos por Intlayer. Esto asegura un estilo de código consistente y formato uniforme en tus archivos de declaración de contenido.

Si no está configurado, Intlayer intentará detectar el comando de formato automáticamente. Probando resolver los siguientes comandos: prettier, biome, eslint.

Configuración

La opción formatCommand acepta una plantilla de cadena donde {{file}} será reemplazado con la ruta del archivo real:

export default {  content: {    formatCommand: 'bun x biome format "{{file}}" --write --log-level none',  },};

Formateadores soportados

Puedes usar cualquier formateador de código que acepte rutas de archivo como argumentos:

Usando Biome:

formatCommand: 'bun x biome format "{{file}}" --write --log-level none';

Usando Prettier:

formatCommand: 'npx prettier --write "{{file}}" --log-level silent';

Usando ESLint:

formatCommand: 'npx eslint --fix "{{file}}" --quiet';

Usando el formateador integrado de Bun:

formatCommand: 'bun format "{{file}}"';

Beneficios

• Formato consistente: Todos los archivos de contenido se formatean automáticamente según las guías de estilo de tu proyecto
• Experiencia del desarrollador: No hay necesidad de formatear archivos manualmente después de que Intlayer los escriba
• Consistencia del equipo: Garantiza que todos los miembros del equipo tengan el mismo formato aplicado a los archivos de contenido
• Integración CI/CD: Los archivos de contenido mantienen un formato consistente en flujos de trabajo automatizados

Cómo funciona

Cuando Intlayer escribe o actualiza un archivo de declaración de contenido (.content.ts, .content.js, etc.), ejecuta automáticamente el comando de formato especificado en el archivo. El marcador {{file}} se reemplaza con la ruta de archivo real, y el comando se ejecuta en el directorio base del proyecto.

Configuración de Dictionary: Mejor organización y estructura

v7 introduce una nueva sección de configuración dedicada a dictionary que proporciona una mejor organización para la configuración relacionada con el diccionario y una gestión mejorada del contenido.

Nueva estructura de configuración del diccionario

La propiedad fill ha sido movida de la sección content a una nueva sección dictionary, proporcionando una separación más clara de responsabilidades:

Configuración v6:

export default {  content: {    autoFill: "./{{fileName}}.content.json",    contentDir: ["src"],  },};

Configuración v7:

export default {  content: {    contentDir: ["src"],  },  dictionary: {    fill: "./{{fileName}}.content.json",  },};

Beneficios de la nueva estructura

• Organización más clara: La configuración específica del diccionario ahora está agrupada
• Mejor separación de responsabilidades: El descubrimiento de contenido frente a las operaciones del diccionario están claramente separados
• Mantenibilidad mejorada: Más fácil de entender y modificar las configuraciones relacionadas con el diccionario
• Extensibilidad futura: La sección del diccionario puede acomodar configuraciones adicionales específicas del diccionario
• Gestión completa del diccionario: Incluye propiedades como title, live, priority, tags, version y description para crear y gestionar nuevos diccionarios

Uso de la configuración

La configuración del diccionario tiene dos propósitos principales:

1. Valores por defecto: Definir valores por defecto al crear archivos de declaración de contenido
2. Comportamiento de reserva: Proporcionar valores de reserva cuando campos específicos no están definidos, permitiéndote definir el comportamiento de operación del diccionario globalmente

La sección del diccionario incluye propiedades completas para la gestión del diccionario:

• fill: Comportamiento de auto-relleno para la generación de contenido
• title: Título por defecto para nuevos diccionarios
• live: Configuración de sincronización en directo para actualizaciones en tiempo real
• priority: Configuración de prioridad para la resolución del diccionario
• tags: Etiquetas por defecto para la organización del contenido
• version: Gestión de versiones para actualizaciones del diccionario
• description: Descripción por defecto para nuevo contenido

Para más información sobre archivos de declaración de contenido y cómo se aplican los valores de configuración, consulta la Documentación de archivo de contenido.

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

Nuevas configuraciones

• editor.formatCommand: Nueva opción para formateo automático de código en archivos de contenido

Mapeo de migración

Mapeo de configuración

Ejemplo de migración

Antes (v6):

export 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