@intlayer/docs 8.10.0-canary.1 → 8.10.1

package/docs/de/dictionary/markdown.md

@@ -95,34 +95,34 @@ Sie können Markdown-Inhalte mithilfe der Funktion `md` oder einfach als Zeichen
     ```
 
   </Tab>
-  <Tab label="Automatische Erkennung" value="automatic-detection">
-    Wenn die Zeichenfolge gängige Markdown-Indikatoren (wie Überschriften, Listen, Links usw.) enthält, transformiert Intlayer sie automatisch.
+  <Tab label="Externe Dateien" value="external-files">
+    Importieren Sie `.md`-Dateien direkt mit der `file`-Funktion.
 
     ```typescript fileName="markdownDictionary.content.ts"
+    import { md, file, t } from "intlayer";
+
     export default {
       key: "app",
-      contentAutoTransformation: true, // Automatische Erkennung von Markdown-Inhalten aktivieren - Kann global in intlayer.config.ts konfiguriert werden
       content: {
-        myMarkdownContent: "## Mein Titel \n\nLorem Ipsum",
+        content: t({
+          en: md(file("./myMarkdown.en.md")),
+          de: md(file("./myMarkdown.de.md")),
+        }),
       },
     };
     ```
 
   </Tab>
 
-  <Tab label="Externe Dateien" value="external-files">
-    Importieren Sie `.md`-Dateien direkt mit der `file`-Funktion.
+  <Tab label="Automatische Erkennung" value="automatic-detection">
+    Wenn die Zeichenfolge gängige Markdown-Indikatoren (wie Überschriften, Listen, Links usw.) enthält, transformiert Intlayer sie automatisch.
 
     ```typescript fileName="markdownDictionary.content.ts"
-    import { md, file, t } from "intlayer";
-
     export default {
       key: "app",
+      contentAutoTransformation: true, // Automatische Erkennung von Markdown-Inhalten aktivieren - Kann global in intlayer.config.ts konfiguriert werden
       content: {
-        content: t({
-          en: md(file("./myMarkdown.en.md")),
-          de: md(file("./myMarkdown.de.md")),
-        }),
+        myMarkdownContent: "## Mein Titel \n\nLorem Ipsum",
       },
     };
     ```
@@ -130,8 +130,6 @@ Sie können Markdown-Inhalte mithilfe der Funktion `md` oder einfach als Zeichen
   </Tab>
 </Tabs>
 
----
-
 ## Markdown rendern
 
 Intlayer bietet zwei unabhängige Möglichkeiten zum Rendern von Markdown:
@@ -147,7 +145,7 @@ Das Markdown-Rendering unterstützt **MDX** — verwenden Sie jede JSX/Framework
 ### 1. Automatisches Rendern (über `useIntlayer`)
 
 <Tabs group="framework">
-  <Tab label="React / Next.js" value="react">
+  <Tab label="React" value="react">
     Markdown-Knoten können direkt als JSX gerendert werden.
 
     ```tsx fileName="App.tsx"
@@ -197,6 +195,57 @@ Das Markdown-Rendering unterstützt **MDX** — verwenden Sie jede JSX/Framework
     {myMarkdownContent.metadata.title}
     ```
 
+  </Tab>
+  <Tab label="Next.js" value="nextjs">
+    Markdown-Knoten können direkt als JSX gerendert werden.
+
+    ```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} />, // MDX-Komponente
+        }}
+      >
+        <AppContent />
+      </MarkdownProvider>
+    );
+    ```
+
+    > Wenn `MarkdownProvider` nicht vorhanden ist, rendert Intlayer das Markdown mit dem standardmäßigen Markdown-zu-JSX-Parser.
+
+    Sie können auch lokale Überschreibungen für bestimmte Knoten mit der Methode `.use()` bereitstellen:
+
+    ```tsx
+    {myMarkdownContent.use({
+      h1: ({ children }) => <h1 style={{ color: "red" }}>{children}</h1>,
+    })}
+    ```
+
+    Sie können das Markdown als Zeichenfolge abrufen:
+
+    ```tsx
+    {myMarkdownContent.value}
+    {String(myMarkdownContent)}
+    {myMarkdownContent.toString()}
+    ```
+
+    Und Sie können folgendermaßen auf Ihre Markdown-Metadaten zugreifen:
+
+    ```tsx
+    {myMarkdownContent.metadata}
+    {myMarkdownContent.metadata.title}
+    ```
+
   </Tab>
   <Tab label="Vue" value="vue">
     In Vue kann Markdown-Inhalt mithilfe des integrierten Tags `component` oder direkt als Knoten gerendert werden.
@@ -441,7 +490,7 @@ Das Markdown-Rendering unterstützt **MDX** — verwenden Sie jede JSX/Framework
 Diese Dienstprogramme rendern **nur reine Markdown-Strings** und sind unabhängig von `useIntlayer`. Verwenden Sie sie, wenn Sie Markdown aus anderen Quellen als Ihren Wörterbüchern rendern müssen.
 
 <Tabs group="framework">
-  <Tab label="React / Next.js" value="react">
+  <Tab label="React" value="react">
   
     #### `<MarkdownRenderer />` Komponente
 
@@ -479,6 +528,45 @@ Diese Dienstprogramme rendern **nur reine Markdown-Strings** und sind unabhängi
     const jsx = renderMarkdown("# Mein Titel", { forceBlock: true });
     ```
 
+  </Tab>
+  <Tab label="Next.js" value="nextjs">
+  
+    #### `<MarkdownRenderer />` Komponente
+
+    Rendert einen Markdown-String mit bestimmten Optionen.
+
+    ```tsx
+    import { MarkdownRenderer } from "next-intlayer/markdown";
+
+    <MarkdownRenderer forceBlock={true} tagfilter={true}>
+      {"# Mein Titel"}
+    </MarkdownRenderer>
+    ```
+
+    #### `useMarkdownRenderer()` Hook
+
+    Holt eine vorkonfigurierte Render-Funktion.
+
+    ```tsx
+    import { useMarkdownRenderer } from "next-intlayer/markdown";
+
+    const renderMarkdown = useMarkdownRenderer({
+      forceBlock: true,
+      components: { h1: (props) => <h1 {...props} className="custom" /> }
+    });
+
+    return renderMarkdown("# Mein Titel");
+    ```
+
+    #### `renderMarkdown()` Dienstprogramm
+    Eigenständiges Dienstprogramm zum Rendern außerhalb von Komponenten.
+
+    ```tsx
+    import { renderMarkdown } from "next-intlayer/markdown";
+
+    const jsx = renderMarkdown("# Mein Titel", { forceBlock: true });
+    ```
+
   </Tab>
   <Tab label="Vue" value="vue">
 
@@ -608,14 +696,12 @@ Diese Dienstprogramme rendern **nur reine Markdown-Strings** und sind unabhängi
   </Tab>
 </Tabs>
 
----
-
 ## Globale Konfiguration mit `MarkdownProvider`
 
 Der `MarkdownProvider` (oder sein Framework-Äquivalent) konfiguriert die Markdown-Rendering-Pipeline für Ihre gesamte Anwendung. Dies gilt sowohl für das automatische Rendering von `useIntlayer` als auch für die Hilfsprogramme. Die hier konfigurierten Optionen sind die Standardeinstellungen — `.use()` überschreibt sie auf Knotenebene.
 
 <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 @@ Der `MarkdownProvider` (oder sein Framework-Äquivalent) konfiguriert die Markdo
     );
     ```
 
+
     > MDX wird unterstützt — jeder in Ihrem Markdown verwendete Komponentenname (z. B. `<MyCustomJSXComponent />`) wird mit dem `components`-Mapping aufgelöst.
 
     Sie können auch Ihren eigenen Markdown-Renderer verwenden:
@@ -643,6 +730,7 @@ Der `MarkdownProvider` (oder sein Framework-Äquivalent) konfiguriert die Markdo
     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 @@ Der `MarkdownProvider` (oder sein Framework-Äquivalent) konfiguriert die Markdo
 
     > Das dynamische Importieren Ihres Markdown-Renderers ist eine gute Möglichkeit, die Bundle-Größe Ihrer Anwendung zu reduzieren.
 
+  </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 wird unterstützt — jeder in Ihrem Markdown verwendete Komponentenname (z. B. `<MyCustomJSXComponent />`) wird mit dem `components`-Mapping aufgelöst.
+
+    Sie können auch Ihren eigenen Markdown-Renderer verwenden:
+
+    ```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>
+    );
+    ```
+
+    > Das dynamische Importieren Ihres Markdown-Renderers ist eine gute Möglichkeit, die Bundle-Größe Ihrer Anwendung zu reduzieren.
+
   </Tab>
   <Tab label="Vue" value="vue">
 
@@ -679,6 +809,9 @@ Der `MarkdownProvider` (oder sein Framework-Äquivalent) konfiguriert die Markdo
     app.mount("#app");
     ```
 
+
+    > MDX wird unterstützt — jeder in Ihrem Markdown verwendete Komponentenname (z. B. `<MyCustomJSXComponent />`) wird mit dem `components`-Mapping aufgelöst.
+
     Sie können auch Ihren eigenen Markdown-Renderer verwenden:
 
     ```typescript fileName="main.ts"
@@ -720,6 +853,9 @@ Der `MarkdownProvider` (oder sein Framework-Äquivalent) konfiguriert die Markdo
     </MarkdownProvider>
     ```
 
+
+    > MDX wird unterstützt — jeder in Ihrem Markdown verwendete Komponentenname (z. B. `<MyCustomJSXComponent />`) wird mit dem `components`-Mapping aufgelöst.
+
     Sie können auch Ihren eigenen Markdown-Renderer verwenden:
 
     ```svelte fileName="App.svelte"
@@ -756,6 +892,9 @@ Der `MarkdownProvider` (oder sein Framework-Äquivalent) konfiguriert die Markdo
     );
     ```
 
+
+    > MDX wird unterstützt — jeder in Ihrem Markdown verwendete Komponentenname (z. B. `<MyCustomJSXComponent />`) wird mit dem `components`-Mapping aufgelöst.
+
     Sie können auch Ihren eigenen Markdown-Renderer verwenden:
 
     ```tsx fileName="AppProvider.tsx"
@@ -792,6 +931,9 @@ Der `MarkdownProvider` (oder sein Framework-Äquivalent) konfiguriert die Markdo
     );
     ```
 
+
+    > MDX wird unterstützt — jeder in Ihrem Markdown verwendete Komponentenname (z. B. `<MyCustomJSXComponent />`) wird mit dem `components`-Mapping aufgelöst.
+
     Sie können auch Ihren eigenen Markdown-Renderer verwenden:
 
     ```tsx fileName="AppProvider.tsx"
@@ -835,3 +977,191 @@ Der `MarkdownProvider` (oder sein Framework-Äquivalent) konfiguriert die Markdo
 
   </Tab>
 </Tabs>
+
+## Suspense
+
+Der Intlayer-Markdown-Renderer wird dynamisch geladen. Obwohl er optimiert ist, ist der zugrunde liegende Parser-Chunk etwa 55 KB groß. Das synchrone Laden verzögert das anfängliche Rendern der Seite und verschlechtert den First Contentful Paint (FCP).
+
+Um ein Blockieren der Benutzeroberfläche zu verhindern, ist Intlayer in die React-Suspense-API integriert. Es ruft den Parser im Hintergrund ab und wirft während des Downloads ein Promise.
+
+Umschließen Sie jede Komponente, die Intlayer Markdown rendert, mit einer `<Suspense>`-Grenze. Dies zeigt einen lokalisierten Fallback-Status an, während der Chunk heruntergeladen wird, sodass der Rest Ihres DOMs sofort gerendert werden kann.
+
+Warnung: Wenn Sie keine `<Suspense>`-Grenze angeben, wird React auf Root-Ebene ausgesetzt oder der gesamte Komponentenbaum vom Rendern blockiert, bis der 55-KB-Chunk vollständig geladen ist.
+
+<Tabs>
+  <Tab label="Next.js" value="nextjs">
+
+Im Next.js App Router können Sie entweder React `Suspense` für Client-Komponenten oder eine `loading.tsx`-Datei für Server-Komponenten verwenden.
+
+**Client-Komponente:**
+
+```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>
+  );
+};
+```
+
+**Server-Komponente mit `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 hat eine eingebaute `<Suspense>`-Komponente. Umschließen Sie die Komponente, die Markdown-Inhalte rendert, in einer `<Suspense>`-Grenze.
+
+```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 hat kein Äquivalent zur Suspense-API. Verwenden Sie einen `{#await}`-Block, um asynchrones Rendern von Markdown-Inhalten zu verarbeiten.
+
+```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 unterstützt die React-Suspense-API über `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 hat eine eigene `<Suspense>`-Komponente aus `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 hat keine Suspense-API. Verwenden Sie verzögerbare Ansichten (`@defer`) von Angular, um lazy-geladene Markdown-Inhalte zu verarbeiten (erfordert 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>
+
+---
+
+## Optionen-Referenz
+
+Diese Optionen können an `MarkdownProvider`, `MarkdownRenderer`, `useMarkdownRenderer` und `renderMarkdown` übergeben werden.
+
+| Option                | Type        | Default | Beschreibung                                                                                             |
+| :-------------------- | :---------- | :------ | :------------------------------------------------------------------------------------------------------- |
+| `forceBlock`          | `boolean`   | `false` | Erzwingt, dass die Ausgabe in ein Element auf Blockebene (z. B. `<div>`) eingeschlossen wird.            |
+| `forceInline`         | `boolean`   | `false` | Erzwingt, dass die Ausgabe in ein Inline-Element (z. B. `<span>`) eingeschlossen wird.                   |
+| `tagfilter`           | `boolean`   | `true`  | Aktiviert den GitHub-Tag-Filter für verbesserte Sicherheit, indem gefährliche HTML-Tags entfernt werden. |
+| `preserveFrontmatter` | `boolean`   | `false` | Wenn `true`, wird Frontmatter am Anfang der Markdown-Zeichenfolge nicht entfernt.                        |
+| `components`          | `Overrides` | `{}`    | Eine Zuordnung von HTML-Tags zu benutzerdefinierten Komponenten (z. B. `{ h1: MyHeading }`).             |
+| `wrapper`             | `Component` | `null`  | Eine benutzerdefinierte Komponente zum Umschließen des gerenderten Markdowns.                            |
+| `renderMarkdown`      | `Function`  | `null`  | Eine benutzerdefinierte Rendering-Funktion, um den Standard-Markdown-Compiler vollständig zu ersetzen.   |

package/docs/de/interest_of_intlayer.md

@@ -224,7 +224,7 @@ Dieser Ansatz ermöglicht es Ihnen:
 
 GitHub-Sterne sind ein starker Indikator für die Popularität eines Projekts, das Vertrauen der Community und die langfristige Relevanz. Sie sind zwar kein direktes Maß für die technische Qualität, spiegeln jedoch wider, wie viele Entwickler das Projekt nützlich finden, seinen Fortschritt verfolgen und es wahrscheinlich übernehmen werden. Um den Wert eines Projekts einzuschätzen, helfen Sterne dabei, die Traktion verschiedener Alternativen zu vergleichen und Einblicke in das Wachstum des Ökosystems zu gewinnen.
 
-[![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)
 
 ---