@intlayer/docs 9.4.0-canary.0 → 9.4.0

package/docs/es/intlayer_with_react_router_v7.md

@@ -43,6 +43,8 @@ author: aymericzip
 
 Esta guía demuestra cómo integrar **Intlayer** para una internacionalización fluida en proyectos con React Router v7, con enrutamiento consciente del locale, soporte para TypeScript y prácticas modernas de desarrollo.
 
+Esta guía se enfoca en el enrutamiento frontend. Para el enrutamiento de fs-routes, consulta la guía [Intlayer with React Router v7 File-System Routes](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/intlayer_with_react_router_v7_fs_routes.md).
+
 ## Tabla de contenidos
 
 <TOC/>
@@ -572,6 +574,34 @@ export default function RootLayout() {
 
 </Step>
 
+<Step number={11} title="Agregar middleware">
+
+También puedes usar `intlayerProxy` para agregar enrutamiento del lado del servidor a tu aplicación. Este plugin detectará automáticamente la configuración regional actual basándose en la URL y establecerá la cookie de configuración regional apropiada. Si no se especifica ninguna configuración regional, el plugin determinará la configuración regional más apropiada en función de las preferencias de idioma del navegador del usuario. Si no se detecta ninguna configuración regional, redirigirá a la configuración regional predeterminada.
+
+> Ten en cuenta que para usar `intlayerProxy` en producción, necesitas cambiar el paquete `vite-intlayer` de `devDependencies` a `dependencies`.
+
+> Desde Intlayer v9, `intlayerProxy()` está incluido directamente en el plugin `intlayer()` y habilitado por defecto a través de la opción `routing.enableProxy` (`true` por defecto). Registrarlo por separado como se muestra a continuación ahora es opcional — se mantiene para compatibilidad hacia atrás y para configuraciones que necesitan controlar el orden del plugin. Establece `routing.enableProxy: false` para optar por no participar. Consulta las [notas de la versión v9](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/releases/v9.md).
+
+```typescript {3,7} fileName="vite.config.ts"
+import { defineConfig } from "vite";
+import react from "@vitejs/plugin-react-swc";
+import { intlayer } from "vite-intlayer";
+
+// https://vitejs.dev/config/
+export default defineConfig({
+  plugins: [
+    react(),
+    intlayer({
+      proxy: {
+        ignore: (req) => req.url?.startsWith("/api"),
+      },
+    }),
+  ],
+});
+```
+
+</Step>
+
 <Step number={12} title="Extraer el contenido de tus componentes" isOptional={true}>
 
 Si tienes una base de código existente, transformar miles de archivos puede llevar mucho tiempo.

package/docs/es/intlayer_with_react_router_v7_fs_routes.md

@@ -619,6 +619,34 @@ Este hook ya se usa en el componente de layout (`root.tsx`) mostrado en el Paso
 
 </Step>
 
+<Step number={10} title="Agregar middleware">
+
+También puedes usar `intlayerProxy` para agregar enrutamiento del lado del servidor a tu aplicación. Este plugin detectará automáticamente la configuración regional actual basándose en la URL y establecerá la cookie de configuración regional apropiada. Si no se especifica una configuración regional, el plugin determinará la configuración regional más apropiada basándose en las preferencias de idioma del navegador del usuario. Si no se detecta ninguna configuración regional, redireccionará a la configuración regional predeterminada.
+
+> Ten en cuenta que para usar `intlayerProxy` en producción, necesitas cambiar el paquete `vite-intlayer` de `devDependencies` a `dependencies`.
+
+> Desde Intlayer v9, `intlayerProxy()` está incluido directamente en el plugin `intlayer()` y habilitado por defecto a través de la opción `routing.enableProxy` (`true` por defecto). Registrarlo por separado como se muestra a continuación es ahora opcional — se mantiene para compatibilidad hacia atrás y para configuraciones que necesitan controlar el orden de los plugins. Establece `routing.enableProxy: false` para rechazarlo. Consulta las [notas de la versión v9](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/releases/v9.md).
+
+```typescript {3,7} fileName="vite.config.ts"
+import { reactRouter } from "@react-router/dev/vite";
+import { defineConfig } from "vite";
+import { intlayer } from "vite-intlayer";
+
+export default defineConfig({
+  plugins: [
+    reactRouter(),
+
+    intlayer({
+      proxy: {
+        ignore: (req) => req.url?.startsWith("/api"),
+      },
+    }),
+  ],
+});
+```
+
+</Step>
+
 <Step number={11} title="Extraer el contenido de tus componentes" isOptional={true}>
 
 Si tienes una base de código existente, transformar miles de archivos puede llevar mucho tiempo.
@@ -721,34 +749,6 @@ bun run build # Or bun run dev
 
 </Step>
 
-<Step number={10} title="Añadir middleware">
-
-También puedes usar el `intlayerProxy` para agregar enrutamiento del lado del servidor a tu aplicación. Este plugin detectará automáticamente la configuración regional actual basada en la URL y establecerá la cookie de configuración regional apropiada. Si no se especifica ninguna configuración regional, el plugin determinará la configuración regional más adecuada según las preferencias de idioma del navegador del usuario. Si no se detecta ninguna configuración regional, redirigirá a la configuración regional predeterminada.
-
-> Ten en cuenta que para usar el `intlayerProxy` en producción, necesitas cambiar el paquete `vite-intlayer` de `devDependencies` a `dependencies`.
-
-```typescript {3,7} fileName="vite.config.ts"
-import { reactRouter } from "@react-router/dev/vite";
-import { defineConfig } from "vite";
-import { intlayer } from "vite-intlayer";
-
-export default defineConfig({
-  plugins: [
-    reactRouter(),
-
-    intlayer({
-      proxy: {
-        ignore: (req) => req.url?.startsWith("/api"),
-      },
-    }),
-  ],
-});
-```
-
----
-
-</Step>
-
 </Steps>
 
 ## Configurar TypeScript

package/docs/es/intlayer_with_solid_start.md

@@ -44,6 +44,18 @@ author: aymericzip
 />
 
   </Tab>
+
+<Tab label="Demo" value="demo">
+
+<iframe
+  src="https://intlayer-solid-start-template.vercel.app"
+  className="m-auto overflow-hidden rounded-lg border-0 max-md:size-full max-md:h-[700px] md:aspect-16/9 md:w-full"
+  title="Demo Plantilla Intlayer Solid Start"
+  sandbox="allow-forms allow-modals allow-popups allow-presentation allow-same-origin allow-scripts"
+  loading="lazy"
+/>
+
+  </Tab>
 </Tabs>
 
 ## Tabla de contenidos

package/docs/es/intlayer_with_svelte_kit.md

@@ -113,6 +113,8 @@ Más que una simple solución i18n, Intlayer proporciona un **[editor visual] au
 
 ## Guía paso a paso para configurar Intlayer en una aplicación SvelteKit
 
+Ver [Plantilla de Aplicación](https://github.com/aymericzip/intlayer-sveltekit-template) en GitHub.
+
 Para comenzar, crea un nuevo proyecto SvelteKit. Aquí está la estructura final que crearemos:
 
 ```bash
@@ -267,6 +269,8 @@ export default heroContent;
 
 <Step number={5} title="Utiliza Intlayer en Tus Componentes">
 
+Ahora puedes usar la función `useIntlayer` en cualquier componente de Svelte. Devuelve un store reactivo que se actualiza automáticamente cuando cambia la configuración regional. La función respetará automáticamente la configuración regional actual (tanto durante SSR como durante la navegación del lado del cliente).
+
 para acceder a su valor reactivo (por ejemplo, `$content.title`).
 
 ```svelte fileName="src/lib/components/Component.svelte"
@@ -612,6 +616,8 @@ Para permitir a los usuarios cambiar de idioma, actualiza la URL.
 
 Para añadir un proxy backend a tu aplicación SvelteKit, puedes usar la función `intlayerProxy` proporcionada por el plugin `vite-intlayer`. Este plugin detectará automáticamente la mejor locale para el usuario basándose en la URL, cookies y preferencias de idioma del navegador.
 
+> Desde Intlayer v9, `intlayerProxy()` está incluido directamente en el plugin `intlayer()` y habilitado por defecto a través de la opción `routing.enableProxy` (`true` por defecto). Registrarlo por separado como se muestra a continuación es ahora opcional — se mantiene para compatibilidad hacia atrás y para configuraciones que necesitan controlar el orden de los plugins. Establece `routing.enableProxy: false` para optar por no usarlo. Consulta las [notas de la versión v9](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/releases/v9.md).
+
 ```ts fileName="vite.config.ts"
 import { defineConfig } from "vite";
 import { intlayer } from "vite-intlayer";

package/docs/es/intlayer_with_tanstack+solid.md

@@ -1,6 +1,6 @@
 ---
 createdAt: 2025-03-25
-updatedAt: 2026-06-23
+updatedAt: 2026-08-25
 title: "TanStack Start + Solid i18n - Guía completa para traducir tu aplicación"
 description: "Sin más i18next. La guía 2026 para crear una aplicación TanStack Start + Solid multilingüe (i18n). Traduce con agentes de IA y optimiza el tamaño del bundle, SEO y rendimiento."
 keywords:
@@ -22,6 +22,9 @@ applicationTemplate: https://github.com/aymericzip/intlayer-tanstack-start-solid
 applicationShowcase: https://intlayer-tanstack-start-solid.vercel.app
 youtubeVideo: https://www.youtube.com/watch?v=_XTdKVWaeqg
 history:
+  - version: 9.4.0
+    date: 2026-08-25
+    changes: "Comparar la resolución estática, dinámica y dinámica cacheada de los diccionarios de metadatos en las funciones head de las rutas"
   - version: 8.9.0
     date: 2026-05-04
     changes: "Actualizar el uso de la API useIntlayer de Solid para el acceso directo a las propiedades"
@@ -458,6 +461,8 @@ export const useLocalizedNavigate = () => {
 
 <Step number={9} title="Utilizar Intlayer en sus páginas">
 
+> Usa **`useIntlayer`** por defecto: es la forma recomendada de leer contenido dentro de los componentes, y el compilador lo resuelve a la locale que se está renderizando. Recurre a `getIntlayer` / `getIntlayerAsync` solo fuera del árbol de Solid: el `head` de las rutas, los loaders y las server functions.
+
 Acceda a sus diccionarios de contenido en toda su aplicación:
 
 #### Página de inicio localizada
@@ -487,8 +492,6 @@ function RouteComponent() {
 }
 ```
 
-> Si deseas usar tu contenido en un atributo de tipo `string`, como `alt`, `title`, `href`, `aria-label`, etc., debes llamar al valor de la función, así:
-
 > ```html
 > <img src="{content.image.src.value}" alt="{content.image.value}" />
 > <img src="{content.image.src.toString()}" alt="{content.image.toString()}" />
@@ -574,6 +577,8 @@ También puede utilizar `intlayerProxy` para añadir enrutamiento del lado del s
 
 > Tenga en cuenta que para utilizar `intlayerProxy` en producción, necesita cambiar el paquete `vite-intlayer` de `devDependencies` a `dependencies`.
 
+> Desde Intlayer v9, `intlayerProxy()` está integrado directamente en el plugin `intlayer()` y habilitado por defecto a través de la opción `routing.enableProxy` (`true` por defecto). Registrarlo por separado como se muestra a continuación es ahora opcional: se mantiene para compatibilidad hacia atrás y para configuraciones que necesitan controlar el orden de los plugins. Establece `routing.enableProxy: false` para optar por no participar. Consulta las [notas de la versión v9](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/releases/v9.md).
+
 ```typescript fileName="vite.config.ts"
 import { tanstackStart } from "@tanstack/solid-start/plugin/vite";
 import solid from "vite-plugin-solid";
@@ -606,16 +611,25 @@ export default defineConfig({
 
 <Step number={13} title="Internacionalizar sus metadatos">
 
-También puede utilizar la función `getIntlayer` para acceder a sus diccionarios de contenido dentro del cargador `head` para metadatos conscientes de la localización:
+<Tabs>
+
+<Tab label="Resolución estática" value="static">
+
+`getIntlayer` se resuelve de forma síncrona contra el diccionario **fusionado**, el que contiene todas las locales declaradas. `head` sigue siendo síncrono y no se espera nada, pero todo el diccionario multilingüe se incluye en el chunk de la ruta que se envía al navegador.
 
 ```tsx fileName="src/routes/{-$locale}/index.tsx"
 import { createFileRoute } from "@tanstack/solid-router";
-import { getIntlayer } from "intlayer";
+import {
+  defaultLocale,
+  getIntlayer,
+  getLocalizedUrl,
+  localeMap,
+} from "intlayer";
 
 export const Route = createFileRoute("/{-$locale}/")({
   component: RouteComponent,
   head: ({ params }) => {
-    const { locale } = params;
+    const { locale = defaultLocale } = params;
     const path = "/"; // The path for this route
 
     const metaContent = getIntlayer("app", locale);
@@ -649,6 +663,143 @@ export const Route = createFileRoute("/{-$locale}/")({
 });
 ```
 
+Ideal para diccionarios de metadatos pequeños, pocas locales o durante el prototipado.
+
+</Tab>
+
+<Tab label="Resolución dinámica" value="dynamic">
+
+`getIntlayerAsync` (disponible a partir de la **v9.4**) se comporta como `getIntlayer`, pero el plugin de build lo apunta al chunk por locale en `.intlayer/dynamic_dictionaries/` en lugar del diccionario fusionado. Así, una página solo envía la locale que renderiza. Como ese chunk se carga bajo demanda, `head` pasa a ser `async`:
+
+```tsx fileName="src/routes/{-$locale}/index.tsx"
+import { createFileRoute } from "@tanstack/solid-router";
+import {
+  defaultLocale,
+  getIntlayerAsync,
+  getLocalizedUrl,
+  localeMap,
+} from "intlayer";
+
+export const Route = createFileRoute("/{-$locale}/")({
+  component: RouteComponent,
+  head: async ({ params }) => {
+    const { locale = defaultLocale } = params;
+    const path = "/"; // The path for this route
+
+    const metaContent = await getIntlayerAsync("app", locale);
+
+    return {
+      links: [
+        // Canonical link: Points to the current localized page
+        { rel: "canonical", href: getLocalizedUrl(path, locale) },
+
+        // Hreflang: Tell Google about all localized versions
+        ...localeMap(({ locale: mapLocale }) => ({
+          rel: "alternate",
+          hrefLang: mapLocale,
+          href: getLocalizedUrl(path, mapLocale),
+        })),
+
+        // x-default: For users in unmatched languages
+        // Define the default fallback locale (usually your primary language)
+        {
+          rel: "alternate",
+          hrefLang: "x-default",
+          href: getLocalizedUrl(path, defaultLocale),
+        },
+      ],
+      meta: [
+        { title: metaContent.title },
+        { name: "description", content: metaContent.meta.description },
+      ],
+    };
+  },
+});
+```
+
+> Si un `head` lee varios diccionarios, resuélvelos con `Promise.all`: esperar cada `getIntlayerAsync` en su propia línea encadena las peticiones en lugar de ejecutarlas en paralelo.
+
+La contrapartida: el import dinámico se resuelve mientras se ejecuta `head`, en la ruta crítica del renderizado del documento. En una ruta fría esto retrasa el `head` unos milisegundos y puede degradar ligeramente el **LCP**.
+
+</Tab>
+
+<Tab label="Resolución dinámica cacheada" value="cached">
+
+Resuelve el diccionario en el `loader` de la ruta y vuelve a leerlo desde `loaderData` en `head`. Los loaders de las rutas coincidentes se ejecutan en paralelo, y `staleTime: Infinity` le indica a TanStack Router que el resultado nunca caduca, de modo que el chunk por locale se resuelve una sola vez y luego se sirve desde la caché del router, dejando `head` síncrono.
+
+```tsx fileName="src/routes/{-$locale}/index.tsx"
+import { createFileRoute } from "@tanstack/solid-router";
+import {
+  defaultLocale,
+  getIntlayerAsync,
+  getLocalizedUrl,
+  localeMap,
+} from "intlayer";
+
+export const Route = createFileRoute("/{-$locale}/")({
+  component: RouteComponent,
+  // Resolved in parallel with the other matched routes, off the head critical path
+  loader: async ({ params }) => {
+    const { locale = defaultLocale } = params;
+
+    return { metaContent: await getIntlayerAsync("app", locale) };
+  },
+  // The dictionary never changes for a given locale: resolve the chunk once
+  staleTime: Infinity,
+  head: ({ params, loaderData }) => {
+    const { locale = defaultLocale } = params;
+    const path = "/"; // The path for this route
+
+    return {
+      links: [
+        // Canonical link: Points to the current localized page
+        { rel: "canonical", href: getLocalizedUrl(path, locale) },
+
+        // Hreflang: Tell Google about all localized versions
+        ...localeMap(({ locale: mapLocale }) => ({
+          rel: "alternate",
+          hrefLang: mapLocale,
+          href: getLocalizedUrl(path, mapLocale),
+        })),
+
+        // x-default: For users in unmatched languages
+        // Define the default fallback locale (usually your primary language)
+        {
+          rel: "alternate",
+          hrefLang: "x-default",
+          href: getLocalizedUrl(path, defaultLocale),
+        },
+      ],
+      meta: [
+        { title: loaderData?.metaContent.title },
+        {
+          name: "description",
+          content: loaderData?.metaContent.meta.description,
+        },
+      ],
+    };
+  },
+});
+```
+
+> `head` puede llamarse antes de que el loader se resuelva, por lo que `loaderData` está tipado como posiblemente `undefined`. Mantén el encadenamiento opcional o devuelve un título de reserva.
+
+Conservas el chunk por locale sin pagar su coste en la ruta crítica del `head`. El precio es la experiencia de desarrollo: el contenido debe pasarse explícitamente del loader al `head` a través de `loaderData`.
+
+</Tab>
+
+</Tabs>
+
+### ¿Qué resolución debo elegir?
+
+|                           | Resolución estática          | Resolución dinámica                       | Resolución dinámica cacheada           |
+| ------------------------- | ---------------------------- | ----------------------------------------- | -------------------------------------- |
+| API                       | `getIntlayer`                | `getIntlayerAsync` (v9.4+)                | `getIntlayerAsync` en `loader` (v9.4+) |
+| Firma de `head`           | síncrona                     | `async`                                   | síncrona, lee `loaderData`             |
+| Locales enviadas          | todas las locales declaradas | solo la locale solicitada                 | solo la locale solicitada              |
+| Navegaciones en cliente   | nada que resolver            | se vuelve a ejecutar en cada coincidencia | servido desde la caché del router      |
+| Experiencia de desarrollo | la más simple                | un solo `await`                           | contenido pasado por `loaderData`      |
+
 ---
 
 </Step>