@intlayer/docs 8.10.0-canary.1 → 8.10.1

package/docs/es/dictionary/markdown.md

@@ -95,34 +95,34 @@ Puede declarar contenido Markdown usando la función `md` o simplemente como una
     ```
 
   </Tab>
-  <Tab label="Detección Automática" value="automatic-detection">
-    Si la cadena contiene indicadores comunes de Markdown (como encabezados, listas, enlaces, etc.), Intlayer la transformará automáticamente.
+  <Tab label="Archivos Externos" value="external-files">
+    Importe archivos `.md` directamente usando la función `file`.
 
     ```typescript fileName="markdownDictionary.content.ts"
+    import { md, file, t } from "intlayer";
+
     export default {
       key: "app",
-      contentAutoTransformation: true, // Habilitar detección automática de contenido Markdown - Se puede configurar globalmente en intlayer.config.ts
       content: {
-        myMarkdownContent: "## Mi título \n\nLorem Ipsum",
+        content: t({
+          en: md(file("./myMarkdown.en.md")),
+          es: md(file("./myMarkdown.es.md")),
+        }),
       },
     };
     ```
 
   </Tab>
 
-  <Tab label="Archivos Externos" value="external-files">
-    Importe archivos `.md` directamente usando la función `file`.
+  <Tab label="Detección Automática" value="automatic-detection">
+    Si la cadena contiene indicadores comunes de Markdown (como encabezados, listas, enlaces, etc.), Intlayer la transformará automáticamente.
 
     ```typescript fileName="markdownDictionary.content.ts"
-    import { md, file, t } from "intlayer";
-
     export default {
       key: "app",
+      contentAutoTransformation: true, // Habilitar detección automática de contenido Markdown - Se puede configurar globalmente en intlayer.config.ts
       content: {
-        content: t({
-          en: md(file("./myMarkdown.en.md")),
-          es: md(file("./myMarkdown.es.md")),
-        }),
+        myMarkdownContent: "## Mi título \n\nLorem Ipsum",
       },
     };
     ```
@@ -130,8 +130,6 @@ Puede declarar contenido Markdown usando la función `md` o simplemente como una
   </Tab>
 </Tabs>
 
----
-
 ## Renderización de Markdown
 
 Intlayer proporciona dos formas independientes de renderizar Markdown:
@@ -147,7 +145,7 @@ La renderización de Markdown admite **MDX** — use cualquier componente JSX/fr
 ### 1. Renderización Automática (a través de `useIntlayer`)
 
 <Tabs group="framework">
-  <Tab label="React / Next.js" value="react">
+  <Tab label="React" value="react">
     Los nodos Markdown se pueden renderizar directamente como JSX.
 
     ```tsx fileName="App.tsx"
@@ -197,6 +195,57 @@ La renderización de Markdown admite **MDX** — use cualquier componente JSX/fr
     {myMarkdownContent.metadata.title}
     ```
 
+  </Tab>
+  <Tab label="Next.js" value="nextjs">
+    Los nodos Markdown se pueden renderizar directamente como JSX.
+
+    ```tsx fileName="App.tsx"
+    import { useIntlayer } from "next-intlayer";
+    import { MarkdownProvider } from "next-intlayer/markdown";
+
+    const AppContent = () => {
+      const { myMarkdownContent } = useIntlayer("app");
+
+      return <div>{myMarkdownContent}</div>;
+    };
+
+    const App = () => (
+      <MarkdownProvider
+        components={{
+          h1: ({ children }) => <h1 style={{ color: "red" }}>{children}</h1>,
+          MyButton: (props) => <button {...props} />, // Componente MDX
+        }}
+      >
+        <AppContent />
+      </MarkdownProvider>
+    );
+    ```
+
+    > Si `MarkdownProvider` no está presente, Intlayer renderizará el markdown usando el analizador por defecto de Markdown a JSX.
+
+    También puede proporcionar anulaciones locales para nodos específicos utilizando el método `.use()`:
+
+    ```tsx
+    {myMarkdownContent.use({
+      h1: ({ children }) => <h1 style={{ color: "red" }}>{children}</h1>,
+    })}
+    ```
+
+    Puede recuperar el Markdown como cadena:
+
+    ```tsx
+    {myMarkdownContent.value}
+    {String(myMarkdownContent)}
+    {myMarkdownContent.toString()}
+    ```
+
+    Y puede acceder a los metadatos de su markdown así:
+
+    ```tsx
+    {myMarkdownContent.metadata}
+    {myMarkdownContent.metadata.title}
+    ```
+
   </Tab>
   <Tab label="Vue" value="vue">
     En Vue, el contenido Markdown se puede renderizar usando la etiqueta incorporada `component` o directamente como un nodo.
@@ -441,7 +490,7 @@ La renderización de Markdown admite **MDX** — use cualquier componente JSX/fr
 Estas utilidades renderizan **únicamente cadenas Markdown puras** y son independientes de `useIntlayer`. Úselas cuando necesite renderizar Markdown de fuentes que no sean sus diccionarios.
 
 <Tabs group="framework">
-  <Tab label="React / Next.js" value="react">
+  <Tab label="React" value="react">
   
     #### Componente `<MarkdownRenderer />`
 
@@ -479,6 +528,45 @@ Estas utilidades renderizan **únicamente cadenas Markdown puras** y son indepen
     const jsx = renderMarkdown("# Mi Título", { forceBlock: true });
     ```
 
+  </Tab>
+  <Tab label="Next.js" value="nextjs">
+  
+    #### Componente `<MarkdownRenderer />`
+
+    Renderiza una cadena Markdown con opciones específicas.
+
+    ```tsx
+    import { MarkdownRenderer } from "next-intlayer/markdown";
+
+    <MarkdownRenderer forceBlock={true} tagfilter={true}>
+      {"# Mi Título"}
+    </MarkdownRenderer>
+    ```
+
+    #### Hook `useMarkdownRenderer()`
+
+    Obtenga una función de renderizado preconfigurada.
+
+    ```tsx
+    import { useMarkdownRenderer } from "next-intlayer/markdown";
+
+    const renderMarkdown = useMarkdownRenderer({
+      forceBlock: true,
+      components: { h1: (props) => <h1 {...props} className="custom" /> }
+    });
+
+    return renderMarkdown("# Mi Título");
+    ```
+
+    #### Utilidad `renderMarkdown()`
+    Utilidad independiente para renderizar fuera de los componentes.
+
+    ```tsx
+    import { renderMarkdown } from "next-intlayer/markdown";
+
+    const jsx = renderMarkdown("# Mi Título", { forceBlock: true });
+    ```
+
   </Tab>
   <Tab label="Vue" value="vue">
 
@@ -608,14 +696,12 @@ Estas utilidades renderizan **únicamente cadenas Markdown puras** y son indepen
   </Tab>
 </Tabs>
 
----
-
 ## Configuración Global con `MarkdownProvider`
 
 `MarkdownProvider` (o su equivalente en el framework) configura el proceso de renderización Markdown para toda su aplicación. Esto se aplica tanto a la renderización automática de `useIntlayer` como a las utilidades auxiliares. Las opciones configuradas aquí son las predeterminadas — `.use()` las anula a nivel de nodo.
 
 <Tabs group="framework">
-  <Tab label="React / Next.js" value="react">
+  <Tab label="React" value="react">
 
     ```tsx fileName="AppProvider.tsx"
     import { MarkdownProvider } from "react-intlayer/markdown";
@@ -633,6 +719,7 @@ Estas utilidades renderizan **únicamente cadenas Markdown puras** y son indepen
     );
     ```
 
+
     > MDX es compatible — cualquier nombre de componente usado dentro de su Markdown (ej. `<MyCustomJSXComponent />`) se resuelve contra el mapeo de `components`.
 
     También puede usar su propio renderizador de markdown:
@@ -643,6 +730,7 @@ Estas utilidades renderizan **únicamente cadenas Markdown puras** y son indepen
     export const AppProvider = ({ children }) => (
       <MarkdownProvider
         renderMarkdown={async (md) => {
+          // Use dynamic import to reduce the bundle size of your application
           const { renderMarkdown } = await import('react-intlayer/markdown');
           return renderMarkdown(md);
         }}
@@ -654,6 +742,48 @@ Estas utilidades renderizan **únicamente cadenas Markdown puras** y son indepen
 
     > Importar su renderizador de Markdown dinámicamente es una buena manera de reducir el tamaño del paquete de su aplicación.
 
+  </Tab>
+  <Tab label="Next.js" value="nextjs">
+
+    ```tsx fileName="AppProvider.tsx"
+    import { MarkdownProvider } from "next-intlayer/markdown";
+
+    export const AppProvider = ({ children }) => (
+      <MarkdownProvider
+        components={{
+          h1: (props) => <h1 style={{color: 'green'}} {...props} />,
+          a: ({ href, ...props }) => <a style={{color: 'red'}} {...props} />,
+          MyCustomJSXComponent: (props) => <span style={{color: 'red'}} {...props} />,
+        }}
+      >
+        {children}
+      </MarkdownProvider>
+    );
+    ```
+
+
+    > MDX es compatible — cualquier nombre de componente usado dentro de su Markdown (ej. `<MyCustomJSXComponent />`) se resuelve contra el mapeo de `components`.
+
+    También puede usar su propio renderizador de markdown:
+
+    ```tsx fileName="AppProvider.tsx"
+    import { MarkdownProvider } from "next-intlayer/markdown";
+
+    export const AppProvider = ({ children }) => (
+      <MarkdownProvider
+        renderMarkdown={async (md) => {
+          // Use dynamic import to reduce the bundle size of your application
+          const { renderMarkdown } = await import('next-intlayer/markdown');
+          return renderMarkdown(md);
+        }}
+      >
+        {children}
+      </MarkdownProvider>
+    );
+    ```
+
+    > Importar su renderizador de Markdown dinámicamente es una buena manera de reducir el tamaño del paquete de su aplicación.
+
   </Tab>
   <Tab label="Vue" value="vue">
 
@@ -679,6 +809,9 @@ Estas utilidades renderizan **únicamente cadenas Markdown puras** y son indepen
     app.mount("#app");
     ```
 
+
+    > MDX es compatible — cualquier nombre de componente usado dentro de su Markdown (ej. `<MyCustomJSXComponent />`) se resuelve contra el mapeo de `components`.
+
     También puede usar su propio renderizador de markdown:
 
     ```typescript fileName="main.ts"
@@ -720,6 +853,9 @@ Estas utilidades renderizan **únicamente cadenas Markdown puras** y son indepen
     </MarkdownProvider>
     ```
 
+
+    > MDX es compatible — cualquier nombre de componente usado dentro de su Markdown (ej. `<MyCustomJSXComponent />`) se resuelve contra el mapeo de `components`.
+
     También puede usar su propio renderizador de markdown:
 
     ```svelte fileName="App.svelte"
@@ -756,6 +892,9 @@ Estas utilidades renderizan **únicamente cadenas Markdown puras** y son indepen
     );
     ```
 
+
+    > MDX es compatible — cualquier nombre de componente usado dentro de su Markdown (ej. `<MyCustomJSXComponent />`) se resuelve contra el mapeo de `components`.
+
     También puede usar su propio renderizador de markdown:
 
     ```tsx fileName="AppProvider.tsx"
@@ -792,6 +931,9 @@ Estas utilidades renderizan **únicamente cadenas Markdown puras** y son indepen
     );
     ```
 
+
+    > MDX es compatible — cualquier nombre de componente usado dentro de su Markdown (ej. `<MyCustomJSXComponent />`) se resuelve contra el mapeo de `components`.
+
     También puede usar su propio renderizador de markdown:
 
     ```tsx fileName="AppProvider.tsx"
@@ -835,3 +977,191 @@ Estas utilidades renderizan **únicamente cadenas Markdown puras** y son indepen
 
   </Tab>
 </Tabs>
+
+## Suspense
+
+El renderizador de Markdown de Intlayer se carga dinámicamente. Aunque está optimizado, el fragmento (chunk) del analizador subyacente es de aproximadamente 55 kb. Cargar esto sincrónicamente retrasa la representación inicial de la página y degrada el First Contentful Paint (FCP).
+
+Para evitar el bloqueo de la interfaz de usuario, Intlayer se integra con la API Suspense de React. Recupera el analizador en segundo plano y arroja una Promesa durante la descarga.
+
+Envuelva cualquier componente que represente Intlayer Markdown en un límite `<Suspense>`. Esto muestra un estado de retroceso localizado mientras se descarga el fragmento, permitiendo que el resto de su DOM se represente de inmediato.
+
+Advertencia: Si no proporciona un límite `<Suspense>`, React suspenderá en el nivel raíz o bloqueará la representación de todo el árbol de componentes hasta que el fragmento de 55 kb esté completamente cargado.
+
+<Tabs>
+  <Tab label="Next.js" value="nextjs">
+
+En Next.js App Router, puede usar React `Suspense` para componentes del cliente o un archivo `loading.tsx` para componentes del servidor.
+
+**Componente de cliente:**
+
+```tsx fileName="components/MyComponent.tsx"
+"use client";
+import { useIntlayer } from "next-intlayer";
+import { Suspense } from "react";
+
+const MyComponent = () => {
+  const markdownContent = useIntlayer("my-markdown");
+
+  return (
+    <Suspense fallback={<div>Loading...</div>}>{markdownContent}</Suspense>
+  );
+};
+```
+
+**Componente de servidor con `loading.tsx`:**
+
+```tsx fileName="app/loading.tsx"
+export default function Loading() {
+  return <div>Loading...</div>;
+}
+```
+
+```tsx fileName="app/page.tsx"
+import { useIntlayer } from "next-intlayer/server";
+
+const MyPage = () => {
+  const markdownContent = useIntlayer("my-markdown");
+  return <div>{markdownContent}</div>;
+};
+
+export default MyPage;
+```
+
+  </Tab>
+
+  <Tab label="React" value="react">
+
+```tsx
+import { useIntlayer } from "react-intlayer";
+import { Suspense } from "react";
+
+const MyComponent = () => {
+  const markdownContent = useIntlayer("my-markdown");
+
+  return (
+    <Suspense fallback={<div>Loading...</div>}>{markdownContent}</Suspense>
+  );
+};
+```
+
+  </Tab>
+ 
+  <Tab label="Vue" value="vue">
+
+Vue tiene un componente `<Suspense>` incorporado. Envuelva el componente que representa contenido Markdown en un límite `<Suspense>`.
+
+```vue fileName="MyComponent.vue"
+<script setup>
+import { useIntlayer } from "vue-intlayer";
+
+const { markdownContent } = useIntlayer("my-markdown");
+</script>
+
+<template>
+  <Suspense>
+    <component :is="markdownContent" />
+    <template #fallback>
+      <div>Loading...</div>
+    </template>
+  </Suspense>
+</template>
+```
+
+  </Tab>
+  <Tab label="Svelte" value="svelte">
+
+Svelte no tiene un equivalente a la API Suspense. Utilice un bloque `{#await}` para manejar la representación asíncrona del contenido Markdown.
+
+```svelte fileName="MyComponent.svelte"
+<script lang="ts">
+import { useIntlayer } from "svelte-intlayer";
+
+const content = useIntlayer("my-markdown");
+</script>
+
+{#await $content.markdownContent}
+  <div>Loading...</div>
+{:then rendered}
+  {@html rendered}
+{/await}
+```
+
+  </Tab>
+  <Tab label="Preact" value="preact">
+
+Preact admite la API Suspense de React a través de `preact/compat`.
+
+```tsx fileName="MyComponent.tsx"
+import { useIntlayer } from "preact-intlayer";
+import { Suspense } from "preact/compat";
+
+const MyComponent = () => {
+  const markdownContent = useIntlayer("my-markdown");
+
+  return (
+    <Suspense fallback={<div>Loading...</div>}>{markdownContent}</Suspense>
+  );
+};
+```
+
+  </Tab>
+  <Tab label="Solid" value="solid">
+
+Solid tiene su propio componente `<Suspense>` de `solid-js`.
+
+```tsx fileName="MyComponent.tsx"
+import { useIntlayer } from "solid-intlayer";
+import { Suspense } from "solid-js";
+
+const MyComponent = () => {
+  const { markdownContent } = useIntlayer("my-markdown");
+
+  return (
+    <Suspense fallback={<div>Loading...</div>}>{markdownContent}</Suspense>
+  );
+};
+```
+
+  </Tab>
+  <Tab label="Angular" value="angular">
+
+Angular no tiene una API Suspense. Utilice las vistas diferibles de Angular (`@defer`) para manejar contenido Markdown cargado de forma diferida (requiere Angular 17+).
+
+```typescript fileName="my.component.ts"
+import { Component } from "@angular/core";
+import { useIntlayer } from "angular-intlayer";
+
+@Component({
+  selector: "app-my",
+  template: `
+    @defer {
+      <div [innerHTML]="content().markdownContent"></div>
+    } @loading {
+      <div>Loading...</div>
+    }
+  `,
+})
+export class MyComponent {
+  content = useIntlayer("my-markdown");
+}
+```
+
+  </Tab>
+</Tabs>
+
+---
+
+## Referencia de opciones
+
+Estas opciones se pueden pasar a `MarkdownProvider`, `MarkdownRenderer`, `useMarkdownRenderer` y `renderMarkdown`.
+
+| Option                | Type        | Default | Descripción                                                                                                      |
+| :-------------------- | :---------- | :------ | :--------------------------------------------------------------------------------------------------------------- |
+| `forceBlock`          | `boolean`   | `false` | Fuerza la salida para que esté envuelta en un elemento de nivel de bloque (ej. `<div>`).                         |
+| `forceInline`         | `boolean`   | `false` | Fuerza la salida para que esté envuelta en un elemento en línea (ej. `<span>`).                                  |
+| `tagfilter`           | `boolean`   | `true`  | Habilita el GitHub Tag Filter para mejorar la seguridad eliminando etiquetas HTML peligrosas.                    |
+| `preserveFrontmatter` | `boolean`   | `false` | Si es `true`, no se eliminará el frontmatter al principio de la cadena Markdown.                                 |
+| `components`          | `Overrides` | `{}`    | Un mapa de etiquetas HTML a componentes personalizados (ej. `{ h1: MyHeading }`).                                |
+| `wrapper`             | `Component` | `null`  | Un componente personalizado para envolver el Markdown renderizado.                                               |
+| `renderMarkdown`      | `Function`  | `null`  | Una función de renderizado personalizada para reemplazar completamente el compilador de Markdown predeterminado. |

package/docs/es/interest_of_intlayer.md

@@ -223,7 +223,7 @@ Este enfoque te permite:
 
 Las estrellas de GitHub son un fuerte indicador de la popularidad de un proyecto, la confianza de la comunidad y la relevancia a largo plazo. Si bien no son una medida directa de la calidad técnica, reflejan cuántos desarrolladores encuentran útil el proyecto, siguen su progreso y es probable que lo adopten. Para estimar el valor de un proyecto, las estrellas ayudan a comparar la tracción entre alternativas y brindan información sobre el crecimiento del ecosistema.
 
-[![Star History Chart](https://api.star-history.com/chart?repos=formatjs/formatjs%2Ci18next/react-i18next%2Ci18next/i18next%2Ci18next/next-i18next%2Clingui/js-lingui%2Camannn/next-intl%2Cintlify/vue-i18n%2Caymericzip/intlayer%2Copral/inlang&type=date&legend=top-left)](https://www.star-history.com/#formatjs/formatjs&i18next/react-i18next&i18next/i18next&i18next/next-i18next&lingui/js-lingui&amannn/next-intl&intlify/vue-i18n&opral/paraglide-js&aymericzip/intlayer)
+[![Star History Chart](https://api.star-history.com/chart?repos=aymericzip/intlayer%2Cformatjs/formatjs%2Ci18next/react-i18next%2Ci18next/i18next%2Ci18next/next-i18next%2Clingui/js-lingui%2Camannn/next-intl%2Cintlify/vue-i18n%2Ccodingcommons/typesafe-i18n%2Copral/paraglide-js&type=date&legend=top-left)](https://www.star-history.com/#aymericzip/intlayer&formatjs/formatjs&i18next/react-i18next&i18next/i18next&i18next/next-i18next&lingui/js-lingui&amannn/next-intl&intlify/vue-i18n&codingcommons/typesafe-i18n&opral/paraglide-js)
 
 ---