@intlayer/docs 9.5.4 → 9.5.5

package/docs/es/packages/astro-intlayer/intlayer.md

@@ -0,0 +1,76 @@
+---
+createdAt: 2026-01-21
+updatedAt: 2026-09-19
+title: Documentación de la integración intlayer | astro-intlayer
+description: Aprende a configurar y utilizar la integración de Astro intlayer en astro.config.mjs.
+keywords:
+  - intlayer
+  - astro
+  - astro-intlayer
+  - integración
+  - i18n
+  - internacionalización
+  - documentación
+slugs:
+  - doc
+  - packages
+  - astro-intlayer
+  - intlayer
+history:
+  - version: 9.5.5
+    date: 2026-09-19
+    changes: "Actualizada documentación de integración con detalles de middleware y hooks"
+  - version: 8.0.0
+    date: 2026-01-21
+    changes: "Doc inicial"
+author: aymericzip
+---
+
+# Documentación de la integración de Astro intlayer
+
+La integración `intlayer` para Astro configura tu proyecto para la internacionalización (i18n) multilingüe. Se encarga de la preparación de diccionarios en tiempo de compilación, la inyección de plugins de Vite, el registro automático de middleware de solicitudes y la emisión de páginas prerenderizadas localizadas.
+
+## Uso
+
+Agrega `intlayer()` a tu `astro.config.mjs`:
+
+```ts fileName="astro.config.mjs"
+import { defineConfig } from "astro/config";
+import { intlayer } from "astro-intlayer";
+
+export default defineConfig({
+  integrations: [intlayer()],
+});
+```
+
+El codemod del CLI de Astro (`astro add astro-intlayer`) también genera una importación predeterminada que es compatible:
+
+```ts
+import intlayer from "astro-intlayer";
+```
+
+## Descripción
+
+La integración se conecta al ciclo de vida de compilación y ejecución de Astro:
+
+1. **Configuración (`astro:config:setup`)**:
+   - **Preparación de diccionarios**: Prepara los diccionarios de Intlayer y los tipos generados antes de que se ejecute la compilación.
+   - **Plugins de Vite**: Inyecta plugins para alias de Vite (permitiendo importaciones directas de diccionarios), proxies de enrutamiento de locale y poda de compilación.
+   - **Registro de Middleware**: Inyecta automáticamente `astro-intlayer/middleware` en la cadena de middleware de tu proyecto, completando `Astro.locals.intlayer` en cada solicitud entrante.
+2. **Compilación finalizada (`astro:build:done`)**:
+   - **Reescritura de páginas**: Inspecciona las reglas de reescritura de URL localizadas y emite páginas HTML prerenderizadas en sus rutas localizadas correspondientes.
+
+## Qué se proporciona de forma predeterminada
+
+Una vez configurada, tu aplicación Astro puede utilizar inmediatamente:
+
+- Los hooks `useIntlayer`, `useDictionary` y `useLocale` dentro del frontmatter de componentes `.astro`.
+- El objeto `Astro.locals.intlayer` en endpoints y páginas de Astro.
+- Importaciones en el cliente en bloques `<script>` que reflejan la misma API con actualizaciones reactivas.
+- Formateadores integrados bajo `astro-intlayer/format` (`useDate`, `useNumber`, `useCurrency`, etc.).
+
+## Documentación relacionada
+
+- [Hook `useIntlayer`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/packages/astro-intlayer/useIntlayer.md)
+- [Hook `useLocale`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/packages/astro-intlayer/useLocale.md)
+- [Middleware `onRequest`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/packages/astro-intlayer/onRequest.md)

package/docs/es/packages/astro-intlayer/onRequest.md

@@ -0,0 +1,76 @@
+---
+createdAt: 2026-09-19
+updatedAt: 2026-09-19
+title: Documentación del middleware onRequest | astro-intlayer
+description: Descubre cómo usar el middleware onRequest en aplicaciones Astro para resolver el locale de la solicitud y completar Astro.locals.intlayer.
+keywords:
+  - onRequest
+  - middleware
+  - astro
+  - astro-intlayer
+  - Astro.locals
+  - internacionalización
+  - documentación
+slugs:
+  - doc
+  - packages
+  - astro-intlayer
+  - onRequest
+history:
+  - version: 9.5.5
+    date: 2026-09-19
+    changes: "Doc inicial"
+author: aymericzip
+---
+
+# Documentación del middleware de Astro onRequest
+
+El middleware `onRequest` de `astro-intlayer/middleware` resuelve el locale de cada solicitud HTTP entrante y completa `Astro.locals.intlayer`.
+
+Cuando registras la integración `intlayer()` en `astro.config.mjs`, este middleware se inyecta automáticamente. Solo necesitas importarlo directamente si estás componiendo manualmente middleware de Astro usando `sequence(...)`.
+
+## Uso
+
+```ts fileName="src/middleware.ts"
+import { onRequest as intlayer } from "astro-intlayer/middleware";
+import { sequence } from "astro:middleware";
+
+export const onRequest = sequence(intlayer, async (context, next) => {
+  // Accede al locale resuelto en tu middleware personalizado
+  const { locale } = context.locals.intlayer;
+  console.log(`Gestionando solicitud para el locale: ${locale}`);
+
+  return next();
+});
+```
+
+## Descripción
+
+El middleware realiza lo siguiente:
+
+1. **Detección de Locale**:
+   - **URL**: Analiza el prefijo de ruta de la URL o el parámetro de búsqueda `?locale=` (a menos que `routing.mode` esté configurado como `no-prefix`).
+   - **Cookies / Encabezados**: Comprueba cookies de locale persistidas o valores de encabezado personalizados.
+   - **Accept-Language**: Utiliza como alternativa la negociación de idioma preferida del navegador.
+   - Para páginas prerenderizadas (`context.isPrerendered`), el locale se extrae estrictamente de la URL para evitar advertencias de compilación de Astro.
+2. **Población del contexto**: Completa `Astro.locals.intlayer` con:
+   - `locale`: El locale resuelto.
+   - `defaultLocale`: El locale de respaldo predeterminado.
+   - `availableLocales`: La lista de locales configurados.
+3. **Ámbito AsyncLocalStorage**: Envuelve el procesamiento de la solicitud descendente dentro de un ámbito `AsyncLocalStorage`, permitiendo que `useIntlayer()`, `useDictionary()` y `useLocale()` accedan al estado de la solicitud sin pasar argumentos.
+
+## Tipo `IntlayerLocals`
+
+```ts
+export type IntlayerLocals = {
+  locale: DeclaredLocales;
+  defaultLocale: DeclaredLocales;
+  availableLocales: DeclaredLocales[];
+};
+```
+
+## Documentación relacionada
+
+- [Integración `intlayer`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/packages/astro-intlayer/intlayer.md)
+- [Hook `useIntlayer`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/packages/astro-intlayer/useIntlayer.md)
+- [Hook `useLocale`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/packages/astro-intlayer/useLocale.md)

package/docs/es/packages/astro-intlayer/useDictionary.md

@@ -0,0 +1,94 @@
+---
+createdAt: 2026-09-19
+updatedAt: 2026-09-19
+title: Documentación del hook useDictionary | astro-intlayer
+description: Descubre cómo usar el hook useDictionary en componentes y scripts de Astro para resolver objetos de diccionario.
+keywords:
+  - useDictionary
+  - dictionary
+  - astro
+  - astro-intlayer
+  - Intlayer
+  - intlayer
+  - internacionalización
+  - documentación
+slugs:
+  - doc
+  - packages
+  - astro-intlayer
+  - useDictionary
+history:
+  - version: 9.5.5
+    date: 2026-09-19
+    changes: "Doc inicial"
+author: aymericzip
+---
+
+# Documentación del hook useDictionary
+
+El hook `useDictionary` resuelve un objeto de diccionario importado o en línea y devuelve su contenido para el locale actual en aplicaciones Astro.
+
+A diferencia de `useIntlayer`, que recupera diccionarios por clave desde el registro global de diccionarios, `useDictionary` funciona directamente con un objeto de diccionario.
+
+## Uso
+
+```astro fileName="src/pages/index.astro"
+---
+import { useDictionary } from "astro-intlayer";
+import homeContent from "../content/home.content";
+
+const content = useDictionary(homeContent);
+---
+
+<main>
+  <h1>{content.title}</h1>
+  <p>{content.description}</p>
+</main>
+```
+
+También puedes pasar diccionarios en línea definidos con `t()`:
+
+```astro fileName="src/components/Footer.astro"
+---
+import { useDictionary } from "astro-intlayer";
+import { t } from "intlayer";
+
+const footer = useDictionary({
+  key: "footer",
+  content: {
+    copyright: t({
+      es: "Todos los derechos reservados.",
+      en: "All rights reserved.",
+      fr: "Tous droits réservés.",
+    }),
+  },
+});
+---
+
+<footer>
+  <p>{footer.copyright}</p>
+</footer>
+```
+
+## Parámetros
+
+```ts
+useDictionary(dictionary, localeOrSelector?)
+```
+
+1. **`dictionary`**: Un objeto de diccionario o grupo de diccionarios calificado.
+2. **`localeOrSelector`** (opcional): Un locale específico o un objeto selector (`{ item }`, `{ variant }`, opcionalmente con `locale`).
+
+## Descripción
+
+El hook realiza las siguientes tareas:
+
+1. **Detección de Locale**: En el servidor, obtiene el locale de `Astro.locals.intlayer`. En el navegador, utiliza el locale del store del cliente.
+2. **Procesamiento de contenido**: Resuelve traducciones (`t()`), enumeraciones, condiciones y estructuras anidadas según el locale resuelto.
+3. **Selectores**: Aplica cualquier selector de elemento o variante proporcionado en los argumentos.
+
+## Documentación relacionada
+
+- [Integración `intlayer`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/packages/astro-intlayer/intlayer.md)
+- [Hook `useIntlayer`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/packages/astro-intlayer/useIntlayer.md)
+- [Hook `useLocale`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/packages/astro-intlayer/useLocale.md)

package/docs/es/packages/astro-intlayer/useIntlayer.md

@@ -0,0 +1,98 @@
+---
+createdAt: 2026-09-19
+updatedAt: 2026-09-19
+title: Documentación del hook useIntlayer | astro-intlayer
+description: Descubre cómo usar el hook useIntlayer en componentes y scripts de cliente de Astro para acceder a contenido localizado.
+keywords:
+  - useIntlayer
+  - dictionary
+  - astro
+  - astro-intlayer
+  - Intlayer
+  - intlayer
+  - internacionalización
+  - documentación
+slugs:
+  - doc
+  - packages
+  - astro-intlayer
+  - useIntlayer
+history:
+  - version: 9.5.5
+    date: 2026-09-19
+    changes: "Doc inicial"
+author: aymericzip
+---
+
+# Documentación del hook useIntlayer
+
+El hook `useIntlayer` te permite obtener contenido de diccionario localizado por clave en aplicaciones Astro.
+
+Se puede llamar en dos contextos distintos utilizando la misma ruta de importación:
+
+1. **Servidor / Frontmatter**: Dentro de archivos `.astro`, resuelve automáticamente el contenido utilizando el locale de solicitud almacenado en `Astro.locals.intlayer`.
+2. **Navegador / Etiqueta `<script>` del cliente**: En scripts de cliente o componentes de frameworks de UI, resuelve a la implementación del store del lado del cliente (`vanilla-intlayer`).
+
+## Uso
+
+### En el Frontmatter de componentes Astro
+
+```astro fileName="src/pages/index.astro"
+---
+import { useIntlayer } from "astro-intlayer";
+
+const content = useIntlayer("home");
+---
+
+<main>
+  <h1>{content.title}</h1>
+  <p>{content.description}</p>
+</main>
+```
+
+### En bloques `<script>` del cliente
+
+```astro fileName="src/components/InteractiveWidget.astro"
+---
+import { useIntlayer } from "astro-intlayer";
+
+const content = useIntlayer("home");
+---
+
+<button id="alert-btn">{content.buttonText}</button>
+
+<script>
+  import { useIntlayer } from "astro-intlayer";
+
+  const content = useIntlayer("home");
+
+  document.getElementById("alert-btn")?.addEventListener("click", () => {
+    alert(content.buttonText);
+  });
+</script>
+```
+
+## Parámetros
+
+```ts
+useIntlayer(key, localeOrSelector?)
+```
+
+1. **`key`**: La clave única del diccionario (tal como se define en tus archivos de declaración `.content.ts`).
+2. **`localeOrSelector`** (opcional): Un locale específico o un objeto selector (`{ item }`, `{ variant }`, opcionalmente con `locale`). Si se proporciona, anula el locale detectado desde el contexto de la solicitud o el store del cliente.
+
+## Descripción
+
+El hook realiza las siguientes tareas:
+
+1. **Resolución de Locale**:
+   - En el servidor, lee el locale activo de `Astro.locals.intlayer` a través de un ámbito `AsyncLocalStorage` inicializado por `astro-intlayer/middleware`.
+   - En el navegador, lee el locale activo desde el almacenamiento/store del cliente.
+2. **Obtención del diccionario**: Inyecta el contenido del diccionario que coincide con la clave especificada.
+3. **Procesamiento de traducción**: Resuelve traducciones (`t()`), enumeraciones, condiciones y markdown en contenido listo para renderizar.
+
+## Documentación relacionada
+
+- [Integración `intlayer`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/packages/astro-intlayer/intlayer.md)
+- [Hook `useDictionary`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/packages/astro-intlayer/useDictionary.md)
+- [Hook `useLocale`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/packages/astro-intlayer/useLocale.md)

package/docs/es/packages/astro-intlayer/useLocale.md

@@ -0,0 +1,126 @@
+---
+createdAt: 2026-09-19
+updatedAt: 2026-09-19
+title: Documentación del hook useLocale | astro-intlayer
+description: Descubre cómo usar el hook useLocale en aplicaciones Astro para acceder y administrar el locale actual.
+keywords:
+  - useLocale
+  - locale
+  - astro
+  - astro-intlayer
+  - Intlayer
+  - intlayer
+  - internacionalización
+  - documentación
+slugs:
+  - doc
+  - packages
+  - astro-intlayer
+  - useLocale
+history:
+  - version: 9.5.5
+    date: 2026-09-19
+    changes: "Doc inicial"
+author: aymericzip
+---
+
+# Documentación del hook useLocale
+
+El hook `useLocale` de `astro-intlayer` proporciona acceso al locale de solicitud actual, al locale predeterminado configurado y a todos los locales disponibles en aplicaciones Astro.
+
+Se comporta de manera consistente en el frontmatter de `.astro` renderizado en el servidor y en los bloques `<script>` del lado del cliente.
+
+## Uso
+
+### En el Frontmatter de componentes (Renderizado en Servidor)
+
+```astro fileName="src/layouts/Layout.astro"
+---
+import { useLocale } from "astro-intlayer";
+import { getLocalizedUrl, getPathWithoutLocale } from "intlayer";
+
+const { locale, defaultLocale, availableLocales } = useLocale();
+const pathWithoutLocale = getPathWithoutLocale(Astro.url.pathname);
+---
+
+<!DOCTYPE html>
+<html lang={locale}>
+  <head>
+    <meta charset="utf-8" />
+    <title>Astro + Intlayer</title>
+  </head>
+  <body>
+    <header>
+      <span>Actual: {locale}</span>
+      <span>Predeterminado: {defaultLocale}</span>
+      <nav>
+        <ul>
+          {availableLocales.map((localeItem) => (
+            <li key={localeItem} className="p-1">
+              <a
+                href={getLocalizedUrl(pathWithoutLocale, localeItem)}
+                aria-current={localeItem === locale ? "page" : undefined}
+              >
+                {localeItem.toUpperCase()}
+              </a>
+            </li>
+          ))}
+        </ul>
+      </nav>
+    </header>
+    <slot />
+  </body>
+</html>
+```
+
+### En `<script>` del cliente (Interactivo)
+
+```astro fileName="src/components/LocaleSwitcher.astro"
+---
+import { useLocale } from "astro-intlayer";
+
+const { locale, availableLocales } = useLocale();
+---
+
+<select id="locale-select">
+  {availableLocales.map((loc) => (
+    <option value={loc} selected={loc === locale}>
+      {loc.toUpperCase()}
+    </option>
+  ))}
+</select>
+
+<script>
+  import { useLocale, setLocaleInStorage } from "astro-intlayer";
+
+  const { setLocale } = useLocale();
+
+  document.getElementById("locale-select")?.addEventListener("change", (e) => {
+    const target = e.target as HTMLSelectElement;
+    setLocale(target.value);
+  });
+</script>
+```
+
+## Valores de retorno
+
+El hook devuelve un objeto de tipo `UseLocaleResult`:
+
+| Propiedad          | Tipo                                   | Descripción                                                                           |
+| ------------------ | -------------------------------------- | ------------------------------------------------------------------------------------- |
+| `locale`           | `DeclaredLocales`                      | El locale activo.                                                                     |
+| `defaultLocale`    | `DeclaredLocales`                      | El locale de respaldo predeterminado configurado en `intlayer.config.ts`.             |
+| `availableLocales` | `DeclaredLocales[]`                    | Matriz de todos los locales admitidos configurados para el proyecto.                  |
+| `setLocale`        | `(locale: LocalesValues) => void`      | Función para actualizar el locale. (Interactiva en `<script>`, advierte durante SSR). |
+| `subscribe`        | `(callback: () => void) => () => void` | Se suscribe a los cambios de locale en el lado del cliente.                           |
+
+## Comportamiento Servidor vs Cliente
+
+- **Durante SSR / Renderizado en Servidor**: Una solicitud se procesa una vez con parámetros fijos. Llamar a `setLocale()` durante un renderizado de servidor no tiene efecto y emite una advertencia; el cambio de locale debe realizarse en el cliente o navegando a la URL del locale de destino.
+- **En scripts de cliente**: `setLocale` actualiza el store del cliente y actualiza las cookies persistidas o el almacenamiento local de acuerdo con tu configuración de Intlayer.
+
+## Documentación relacionada
+
+- [Integración `intlayer`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/packages/astro-intlayer/intlayer.md)
+- [Hook `useIntlayer`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/packages/astro-intlayer/useIntlayer.md)
+- [Hook `useDictionary`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/packages/astro-intlayer/useDictionary.md)

package/docs/es/packages/remix-intlayer/Intlayer.md

@@ -0,0 +1,77 @@
+---
+createdAt: 2026-09-19
+updatedAt: 2026-09-19
+title: Documentación del contexto Intlayer | remix-intlayer
+description: Vea cómo utilizar la clave y propiedad de contexto de solicitud Intlayer en aplicaciones Remix 3.
+keywords:
+  - Intlayer
+  - remix
+  - remix-3
+  - contexto
+  - RequestContext
+  - Internacionalización
+  - Documentación
+slugs:
+  - doc
+  - packages
+  - remix-intlayer
+  - Intlayer
+history:
+  - version: 9.5.5
+    date: 2026-09-19
+    changes: "Init doc"
+author: aymericzip
+---
+
+# Documentación del contexto Intlayer
+
+En `remix-intlayer`, `Intlayer` es la clave de `RequestContext` utilizada para acceder al estado de internacionalización dentro de los controladores de solicitudes de Remix 3.
+
+## Uso
+
+Cuando se ejecuta el middleware `intlayer()`, almacena un objeto `IntlayerState` en el contexto de solicitud bajo la clave `Intlayer`. Puedes recuperarlo dentro de cualquier controlador de ruta:
+
+```ts fileName="src/server.ts"
+import { createRouter } from "remix/router";
+import { intlayer, Intlayer } from "remix-intlayer";
+
+const router = createRouter({
+  middleware: [intlayer()],
+});
+
+router.get("/api/profile", (context) => {
+  // Acceso mediante context.get(Intlayer)
+  const { locale, defaultLocale, availableLocales } = context.get(Intlayer);
+
+  return Response.json({
+    locale,
+    defaultLocale,
+    availableLocales,
+  });
+});
+```
+
+También puedes acceder utilizando el atajo de propiedad directa `context.intlayer`:
+
+```ts
+router.get("/api/status", (context) => {
+  const currentLocale = context.intlayer.locale;
+  return Response.json({ status: "ok", locale: currentLocale });
+});
+```
+
+## Estructura de `IntlayerState`
+
+El objeto `IntlayerState` contiene:
+
+| Propiedad          | Tipo                | Descripción                                                               |
+| ------------------ | ------------------- | ------------------------------------------------------------------------- |
+| `locale`           | `DeclaredLocales`   | La locale resuelta para la solicitud actual.                              |
+| `defaultLocale`    | `DeclaredLocales`   | La locale predeterminada de respaldo configurada en `intlayer.config.ts`. |
+| `availableLocales` | `DeclaredLocales[]` | La lista de todas las locales admitidas configuradas para el proyecto.    |
+
+## Documentación relacionada
+
+- [Middleware `intlayer`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/packages/remix-intlayer/intlayerMiddleware.md)
+- [Hook `useLocale`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/packages/remix-intlayer/useLocale.md)
+- [Hook `useIntlayer`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/packages/remix-intlayer/useIntlayer.md)