@intlayer/docs 7.0.0-canary.1 → 7.0.0-canary.3

package/docs/es/releases/v7.md

@@ -0,0 +1,503 @@
+---
+createdAt: 2025-09-22
+updatedAt: 2025-09-23
+title: Nueva Intlayer v7 - ¿Qué hay de nuevo?
+description: Descubre las novedades de Intlayer v7. Grandes mejoras en rendimiento, experiencia del desarrollador y nuevas funcionalidades para mejorar tu flujo de trabajo de internacionalización.
+keywords:
+  - Intlayer
+  - Localización
+  - Desarrollo
+  - Rendimiento
+  - Experiencia del desarrollador
+  - Funcionalidades
+  - React
+  - Next.js
+  - JavaScript
+  - TypeScript
+slugs:
+  - doc
+  - releases
+  - v7
+---
+
+# 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.
+
+```bash
+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:**
+
+```tsx
+const content = getIntlayer("my-title-content", "en");
+// typeof content = { title: "My title" } | { title: "Mon titre" } | { title: "Mi título" }
+```
+
+**Comportamiento en v7:**
+
+```tsx
+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:**
+
+```typescript
+import { Locales } from "intlayer";
+// Enum que incluye todos los locales -> no es tree-shakeable
+
+const locale: Locales = Locales.ENGLISH;
+```
+
+**v7:**
+
+```typescript
+import { Locales, Locale } from "intlayer";
+// Tipo cadena -> totalmente tree-shakeable
+
+const 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](https://github.com/aymericzip/intlayer/blob/main/packages/%40intlayer/types/src/index.ts) 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
+
+```typescript
+// intlayer.config.ts
+export 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:
+
+```typescript
+// Desactivar almacenamiento
+storage: false
+
+// Tipos simples de almacenamiento
+storage: 'cookie'
+storage: 'localStorage'
+storage: 'sessionStorage'
+
+// Cookie con atributos personalizados
+storage: {
+  type: 'cookie',
+  name: 'custom-locale',
+  domain: '.example.com',
+  secure: true,
+  sameSite: 'strict'
+}
+
+// localStorage con clave personalizada
+storage: {
+  type: 'localStorage',
+  name: 'custom-locale'
+}
+
+// Múltiples tipos de almacenamiento para redundancia
+storage: ['cookie', 'localStorage']
+```
+
+### Ejemplo de configuración compatible con GDPR
+
+Para aplicaciones en producción que necesitan equilibrar funcionalidad con cumplimiento de GDPR:
+
+```typescript
+// intlayer.config.ts
+export 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:
+
+```typescript
+<IntlayerProvider isCookieEnabled={false}>
+  <App />
+</IntlayerProvider>
+```
+
+Se puede sobrescribir localmente para cada hook:
+
+```ts
+const { setLocale } = useLocale({ isCookieEnabled: false });
+
+setLocale("en");
+```
+
+**Nota:** Las cookies están habilitadas por defecto.
+**Nota:** Consulta los [requisitos de cookies del GDPR](https://gdpr.eu/cookies/) 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
+
+```typescript
+// Reescribe el archivo actual con todos los locales
+const content = {
+  key: "example",
+  fill: true, // Reescribe este archivo
+  content: {
+    title: "Hello World",
+  },
+};
+
+// Llena un archivo separado sin modificar el archivo actual
+const content = {
+  key: "example",
+  fill: "./translations.json", // Crea/actualiza translations.json
+  content: {
+    title: "Hello World",
+  },
+};
+
+// Deshabilita el auto-llenado
+const content = {
+  key: "example",
+  fill: false, // Sin auto-llenado
+  content: {
+    title: "Hello World",
+  },
+};
+
+// Estructura de contenido compleja con objetos compuestos
+const 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
+
+```typescript
+// Archivo de contenido grande se segmenta automáticamente
+const 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
+
+| 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):**
+
+````typescript
+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):**
+
+```typescript
+export default {
+  middleware: {
+    headerName: "x-intlayer-locale",
+    cookieName: "intlayer-locale",
+    prefixDefault: false,
+    basePath: "",
+    serverSetCookie: "always",
+    noPrefix: false,
+  },
+};
+````
+
+**Después (v7):**
+
+```typescript
+export default {
+  routing: {
+    mode: "prefix-no-default",
+    storage: "localStorage", // o 'cookie' si necesitas almacenamiento en cookie
+    headerName: "x-intlayer-locale",
+    basePath: "",
+    detectLocaleOnPrefetchNoPrefix: false,
+  },
+};
+```
+
+#### Mapeo del contenido del diccionario
+
+| Contenido del diccionario v6 | Contenido del diccionario v7 |
+| ---------------------------- | ---------------------------- |
+| `autoFill: xxx`              | `fill: xxx`                  |
+
+#### Ejemplo de migración
+
+**Antes (v6):**
+
+```typescript
+const content = {
+  key: "example",
+  autoFill: true, // Reescribe este archivo
+  content: {
+    title: "Hola Mundo",
+  },
+};
+```
+
+**Después (v7):**
+
+```typescript
+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](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/releases/v6.md) para más información.
+
+---
+
+## Enlaces útiles
+
+- [Referencia de configuración](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/configuration.md)
+- [Documentación del Middleware](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/packages/next-intlayer/index.md)
+- [Tipos de TypeScript](https://github.com/aymericzip/intlayer/blob/main/packages/%40intlayer/types/src/index.ts)
+- [Directrices de cookies GDPR](https://gdpr.eu/cookies/)