@intlayer/docs 8.10.0-canary.1 → 8.10.1

package/docs/ru/dictionary/markdown.md

@@ -96,35 +96,35 @@ Intlayer поддерживает форматированный текстов
     ```
 
   </Tab>
-  <Tab label="Автоматическое обнаружение" value="automatic-detection">
-    Если строка содержит общие признаки Markdown (такие как заголовки, списки, ссылки и т. д.), Intlayer автоматически преобразует ее.
+  <Tab label="Внешние файлы" value="external-files">
+    Импортируйте файлы `.md` напрямую, используя функцию `file`.
 
     ```typescript fileName="markdownDictionary.content.ts"
+    import { md, file, t } from "intlayer";
+
     export default {
       key: "app",
-      contentAutoTransformation: true, // Включить автоматическое обнаружение Markdown контента — можно установить глобально в intlayer.config.ts
       content: {
-        myMarkdownContent: "## My title \n\nLorem Ipsum",
+        content: t({
+          ru: md(file("./myMarkdown.ru.md")),
+          en: md(file("./myMarkdown.en.md")),
+          fr: md(file("./myMarkdown.fr.md")),
+        }),
       },
     };
     ```
 
   </Tab>
 
-  <Tab label="Внешние файлы" value="external-files">
-    Импортируйте файлы `.md` напрямую, используя функцию `file`.
+  <Tab label="Автоматическое обнаружение" value="automatic-detection">
+    Если строка содержит общие признаки Markdown (такие как заголовки, списки, ссылки и т. д.), Intlayer автоматически преобразует ее.
 
     ```typescript fileName="markdownDictionary.content.ts"
-    import { md, file, t } from "intlayer";
-
     export default {
       key: "app",
+      contentAutoTransformation: true, // Включить автоматическое обнаружение Markdown контента — можно установить глобально в intlayer.config.ts
       content: {
-        content: t({
-          ru: md(file("./myMarkdown.ru.md")),
-          en: md(file("./myMarkdown.en.md")),
-          fr: md(file("./myMarkdown.fr.md")),
-        }),
+        myMarkdownContent: "## My title \n\nLorem Ipsum",
       },
     };
     ```
@@ -132,8 +132,6 @@ Intlayer поддерживает форматированный текстов
   </Tab>
 </Tabs>
 
----
-
 ## Рендеринг Markdown
 
 Intlayer предоставляет два независимых способа рендеринга Markdown:
@@ -149,7 +147,7 @@ Intlayer предоставляет два независимых способа
 ### 1. Автоматический рендеринг (через `useIntlayer`)
 
 <Tabs group="framework">
-  <Tab label="React / Next.js" value="react">
+  <Tab label="React" value="react">
     Markdown-узлы могут быть отрисованы напрямую как JSX.
 
     ```tsx fileName="App.tsx"
@@ -176,6 +174,57 @@ Intlayer предоставляет два независимых способа
 
     > Если `MarkdownProvider` отсутствует, intlayer будет отрисовывать markdown, используя стандартный парсер Markdown в JSX.
 
+Вы также можете предоставить локальные переопределения для конкретных узлов, используя метод `.use()`:
+
+    ```tsx
+    {myMarkdownContent.use({
+      h1: ({ children }) => <h1 style={{ color: "red" }}>{children}</h1>,
+    })}
+    ```
+
+    Вы можете получить Markdown в виде строки:
+
+    ```tsx
+    {myMarkdownContent.value}
+    {String(myMarkdownContent)}
+    {myMarkdownContent.toString()}
+    ```
+
+    И вы можете получить доступ к метаданным вашего markdown, например:
+
+    ```tsx
+    {myMarkdownContent.metadata}
+    {myMarkdownContent.metadata.title}
+    ```
+
+  </Tab>
+  <Tab label="Next.js" value="nextjs">
+    Markdown-узлы могут быть отрисованы напрямую как 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} />, // MDX-компонент
+        }}
+      >
+        <AppContent />
+      </MarkdownProvider>
+    );
+    ```
+
+    > Если `MarkdownProvider` отсутствует, intlayer будет отрисовывать markdown, используя стандартный парсер Markdown в JSX.
+
 Вы также можете предоставить локальные переопределения для конкретных узлов, используя метод `.use()`:
 
     ```tsx
@@ -232,3 +281,396 @@ Intlayer предоставляет два независимых способа
     Вы также можете предоставить локальные переопределения для конкретных узлов, используя метод `.use()`:
 
     ```vue
+    <component :is="myMarkdownContent.use({
+      h1: (props) => h('h1', { style: { color: 'red' } }, props.children),
+    })" />
+    ```
+
+    Вы можете получить Markdown в виде строки:
+
+    ```vue
+    {{ myMarkdownContent.value }}
+    {{ String(myMarkdownContent) }}
+    {{ myMarkdownContent.toString() }}
+    ```
+
+    И вы можете получить доступ к метаданным вашего markdown, например:
+
+    ```vue
+    <component :is="myMarkdownContent.metadata" />
+    <component :is="myMarkdownContent.metadata.title" />
+    ```
+
+  </Tab>
+  <Tab label="Svelte" value="svelte">
+    Svelte по умолчанию рендерит Markdown как HTML-строку. Используйте `{@html}` для его рендеринга.
+
+    ```svelte fileName="App.svelte"
+    <script lang="ts">
+    import { useIntlayer } from "svelte-intlayer";
+    import { MarkdownProvider } from "svelte-intlayer/markdown";
+    import MyHeading from "./MyHeading.svelte";
+
+    const content = useIntlayer("app");
+    </script>
+
+    <MarkdownProvider components={{ h1: MyHeading }}>
+      {@html $content.myMarkdownContent}
+    </MarkdownProvider>
+    ```
+
+    > Если `MarkdownProvider` отсутствует, Intlayer будет рендерить markdown с использованием компилятора по умолчанию.
+
+    Вы также можете предоставить локальные переопределения для конкретных узлов, используя метод `.use()`:
+
+    ```svelte
+    {@html $content.myMarkdownContent.use({ ... })}
+    ```
+
+    Вы можете получить Markdown в виде строки:
+
+    ```svelte
+    {$content.myMarkdownContent.value}
+    {String($content.myMarkdownContent)}
+    {$content.myMarkdownContent.toString()}
+    ```
+
+    И вы можете получить доступ к метаданным вашего markdown, например:
+
+    ```svelte
+    {$content.myMarkdownContent.metadata}
+    {$content.myMarkdownContent.metadata.title}
+    ```
+
+  </Tab>
+  <Tab label="Preact" value="preact">
+    Preact поддерживает узлы Markdown непосредственно в JSX.
+
+    ```tsx fileName="App.tsx"
+    import { useIntlayer } from "preact-intlayer";
+    import { MarkdownProvider } from "preact-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
+        }}
+      >
+        <AppContent />
+      </MarkdownProvider>
+    );
+    ```
+
+    > Если `MarkdownProvider` отсутствует, intlayer будет отрисовывать markdown, используя стандартный парсер Markdown в JSX.
+
+    Вы также можете предоставить локальные переопределения для конкретных узлов, используя метод `.use()`:
+
+    ```tsx
+    {myMarkdownContent.use({
+      h1: ({ children }) => <h1 style={{ color: "red" }}>{children}</h1>,
+    })}
+    ```
+
+    Вы можете получить Markdown в виде строки:
+
+    ```tsx
+    {myMarkdownContent.value}
+    {String(myMarkdownContent)}
+    {myMarkdownContent.toString()}
+    ```
+
+    И вы можете получить доступ к метаданным вашего markdown, например:
+
+    ```tsx
+    {myMarkdownContent.metadata}
+    {myMarkdownContent.metadata.title}
+    ```
+
+  </Tab>
+  <Tab label="Solid" value="solid">
+    Solid поддерживает узлы Markdown непосредственно в JSX.
+
+    ```tsx fileName="App.tsx"
+    import { useIntlayer } from "solid-intlayer";
+    import { MarkdownProvider } from "solid-intlayer/markdown";
+
+    const AppContent = () => {
+      const { myMarkdownContent } = useIntlayer("app");
+      return <div>{myMarkdownContent}</div>;
+    };
+
+    const App = () => (
+      <MarkdownProvider
+        components={{
+          h1: (props) => <h1 style={{ color: "red" }}>{props.children}</h1>,
+          MyButton: (props) => <button {...props} />, // Компонент MDX
+        }}
+      >
+        <AppContent />
+      </MarkdownProvider>
+    );
+    ```
+
+    > Если `MarkdownProvider` отсутствует, intlayer будет отрисовывать markdown, используя стандартный парсер Markdown в JSX.
+
+    Вы также можете предоставить локальные переопределения для конкретных узлов, используя метод `.use()`:
+
+    ```tsx
+    {myMarkdownContent.use({
+      h1: (props) => <h1 style={{ color: "red" }}>{props.children}</h1>,
+    })}
+    ```
+
+    Вы можете получить Markdown в виде строки:
+
+    ```tsx
+    {myMarkdownContent.value}
+    {String(myMarkdownContent)}
+    {myMarkdownContent.toString()}
+    ```
+
+    И вы можете получить доступ к метаданным вашего markdown, например:
+
+    ```tsx
+    {myMarkdownContent.metadata}
+    {myMarkdownContent.metadata.title}
+    ```
+
+  </Tab>
+  <Tab label="Angular" value="angular">
+    Angular использует директиву `[innerHTML]` для рендеринга контента Markdown.
+
+    ```typescript fileName="app.component.ts"
+    import { Component } from "@angular/core";
+    import { useIntlayer } from "angular-intlayer";
+
+    @Component({
+      selector: "app-root",
+      template: `<div [innerHTML]="content().myMarkdownContent"></div>`,
+    })
+    export class AppComponent {
+      content = useIntlayer("app");
+    }
+    ```
+
+    > Если провайдер IntlayerMarkdown не настроен, Intlayer будет выполнять рендеринг с использованием компилятора по умолчанию.
+
+    Вы также можете предоставить локальные переопределения для конкретных узлов, используя метод `.use()`:
+
+    ```typescript
+    content().myMarkdownContent.use({
+      h1: { class: "text-3xl font-bold" },
+    })
+    ```
+
+    Вы можете получить Markdown в виде строки:
+
+    ```typescript
+    content().myMarkdownContent.value
+    String(content().myMarkdownContent)
+    content().myMarkdownContent.toString()
+    ```
+
+    И вы можете получить доступ к метаданным вашего markdown, например:
+
+    ```typescript
+    content().myMarkdownContent.metadata
+    content().myMarkdownContent.metadata.title
+    ```
+
+  </Tab>
+</Tabs>
+
+## Suspense
+
+Рендерер Markdown в Intlayer загружается динамически. Несмотря на оптимизацию, базовый фрагмент парсера составляет около 55 КБ. Его синхронная загрузка задерживает первоначальный рендеринг страницы и ухудшает First Contentful Paint (FCP).
+
+Чтобы предотвратить блокировку пользовательского интерфейса, Intlayer интегрируется с API React Suspense. Он загружает парсер в фоновом режиме и выдает Promise во время загрузки.
+
+Оберните любой компонент, рендерящий Intlayer Markdown, в границу `<Suspense>`. Это отобразит локализованное резервное состояние во время загрузки фрагмента, позволяя остальной части вашего DOM рендериться немедленно.
+
+Предупреждение: Если вы не предоставите границу `<Suspense>`, React приостановит работу на корневом уровне или заблокирует рендеринг всего дерева компонентов до тех пор, пока фрагмент размером 55 КБ не будет полностью загружен.
+
+<Tabs>
+  <Tab label="Next.js" value="nextjs">
+
+В маршрутизаторе Next.js App Router вы можете использовать либо React `Suspense` для клиентских компонентов, либо файл `loading.tsx` для серверных компонентов.
+
+**Клиентский компонент:**
+
+```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>
+  );
+};
+```
+
+**Серверный компонент с `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 есть встроенный компонент `<Suspense>`. Оберните компонент, рендерящий содержимое Markdown, в границу `<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 не имеет эквивалента API Suspense. Используйте блок `{#await}` для обработки асинхронного рендеринга содержимого 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 поддерживает API React Suspense через `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 есть собственный компонент `<Suspense>` из `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 не имеет API Suspense. Используйте отложенные представления (`@defer`) для обработки лениво загружаемого содержимого Markdown (требуется 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>
+
+---
+
+## Справочник по опциям
+
+Эти параметры могут быть переданы в `MarkdownProvider`, `MarkdownRenderer`, `useMarkdownRenderer` и `renderMarkdown`.
+
+| Option                | Type        | Default | Описание                                                                                   |
+| :-------------------- | :---------- | :------ | :----------------------------------------------------------------------------------------- |
+| `forceBlock`          | `boolean`   | `false` | Принудительно оборачивает вывод в блочный элемент (например, `<div>`).                     |
+| `forceInline`         | `boolean`   | `false` | Принудительно оборачивает вывод во встроенный элемент (например, `<span>`).                |
+| `tagfilter`           | `boolean`   | `true`  | Включает фильтр тегов GitHub для повышения безопасности путем удаления опасных тегов HTML. |
+| `preserveFrontmatter` | `boolean`   | `false` | Если `true`, начальный мета-блок (frontmatter) в строке Markdown не будет удален.          |
+| `components`          | `Overrides` | `{}`    | Карта HTML-тегов в пользовательские компоненты (например, `{ h1: MyHeading }`).            |
+| `wrapper`             | `Component` | `null`  | Пользовательский компонент для обертывания отрендеренного Markdown.                        |
+| `renderMarkdown`      | `Function`  | `null`  | Пользовательская функция рендеринга для полной замены компилятора Markdown по умолчанию.   |

package/docs/ru/interest_of_intlayer.md

@@ -224,7 +224,7 @@ export const ComponentExample = () => {
 
 Звезды на GitHub - это сильный индикатор популярности проекта, доверия сообщества и долгосрочной актуальности. Хотя они не являются прямым показателем технического качества, они отражают, сколько разработчиков считают проект полезным, следят за его прогрессом и, вероятно, будут его использовать. Для оценки ценности проекта звезды помогают сравнивать популярность альтернатив и дают представление о росте экосистемы.
 
-[![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)
 
 ---