@intlayer/docs 9.4.0-canary.0 → 9.4.1

package/docs/es/packages/intlayer/getDictionary.md

@@ -0,0 +1,155 @@
+---
+createdAt: 2026-08-23
+updatedAt: 2026-08-23
+title: Documentación de la función getDictionary | intlayer
+description: Consulta cómo usar la función getDictionary para el paquete intlayer
+keywords:
+  - getDictionary
+  - dictionary
+  - interpreter
+  - content
+  - Intlayer
+  - intlayer
+  - Internationalization
+  - Documentation
+  - JavaScript
+  - TypeScript
+slugs:
+  - doc
+  - packages
+  - intlayer
+  - getDictionary
+history:
+  - version: 9.4.0
+    date: 2026-08-23
+    changes: "Initial documentation"
+author: aymericzip
+---
+
+# Documentación: Función `getDictionary` en `intlayer`
+
+## Descripción
+
+La función `getDictionary` interpreta un objeto de diccionario **que tú mismo pasas** y devuelve su contenido resuelto para una locale determinada. Recorre el contenido en una sola pasada y aplica cada plugin intérprete según sea necesario, resolviendo traducciones `t()`, enumeraciones, condiciones, inserciones, anidamiento, markdown, HTML y nodos de archivo.
+
+A diferencia de [`getIntlayer`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/packages/intlayer/getIntlayer.md), que busca un diccionario por clave en el registro generado, `getDictionary` toma el diccionario en sí. Esto la convierte en la herramienta correcta para contenido construido en tiempo de ejecución, obtenido de una API o CMS, o declarado en línea en una prueba.
+
+**Características principales:**
+
+- Funciona con cualquier objeto que siga la estructura del diccionario (`{ key, content }`)
+- También acepta un grupo de diccionario calificado (colecciones, variantes) junto con un selector
+- Totalmente tipado: el objeto devuelto refleja el `content` que pasaste
+- Acepta plugins intérpretes personalizados
+
+---
+
+## Firma de Función
+
+```typescript
+getDictionary(
+  dictionary: Dictionary | QualifiedDictionaryGroup, // Requerido
+  localeOrSelector?: LocalesValues | DictionarySelector, // Opcional
+  plugins?: Plugins[]                                // Opcional
+): DeepTransformContent<...>
+```
+
+---
+
+## Parámetros
+
+- `dictionary: Dictionary | QualifiedDictionaryGroup`
+  - **Description**: El diccionario (o grupo de diccionario calificado) a interpretar.
+  - **Type**: `Dictionary | QualifiedDictionaryGroup`
+  - **Required**: Yes
+
+- `localeOrSelector: LocalesValues | DictionarySelector`
+  - **Description**: La locale para interpretar el contenido, o un objeto selector (`{ item }`, `{ variant }`, opcionalmente con `locale`). Ver [dynamic dictionaries](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/dynamic_dictionaries/index.md).
+  - **Type**: `LocalesValues | DictionarySelector`
+  - **Required**: No (Optional) — defaults to the configured `defaultLocale`.
+
+- `plugins: Plugins[]`
+  - **Description**: Un array de transformadores de nodos que definen cómo se interpretan los nodos reconocidos. Si se omite, se utiliza el conjunto predeterminado de plugins de intérprete.
+  - **Type**: `Plugins[]`
+  - **Required**: No (Optional)
+
+### Retorna
+
+- **Type**: El contenido interpretado del diccionario.
+- **Description**: El `content` que pasaste, con cada nodo de Intlayer resuelto para la locale solicitada. Para un grupo de colección sin un selector `item`, se devuelve una matriz ordenada de entradas interpretadas; `null` se devuelve cuando el selector no apunta a nada.
+
+---
+
+## Ejemplo de uso
+
+### Uso Básico
+
+```typescript codeFormat={["typescript", "esm", "commonjs"]}
+import { getDictionary, t } from "intlayer";
+
+const content = getDictionary(
+  {
+    key: "my_key",
+    content: {
+      greeting: t({
+        es: "Hola",
+        en: "Hello",
+        fr: "Bonjour",
+      }),
+    },
+  },
+  "fr"
+);
+
+console.log(content.greeting); // "Bonjour"
+```
+
+### Interpretación de contenido obtenido en tiempo de ejecución
+
+```typescript
+import { getDictionary, type Dictionary } from "intlayer";
+
+const remoteDictionary: Dictionary = await fetch("/api/cms/banner").then(
+  (res) => res.json()
+);
+
+const banner = getDictionary(remoteDictionary, "fr");
+```
+
+### Con un selector
+
+```typescript
+import { getDictionary } from "intlayer";
+
+// Un grupo de diccionario calificado se resuelve en una única entrada…
+const secondItem = getDictionary(blogPostGroup, { item: 2, locale: "fr" });
+
+// …o en un array ordenado cuando no se proporciona `item`
+const allItems = getDictionary(blogPostGroup, { locale: "fr" });
+```
+
+---
+
+## Funciones Relacionadas
+
+- [`getIntlayer`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/packages/intlayer/getIntlayer.md): Misma interpretación, pero el diccionario se busca por clave en el registro generado.
+- [`getDictionaryAsync`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/packages/intlayer/getDictionaryAsync.md): Contraparte para mapas de cargadores por locale.
+- [`useDictionary`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/packages/react-intlayer/useDictionary.md): El equivalente del hook de React, leyendo el locale del proveedor.
+
+---
+
+## TypeScript
+
+```typescript
+function getDictionary<
+  const T extends Dictionary | QualifiedDictionaryGroup,
+  const A extends LocalesValues | DictionarySelector = DeclaredLocales,
+>(
+  dictionary: T,
+  localeOrSelector?: A,
+  plugins?: Plugins[]
+): DeepTransformContent<
+  ResolveQualifiedDictionaryContent<T, A>,
+  IInterpreterPluginState,
+  ExtractSelectorLocale<A>
+>;
+```

package/docs/es/packages/intlayer/getDictionaryAsync.md

@@ -0,0 +1,166 @@
+---
+createdAt: 2026-08-23
+updatedAt: 2026-08-23
+title: Documentación de la función getDictionaryAsync | intlayer
+description: Ve cómo usar la función getDictionaryAsync para el paquete intlayer
+keywords:
+  - getDictionaryAsync
+  - dictionary
+  - dynamic dictionaries
+  - loader map
+  - bundle optimization
+  - Intlayer
+  - intlayer
+  - Internationalization
+  - Documentation
+  - JavaScript
+  - TypeScript
+slugs:
+  - doc
+  - packages
+  - intlayer
+  - getDictionaryAsync
+history:
+  - version: 9.4.0
+    date: 2026-08-23
+    changes: "Initial documentation"
+author: aymericzip
+---
+
+# Documentación: Función `getDictionaryAsync` en `intlayer`
+
+## Descripción
+
+La función `getDictionaryAsync` carga un **único chunk de locale** de un diccionario y devuelve su contenido interpretado.
+
+Es el contraparte de [`getDictionary`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/packages/intlayer/getDictionary.md) para los mapas de loader por locale emitidos en `.intlayer/dynamic_dictionaries/`: en lugar de recibir un diccionario que contiene todos los locales, recibe el mapa de loader y espera solo el chunk que el locale solicitado necesita.
+
+> En el código de aplicación normalmente llamas [`getIntlayerAsync`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/packages/intlayer/getIntlayerAsync.md), no esta función. Los [plugins de build](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/bundle_optimization.md) reescriben cada llamada `getIntlayerAsync('key', locale)` en una `getDictionaryAsync(loaderMap, 'key', locale)`. `getDictionaryAsync` se exporta para loaders personalizados y para herramientas que construyen sus propios mapas de loader.
+
+**Características Principales:**
+
+- Carga solo el chunk de locale que se solicita
+- Soporta mapas de loader simples (`locale → loader`) y calificados (`locale → qualifierId → loader`)
+- Deduplica cargas concurrentes del mismo chunk y cachea el contenido resuelto
+- Las cargas fallidas se evictan del caché para que una llamada posterior reintente el chunk
+
+---
+
+## Firma de la función
+
+```typescript
+getDictionaryAsync(
+  dictionaryLoaders: PlainDynamicLoaderMap | QualifiedDynamicLoaderMap, // Requerido
+  key: string,                                           // Requerido
+  localeOrSelector?: LocalesValues | DictionarySelector, // Opcional
+  plugins?: Plugins[]                                    // Opcional
+): Promise<DeepTransformContent<...>>
+```
+
+---
+
+## Parámetros
+
+- `dictionaryLoaders: PlainDynamicLoaderMap | QualifiedDynamicLoaderMap`
+  - **Description**: El mapa de cargadores por locale. Los mapas simples asocian un locale con un cargador; los mapas calificados (utilizados por colecciones y variantes) asocian un locale con un id de calificador, luego con un cargador. Para un mapa calificado, solo se cargan los chunk(s) que el selector apunta.
+  - **Type**: `PlainDynamicLoaderMap<T> | QualifiedDynamicLoaderMap`
+  - **Required**: Yes
+
+- `key: string`
+  - **Description**: La clave del diccionario, utilizada para namespace del caché de chunks.
+  - **Type**: `string`
+  - **Required**: Yes
+
+- `localeOrSelector: LocalesValues | DictionarySelector`
+  - **Description**: El locale para interpretar el contenido, o un objeto selector (`{ item }`, `{ variant }`, opcionalmente con `locale`). Ver [diccionarios dinámicos](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/dynamic_dictionaries/index.md).
+  - **Type**: `LocalesValues | DictionarySelector`
+  - **Required**: No (Optional) — defaults to the configured `defaultLocale`.
+
+- `plugins: Plugins[]`
+  - **Description**: Transformadores de nodos. Por defecto el conjunto base del intérprete.
+  - **Type**: `Plugins[]`
+  - **Required**: No (Optional)
+
+### Retorna
+
+- **Type**: `Promise<Content>` — una promesa que se resuelve al contenido interpretado del chunk cargado.
+- **Description**: Se resuelve a `null` cuando el mapa no emite ningún chunk para la locale solicitada ni para ninguno de sus fallbacks, reflejando cómo se resuelve una coordenada calificada faltante.
+
+---
+
+## Ejemplo de Uso
+
+### Con un mapa de cargador generado
+
+```typescript codeFormat={["typescript", "esm", "commonjs"]}
+import { getDictionaryAsync } from "intlayer";
+import appLoaderMap from "../.intlayer/dynamic_dictionaries/app";
+
+const { title } = await getDictionaryAsync(appLoaderMap, "app", "fr");
+```
+
+### Con un mapa de cargadores personalizado
+
+```typescript
+import { getDictionaryAsync } from "intlayer";
+
+const loaderMap = {
+  en: () => import("./banner.en.json").then((mod) => mod.default),
+  fr: () => import("./banner.fr.json").then((mod) => mod.default),
+};
+
+const banner = await getDictionaryAsync(loaderMap, "banner", "fr");
+```
+
+### Con un selector en un mapa calificado
+
+```typescript
+import { getDictionaryAsync } from "intlayer";
+
+const promoBanner = await getDictionaryAsync(bannerLoaderMap, "banner", {
+  variant: "black-friday",
+  locale: "fr",
+});
+```
+
+---
+
+## Notas de comportamiento
+
+### Almacenamiento en caché y deduplicación
+
+El caché almacena la **promise** de cada triple `key + locale + selector`, por lo que las llamadas concurrentes para el mismo chunk esperan una única carga. Una carga rechazada se elimina del caché, por lo que un chunk que falla se reintenta en la siguiente llamada en lugar de reproducir el mismo error indefinidamente.
+
+### Fallback de locale
+
+Un mapa de loader simple se recorre a lo largo de la misma cadena de fallback que en modo síncrono: primero la locale solicitada, luego sus fallbacks, y luego `null` si ninguno emitió un chunk.
+
+---
+
+## Funciones Relacionadas
+
+- [`getIntlayerAsync`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/packages/intlayer/getIntlayerAsync.md): La función que las aplicaciones llaman; los plugins de compilación la reescriben en `getDictionaryAsync`.
+- [`getDictionary`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/packages/intlayer/getDictionary.md): Contraparte síncrona que toma un diccionario completo.
+- [Diccionarios dinámicos](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/dynamic_dictionaries/index.md): Colecciones y variantes, y los mapas de cargadores que generan.
+
+---
+
+## TypeScript
+
+```typescript
+function getDictionaryAsync<
+  const T extends Dictionary,
+  const A extends LocalesValues | DictionarySelector = DeclaredLocales,
+>(
+  dictionaryLoaders: PlainDynamicLoaderMap<T> | QualifiedDynamicLoaderMap,
+  key: string,
+  localeOrSelector?: A,
+  plugins?: Plugins[]
+): Promise<
+  DeepTransformContent<
+    T["content"],
+    IInterpreterPluginState,
+    ExtractSelectorLocale<A>
+  >
+>;
+```

package/docs/es/packages/intlayer/getEnumeration.md

@@ -31,6 +31,8 @@ author: aymericzip
 
 La función `getEnumeration` recupera contenido correspondiente a una cantidad específica basada en condiciones predefinidas en un objeto de enumeración. Las condiciones se definen como claves, y su prioridad está determinada por su orden en el objeto.
 
+Para más detalles sobre cómo declarar enumeraciones, consulta la [documentación de Enumeración](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/dictionary/enumeration.md).
+
 ## Parámetros
 
 - `enumerationContent: QuantityContent<Content>`

package/docs/es/packages/intlayer/getIntlayer.md

@@ -0,0 +1,197 @@
+---
+createdAt: 2026-08-23
+updatedAt: 2026-08-23
+title: Documentación de la Función getIntlayer | intlayer
+description: Ve cómo usar la función getIntlayer para el paquete intlayer
+keywords:
+  - getIntlayer
+  - dictionary
+  - content
+  - selector
+  - Intlayer
+  - intlayer
+  - Internationalization
+  - Documentation
+  - JavaScript
+  - TypeScript
+slugs:
+  - doc
+  - packages
+  - intlayer
+  - getIntlayer
+history:
+  - version: 9.4.0
+    date: 2026-08-23
+    changes: "Initial documentation"
+author: aymericzip
+---
+
+# Documentación: Función `getIntlayer` en `intlayer`
+
+## Descripción
+
+La función `getIntlayer` selecciona un diccionario por su clave y devuelve su contenido interpretado para una locale determinada. Es el equivalente agnóstico del framework del hook `useIntlayer`: mismo contenido, mismos selectores, pero utilizable en cualquier lugar donde un contexto de React no esté disponible — scripts de Node, funciones de servidor, cargadores de rutas, constructores de metadatos, manejadores de Express/Fastify, pruebas.
+
+Lee los diccionarios generados por Intlayer en `.intlayer/`, por lo que el argumento `key` está tipado y autocompletado a partir de tus propias declaraciones de contenido, y el objeto devuelto está completamente tipado hasta cada hoja.
+
+**Características principales:**
+
+- Claves de diccionario tipadas y contenido devuelto tipado
+- Interpreta cada nodo de contenido (`t()`, `enu()`, `cond()`, `insert()`, `nest()`, `md()`, `html()`, `file()`, `gender()`)
+- Acepta una locale u un objeto selector (colecciones, variantes)
+- Los resultados se memorizan por `key + locale + selector`
+- Se retrocede a un proxy seguro en desarrollo cuando falta un diccionario, en lugar de fallar
+
+---
+
+## Firma de función
+
+```typescript
+getIntlayer(
+  key: DictionaryKeys,                        // Requerido
+  localeOrSelector?: LocalesValues | DictionarySelector, // Opcional
+  plugins?: Plugins[]                         // Opcional
+): DeepTransformContent<...>
+```
+
+---
+
+## Parámetros
+
+- `key: DictionaryKeys`
+  - **Description**: The key of the dictionary to read, as declared in your content files.
+  - **Type**: `DictionaryKeys` — a union of every declared dictionary key.
+  - **Required**: Yes
+
+- `localeOrSelector: LocalesValues | DictionarySelector`
+  - **Description**: The locale to interpret the content with, or a selector object for [dynamic dictionaries](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/dynamic_dictionaries/index.md).
+    - `'fr'` — a locale
+    - `{ item: 2 }` — a [collection](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/dynamic_dictionaries/collections.md) item (omit `item` to get every item as an array)
+    - `{ variant: 'black-friday' }` — a named [variant](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/dynamic_dictionaries/variants.md) (omit for the `default` one)
+    - `{ variant: { id: 'prod_abc', userId: '123' } }` — a structured variant
+    - Any selector can carry a locale: `{ item: 2, locale: 'fr' }`
+  - **Type**: `LocalesValues | DictionarySelector`
+  - **Required**: No (Optional) — defaults to the configured `defaultLocale`.
+
+- `plugins: Plugins[]`
+  - **Description**: Custom node transformers replacing the base interpreter plugins. Advanced use only; omit it to keep the default behaviour.
+  - **Type**: `Plugins[]`
+  - **Required**: No (Optional)
+
+### Retorna
+
+- **Type**: El contenido interpretado del diccionario, tipado desde tu declaración.
+- **Description**: Un objeto plano que refleja el campo `content` de tu diccionario, donde cada nodo de Intlayer ha sido resuelto a su valor final para la locale solicitada.
+
+---
+
+## Ejemplo de uso
+
+### Uso Básico
+
+```typescript fileName="src/app.content.ts" codeFormat="typescript"
+import { t, type Dictionary } from "intlayer";
+
+const appContent = {
+  key: "app",
+  content: {
+    title: t({
+      es: "Hola",
+      en: "Hello",
+      fr: "Bonjour",
+    }),
+  },
+} satisfies Dictionary;
+
+export default appContent;
+```
+
+```typescript codeFormat={["typescript", "esm", "commonjs"]}
+import { getIntlayer } from "intlayer";
+
+const { title } = getIntlayer("app", "es"); // "Hola"
+```
+
+### Sin locale
+
+Omitir el locale interpreta el contenido con el `defaultLocale` declarado en tu [configuración](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/configuration.md).
+
+```typescript
+import { getIntlayer } from "intlayer";
+
+const { title } = getIntlayer("app"); // Interpretado con el locale por defecto
+```
+
+### Dentro de un manejador del servidor
+
+```typescript fileName="src/routes/greeting.ts" codeFormat="typescript"
+import { getIntlayer, getLocale } from "intlayer";
+
+export const greetingHandler = async (request: Request) => {
+  const locale = await getLocale({
+    getHeader: (name) => request.headers.get(name) ?? undefined,
+  });
+
+  const { title } = getIntlayer("app", locale);
+
+  return Response.json({ title });
+};
+```
+
+### Con un selector (colecciones y variantes)
+
+```typescript
+import { getIntlayer } from "intlayer";
+
+// Un elemento único de la colección
+const secondPost = getIntlayer("blog-post", { item: 2, locale: "fr" });
+
+// Todos los elementos de la colección, como un array ordenado
+const allPosts = getIntlayer("blog-post", { locale: "fr" });
+
+// Una variante nombrada
+const banner = getIntlayer("banner", { variant: "black-friday", locale: "fr" });
+```
+
+---
+
+## Notas de Comportamiento
+
+### Caché
+
+Los resultados se memorizan en un caché a nivel de módulo, con clave `key + locale + selector`. Llamar a `getIntlayer("app", "fr")` repetidamente interpreta el diccionario una sola vez y devuelve el mismo objeto después.
+
+### Diccionarios faltantes
+
+En desarrollo, solicitar una clave que no tiene un diccionario generado registra una advertencia una vez y devuelve un proxy de respaldo seguro: leer `content.title` produce la cadena `"app.title"` en lugar de lanzar una excepción. Esto mantiene una página utilizable mientras se corrige la declaración faltante. Ejecuta la compilación de Intlayer (o el servidor de desarrollo) para que se genere el diccionario.
+
+### Tamaño del bundle
+
+`getIntlayer` lee el diccionario fusionado, que contiene **todos** los locales. En bundles del cliente, los [plugins de compilación](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/bundle_optimization.md) reescriben la llamada para que solo se envíe el contenido requerido. Cuando lees contenido fuera de la renderización (metadatos, loaders, funciones de servidor) y deseas que un único local se cargue bajo demanda, utiliza [`getIntlayerAsync`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/packages/intlayer/getIntlayerAsync.md) en su lugar.
+
+---
+
+## Funciones Relacionadas
+
+- [`getIntlayerAsync`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/packages/intlayer/getIntlayerAsync.md): Contraparte asincrónica que carga un único chunk de locale.
+- [`getDictionary`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/packages/intlayer/getDictionary.md): Interpreta un objeto de diccionario que pasas tú mismo, en lugar de uno buscado por clave.
+- [`useIntlayer`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/packages/react-intlayer/useIntlayer.md): El equivalente del hook de React, leyendo el locale del provider.
+
+---
+
+## TypeScript
+
+```typescript
+function getIntlayer<
+  const T extends DictionaryKeys,
+  const A extends LocalesValues | DictionarySelector = DeclaredLocales,
+>(
+  key: T,
+  localeOrSelector?: A,
+  plugins?: Plugins[]
+): DeepTransformContent<
+  DictionaryRegistryResult<T, A>,
+  IInterpreterPluginState,
+  ExtractSelectorLocale<A>
+>;
+```

package/docs/es/packages/intlayer/getIntlayerAsync.md

@@ -0,0 +1,141 @@
+---
+createdAt: 2026-08-23
+updatedAt: 2026-08-23
+title: Documentación de la función getIntlayerAsync | intlayer
+description: Consulta cómo utilizar la función getIntlayerAsync del paquete intlayer
+keywords:
+  - getIntlayerAsync
+  - dictionary
+  - dynamic import
+  - metadata
+  - bundle optimization
+  - Intlayer
+  - intlayer
+  - Internationalization
+  - Documentation
+  - JavaScript
+  - TypeScript
+slugs:
+  - doc
+  - packages
+  - intlayer
+  - getIntlayerAsync
+history:
+  - version: 9.4.0
+    date: 2026-08-23
+    changes: "Initial documentation"
+author: aymericzip
+---
+
+# Documentación: Función `getIntlayerAsync` en `intlayer`
+
+## Descripción
+
+La función `getIntlayerAsync` selecciona un diccionario por su clave y resuelve su contenido para una localidad determinada, **cargando solo esa localidad**.
+
+Es la contraparte asincrónica de [`getIntlayer`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/packages/intlayer/getIntlayer.md), destinada a los lugares donde se lee un diccionario fuera del renderizado — constructores de rutas `head` / metadatos, loaders, funciones de servidor.
+
+Mientras que `getIntlayer` carga el diccionario fusionado que contiene todas las localidades, los [plugins de construcción](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/bundle_optimization.md) (`@intlayer/babel`, `@intlayer/swc`) reescriben esta llamada en `getDictionaryAsync(loaderMap, key, locale)`, apuntando a los fragmentos por localidad en `.intlayer/dynamic_dictionaries/`. El bundle por lo tanto solo carga la localidad realmente solicitada.
+
+Sin esos plugins — una construcción no optimizada — la llamada se resuelve a través del registro de diccionarios sincrónico en su lugar: el mismo contenido, sin la división por localidad.
+
+**Características Clave:**
+
+- Las mismas claves tipadas, selectores y contenido devuelto que `getIntlayer`
+- Carga solo el fragmento de localidad solicitado en construcciones optimizadas
+- Las llamadas concurrentes para el mismo fragmento comparten una única carga
+- Seguro de usar en constructores de metadatos `async`, loaders y funciones de servidor
+
+---
+
+## Firma de Función
+
+```typescript
+getIntlayerAsync(
+  key: DictionaryKeys,                        // Requerido
+  localeOrSelector?: LocalesValues | DictionarySelector, // Opcional
+  plugins?: Plugins[]                         // Opcional
+): Promise<DeepTransformContent<...>>
+```
+
+---
+
+## Parámetros
+
+- `key: DictionaryKeys`
+  - **Description**: La clave del diccionario a leer, tal como se declara en tus archivos de contenido.
+  - **Type**: `DictionaryKeys` — una unión de cada clave de diccionario declarada.
+  - **Required**: Yes
+
+- `localeOrSelector: LocalesValues | DictionarySelector`
+  - **Description**: La locale para interpretar el contenido, o un objeto selector para [diccionarios dinámicos](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/dynamic_dictionaries/index.md).
+    - `'fr'` — una locale
+    - `{ item: 2 }` — un elemento de [colección](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/dynamic_dictionaries/collections.md) (omite `item` para obtener cada elemento como un array)
+    - `{ variant: 'black-friday' }` — una [variante](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/dynamic_dictionaries/variants.md) nombrada (omite para la `default`)
+    - `{ variant: { id: 'prod_abc', userId: '123' } }` — una variante estructurada
+    - Cualquier selector puede llevar una locale: `{ item: 2, locale: 'fr' }`
+  - **Type**: `LocalesValues | DictionarySelector`
+  - **Required**: No (Optional) — por defecto la `defaultLocale` configurada.
+
+- `plugins: Plugins[]`
+  - **Description**: Transformadores de nodos personalizados que reemplazan los plugins base del intérprete. Solo uso avanzado.
+  - **Type**: `Plugins[]`
+  - **Required**: No (Optional)
+
+### Devoluciones
+
+- **Type**: `Promise<Content>` — una promesa que se resuelve al contenido interpretado del diccionario, tipado desde tu declaración.
+
+---
+
+## Ejemplo de uso
+
+### Uso Básico
+
+```typescript codeFormat={["typescript", "esm", "commonjs"]}
+import { getIntlayerAsync } from "intlayer";
+
+const { title } = await getIntlayerAsync("app", "fr"); // "Bonjour"
+```
+
+---
+
+## `getIntlayer` vs `getIntlayerAsync`
+
+|                     | [`getIntlayer`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/packages/intlayer/getIntlayer.md) | `getIntlayerAsync`                                 |
+| ------------------- | --------------------------------------------------------------------------------------------------------------- | -------------------------------------------------- |
+| Devuelve            | El contenido                                                                                                    | Una promesa del contenido                          |
+| Diccionario cargado | El diccionario fusionado (todas las locales)                                                                    | El chunk de la locale solicitada únicamente        |
+| Mejor para          | Renderizado, rutas de código sincrónicas                                                                        | Metadatos, loaders, funciones del servidor         |
+| ¿Requiere plugin?   | No                                                                                                              | No — la división por locale requiere plugins build |
+
+Ambos aceptan los mismos argumentos y devuelven el mismo contenido: cambiar de uno a otro solo cambia **cuándo** y **cuánto** se carga.
+
+---
+
+## Funciones Relacionadas
+
+- [`getIntlayer`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/packages/intlayer/getIntlayer.md): Equivalente síncrono que lee el diccionario combinado.
+- [`getDictionaryAsync`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/packages/intlayer/getDictionaryAsync.md): La función de nivel inferior que los plugins de compilación reescriben en esta llamada.
+- [`getLocale`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/packages/intlayer/getLocale.md): Detecta el locale de una solicitud entrante.
+
+---
+
+## TypeScript
+
+```typescript
+function getIntlayerAsync<
+  const T extends DictionaryKeys,
+  const A extends LocalesValues | DictionarySelector = DeclaredLocales,
+>(
+  key: T,
+  localeOrSelector?: A,
+  plugins?: Plugins[]
+): Promise<
+  DeepTransformContent<
+    DictionaryRegistryResult<T, A>,
+    IInterpreterPluginState,
+    ExtractSelectorLocale<A>
+  >
+>;
+```