@intlayer/docs 8.10.0-canary.1 → 8.10.1

package/docs/fr/dictionary/markdown.md

@@ -95,34 +95,34 @@ Vous pouvez déclarer du contenu Markdown en utilisant la fonction `md` ou simpl
     ```
 
   </Tab>
-  <Tab label="Détection Automatique" value="automatic-detection">
-    Si la chaîne de caractères contient des indicateurs Markdown courants (comme des en-têtes, des listes, des liens, etc.), Intlayer la transformera automatiquement.
+  <Tab label="Fichiers Externes" value="external-files">
+    Importez des fichiers `.md` directement en utilisant la fonction `file`.
 
     ```typescript fileName="markdownDictionary.content.ts"
+    import { md, file, t } from "intlayer";
+
     export default {
       key: "app",
-      contentAutoTransformation: true, // Activer la détection automatique du Markdown - Peut être défini globalement dans intlayer.config.ts
       content: {
-        myMarkdownContent: "## Mon titre \n\nLorem Ipsum",
+        content: t({
+          en: md(file("./myMarkdown.en.md")),
+          fr: md(file("./myMarkdown.fr.md")),
+        }),
       },
     };
     ```
 
   </Tab>
 
-  <Tab label="Fichiers Externes" value="external-files">
-    Importez des fichiers `.md` directement en utilisant la fonction `file`.
+  <Tab label="Détection Automatique" value="automatic-detection">
+    Si la chaîne de caractères contient des indicateurs Markdown courants (comme des en-têtes, des listes, des liens, etc.), Intlayer la transformera automatiquement.
 
     ```typescript fileName="markdownDictionary.content.ts"
-    import { md, file, t } from "intlayer";
-
     export default {
       key: "app",
+      contentAutoTransformation: true, // Activer la détection automatique du Markdown - Peut être défini globalement dans intlayer.config.ts
       content: {
-        content: t({
-          en: md(file("./myMarkdown.en.md")),
-          fr: md(file("./myMarkdown.fr.md")),
-        }),
+        myMarkdownContent: "## Mon titre \n\nLorem Ipsum",
       },
     };
     ```
@@ -130,8 +130,6 @@ Vous pouvez déclarer du contenu Markdown en utilisant la fonction `md` ou simpl
   </Tab>
 </Tabs>
 
----
-
 ## Rendu Markdown
 
 Intlayer propose deux manières indépendantes de rendre du Markdown :
@@ -147,7 +145,7 @@ Le rendu Markdown prend en charge **MDX** — utilisez n'importe quel composant
 ### 1. Rendu Automatique (via `useIntlayer`)
 
 <Tabs group="framework">
-  <Tab label="React / Next.js" value="react">
+  <Tab label="React" value="react">
     Les nœuds Markdown peuvent être rendus directement sous forme de JSX.
 
     ```tsx fileName="App.tsx"
@@ -197,6 +195,57 @@ Le rendu Markdown prend en charge **MDX** — utilisez n'importe quel composant
     {myMarkdownContent.metadata.title}
     ```
 
+  </Tab>
+  <Tab label="Next.js" value="nextjs">
+    Les nœuds Markdown peuvent être rendus directement sous forme de 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} />, // Composant MDX
+        }}
+      >
+        <AppContent />
+      </MarkdownProvider>
+    );
+    ```
+
+    > Si `MarkdownProvider` n'est pas présent, Intlayer rendra le markdown en utilisant le parser par défaut de Markdown vers JSX.
+
+    Vous pouvez également fournir des remplacements locaux pour des nœuds spécifiques en utilisant la méthode `.use()` :
+
+    ```tsx
+    {myMarkdownContent.use({
+      h1: ({ children }) => <h1 style={{ color: "red" }}>{children}</h1>,
+    })}
+    ```
+
+    Vous pouvez récupérer le Markdown sous forme de chaîne de caractères :
+
+    ```tsx
+    {myMarkdownContent.value}
+    {String(myMarkdownContent)}
+    {myMarkdownContent.toString()}
+    ```
+
+    Et vous pouvez accéder aux métadonnées de votre markdown comme ceci :
+
+    ```tsx
+    {myMarkdownContent.metadata}
+    {myMarkdownContent.metadata.title}
+    ```
+
   </Tab>
   <Tab label="Vue" value="vue">
     Dans Vue, le contenu Markdown peut être rendu en utilisant la balise `component` intégrée ou directement comme un nœud.
@@ -441,7 +490,7 @@ Le rendu Markdown prend en charge **MDX** — utilisez n'importe quel composant
 Ces utilitaires rendent **des chaînes Markdown brutes** et sont indépendants de `useIntlayer`. Utilisez-les lorsque vous devez afficher du Markdown provenant de sources autres que vos dictionnaires.
 
 <Tabs group="framework">
-  <Tab label="React / Next.js" value="react">
+  <Tab label="React" value="react">
   
     #### Composant `<MarkdownRenderer />`
 
@@ -479,6 +528,45 @@ Ces utilitaires rendent **des chaînes Markdown brutes** et sont indépendants d
     const jsx = renderMarkdown("# Mon Titre", { forceBlock: true });
     ```
 
+  </Tab>
+  <Tab label="Next.js" value="nextjs">
+  
+    #### Composant `<MarkdownRenderer />`
+
+    Rend une chaîne Markdown avec des options spécifiques.
+
+    ```tsx
+    import { MarkdownRenderer } from "next-intlayer/markdown";
+
+    <MarkdownRenderer forceBlock={true} tagfilter={true}>
+      {"# Mon Titre"}
+    </MarkdownRenderer>
+    ```
+
+    #### Hook `useMarkdownRenderer()`
+
+    Obtenez une fonction de rendu préconfigurée.
+
+    ```tsx
+    import { useMarkdownRenderer } from "next-intlayer/markdown";
+
+    const renderMarkdown = useMarkdownRenderer({
+      forceBlock: true,
+      components: { h1: (props) => <h1 {...props} className="custom" /> }
+    });
+
+    return renderMarkdown("# Mon Titre");
+    ```
+
+    #### Utilitaire `renderMarkdown()`
+    Utilitaire autonome pour le rendu en dehors des composants.
+
+    ```tsx
+    import { renderMarkdown } from "next-intlayer/markdown";
+
+    const jsx = renderMarkdown("# Mon Titre", { forceBlock: true });
+    ```
+
   </Tab>
   <Tab label="Vue" value="vue">
 
@@ -608,14 +696,12 @@ Ces utilitaires rendent **des chaînes Markdown brutes** et sont indépendants d
   </Tab>
 </Tabs>
 
----
-
 ## Configuration Globale avec `MarkdownProvider`
 
 Le `MarkdownProvider` (ou son équivalent dans un framework) configure le pipeline de rendu Markdown pour toute votre application. Cela s'applique aussi bien au rendu automatique `useIntlayer` qu'aux utilitaires d'aide. Les options définies ici sont les options par défaut — `.use()` les remplace au niveau du nœud.
 
 <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 @@ Le `MarkdownProvider` (ou son équivalent dans un framework) configure le pipeli
     );
     ```
 
+
     > MDX est pris en charge — tout nom de composant utilisé dans votre Markdown (ex. `<MyCustomJSXComponent />`) est résolu par rapport à la correspondance dans `components`.
 
     Vous pouvez également utiliser votre propre rendu de markdown :
@@ -643,6 +730,7 @@ Le `MarkdownProvider` (ou son équivalent dans un framework) configure le pipeli
     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 @@ Le `MarkdownProvider` (ou son équivalent dans un framework) configure le pipeli
 
     > L'import dynamique de votre système de rendu Markdown est un bon moyen de réduire la taille du bundle de votre application.
 
+  </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 est pris en charge — tout nom de composant utilisé dans votre Markdown (ex. `<MyCustomJSXComponent />`) est résolu par rapport à la correspondance dans `components`.
+
+    Vous pouvez également utiliser votre propre rendu 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>
+    );
+    ```
+
+    > L'import dynamique de votre système de rendu Markdown est un bon moyen de réduire la taille du bundle de votre application.
+
   </Tab>
   <Tab label="Vue" value="vue">
 
@@ -679,6 +809,9 @@ Le `MarkdownProvider` (ou son équivalent dans un framework) configure le pipeli
     app.mount("#app");
     ```
 
+
+    > MDX est pris en charge — tout nom de composant utilisé dans votre Markdown (ex. `<MyCustomJSXComponent />`) est résolu par rapport à la correspondance dans `components`.
+
     Vous pouvez également utiliser votre propre rendu de markdown :
 
     ```typescript fileName="main.ts"
@@ -720,6 +853,9 @@ Le `MarkdownProvider` (ou son équivalent dans un framework) configure le pipeli
     </MarkdownProvider>
     ```
 
+
+    > MDX est pris en charge — tout nom de composant utilisé dans votre Markdown (ex. `<MyCustomJSXComponent />`) est résolu par rapport à la correspondance dans `components`.
+
     Vous pouvez également utiliser votre propre rendu de markdown :
 
     ```svelte fileName="App.svelte"
@@ -756,6 +892,9 @@ Le `MarkdownProvider` (ou son équivalent dans un framework) configure le pipeli
     );
     ```
 
+
+    > MDX est pris en charge — tout nom de composant utilisé dans votre Markdown (ex. `<MyCustomJSXComponent />`) est résolu par rapport à la correspondance dans `components`.
+
     Vous pouvez également utiliser votre propre rendu de markdown :
 
     ```tsx fileName="AppProvider.tsx"
@@ -792,6 +931,9 @@ Le `MarkdownProvider` (ou son équivalent dans un framework) configure le pipeli
     );
     ```
 
+
+    > MDX est pris en charge — tout nom de composant utilisé dans votre Markdown (ex. `<MyCustomJSXComponent />`) est résolu par rapport à la correspondance dans `components`.
+
     Vous pouvez également utiliser votre propre rendu de markdown :
 
     ```tsx fileName="AppProvider.tsx"
@@ -835,3 +977,191 @@ Le `MarkdownProvider` (ou son équivalent dans un framework) configure le pipeli
 
   </Tab>
 </Tabs>
+
+## Suspense
+
+Le moteur de rendu Markdown d'Intlayer est chargé dynamiquement. Bien qu'optimisé, le chunk de l'analyseur sous-jacent fait environ 55 ko. Son chargement synchrone retarde le rendu initial de la page et dégrade le First Contentful Paint (FCP).
+
+Pour éviter de bloquer l'interface utilisateur, Intlayer s'intègre à l'API Suspense de React. Il récupère l'analyseur en arrière-plan et lève une Promise pendant le téléchargement.
+
+Enveloppez tout composant rendant le Markdown d'Intlayer dans une limite `<Suspense>`. Cela affiche un état de repli localisé pendant le téléchargement du chunk, permettant au reste de votre DOM de se rendre immédiatement.
+
+Avertissement : Si vous ne fournissez pas de limite `<Suspense>`, React suspendra au niveau racine ou bloquera le rendu de tout l'arbre des composants jusqu'à ce que le chunk de 55 ko soit complètement chargé.
+
+<Tabs>
+  <Tab label="Next.js" value="nextjs">
+
+Dans Next.js App Router, vous pouvez utiliser soit React `Suspense` pour les composants clients, soit un fichier `loading.tsx` pour les composants serveurs.
+
+**Composant Client :**
+
+```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>
+  );
+};
+```
+
+**Composant Serveur avec `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 possède un composant `<Suspense>` intégré. Enveloppez le composant rendant le contenu Markdown dans une limite `<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 n'a pas d'équivalent à l'API Suspense. Utilisez un bloc `{#await}` pour gérer le rendu asynchrone du contenu 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 prend en charge l'API Suspense de React via `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 possède son propre composant `<Suspense>` provenant 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 n'a pas d'API Suspense. Utilisez les vues différées (`@defer`) d'Angular pour gérer le contenu Markdown chargé paresseusement (nécessite 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>
+
+---
+
+## Référence des options
+
+Ces options peuvent être passées à `MarkdownProvider`, `MarkdownRenderer`, `useMarkdownRenderer` et `renderMarkdown`.
+
+| Option                | Type        | Default | Description                                                                                         |
+| :-------------------- | :---------- | :------ | :-------------------------------------------------------------------------------------------------- |
+| `forceBlock`          | `boolean`   | `false` | Force la sortie à être enveloppée dans un élément de niveau bloc (ex: `<div>`).                     |
+| `forceInline`         | `boolean`   | `false` | Force la sortie à être enveloppée dans un élément en ligne (ex: `<span>`).                          |
+| `tagfilter`           | `boolean`   | `true`  | Active le GitHub Tag Filter pour une meilleure sécurité en supprimant les balises HTML dangereuses. |
+| `preserveFrontmatter` | `boolean`   | `false` | Si `true`, le frontmatter au début de la chaîne Markdown ne sera pas supprimé.                      |
+| `components`          | `Overrides` | `{}`    | Une carte des balises HTML vers des composants personnalisés (ex: `{ h1: MyHeading }`).             |
+| `wrapper`             | `Component` | `null`  | Un composant personnalisé pour envelopper le Markdown rendu.                                        |
+| `renderMarkdown`      | `Function`  | `null`  | Une fonction de rendu personnalisée pour remplacer complètement le compilateur Markdown par défaut. |

package/docs/fr/interest_of_intlayer.md

@@ -223,7 +223,7 @@ Cette approche vous permet de :
 
 Les étoiles GitHub sont un indicateur fort de la popularité d'un projet, de la confiance de la communauté et de sa pertinence à long terme. Bien qu'elles ne soient pas une mesure directe de la qualité technique, elles reflètent le nombre de développeurs qui trouvent le projet utile, suivent ses progrès et sont susceptibles de l'adopter. Pour estimer la valeur d'un projet, les étoiles aident à comparer l'attraction entre les alternatives et fournissent des informations sur la croissance de l'écosystème.
 
-[![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)
 
 ---