@intlayer/docs 8.10.0-canary.1 → 8.10.1

package/docs/uk/dictionary/markdown.md

@@ -95,34 +95,34 @@ 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: "## Мій заголовок \n\nLorem Ipsum",
+        content: t({
+          en: md(file("./myMarkdown.en.md")),
+          uk: md(file("./myMarkdown.uk.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({
-          en: md(file("./myMarkdown.en.md")),
-          uk: md(file("./myMarkdown.uk.md")),
-        }),
+        myMarkdownContent: "## Мій заголовок \n\nLorem Ipsum",
       },
     };
     ```
@@ -130,8 +130,6 @@ Intlayer підтримує вміст форматованого тексту,
   </Tab>
 </Tabs>
 
----
-
 ## Рендеринг Markdown
 
 Intlayer надає два незалежні способи рендерингу Markdown:
@@ -147,7 +145,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"
@@ -197,6 +195,57 @@ Intlayer надає два незалежні способи рендеринг
     {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
+    {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="Vue" value="vue">
     У Vue вміст Markdown можна рендерити за допомогою вбудованого тегу `component` або безпосередньо як вузол.
@@ -441,7 +490,7 @@ Intlayer надає два незалежні способи рендеринг
 Ці утиліти рендерять **тільки необроблені рядки Markdown** і не залежать від `useIntlayer`. Використовуйте їх, коли вам потрібно відрендерити Markdown з джерел, відмінних від ваших словників.
 
 <Tabs group="framework">
-  <Tab label="React / Next.js" value="react">
+  <Tab label="React" value="react">
   
     #### Компонент `<MarkdownRenderer />`
 
@@ -479,6 +528,45 @@ Intlayer надає два незалежні способи рендеринг
     const jsx = renderMarkdown("# Мій Заголовок", { forceBlock: true });
     ```
 
+  </Tab>
+  <Tab label="Next.js" value="nextjs">
+  
+    #### Компонент `<MarkdownRenderer />`
+
+    Рендерить рядок Markdown з певними опціями.
+
+    ```tsx
+    import { MarkdownRenderer } from "next-intlayer/markdown";
+
+    <MarkdownRenderer forceBlock={true} tagfilter={true}>
+      {"# Мій Заголовок"}
+    </MarkdownRenderer>
+    ```
+
+    #### Хук `useMarkdownRenderer()`
+
+    Отримайте попередньо налаштовану функцію рендерингу.
+
+    ```tsx
+    import { useMarkdownRenderer } from "next-intlayer/markdown";
+
+    const renderMarkdown = useMarkdownRenderer({
+      forceBlock: true,
+      components: { h1: (props) => <h1 {...props} className="custom" /> }
+    });
+
+    return renderMarkdown("# Мій Заголовок");
+    ```
+
+    #### Утиліта `renderMarkdown()`
+    Окрема утиліта для рендерингу поза компонентами.
+
+    ```tsx
+    import { renderMarkdown } from "next-intlayer/markdown";
+
+    const jsx = renderMarkdown("# Мій Заголовок", { forceBlock: true });
+    ```
+
   </Tab>
   <Tab label="Vue" value="vue">
 
@@ -608,14 +696,12 @@ Intlayer надає два незалежні способи рендеринг
   </Tab>
 </Tabs>
 
----
-
 ## Глобальне налаштування за допомогою `MarkdownProvider`
 
 `MarkdownProvider` (або його еквівалент у фреймворку) налаштовує конвеєр рендерингу Markdown для всього вашого додатку. Це стосується як автоматичного рендерингу `useIntlayer`, так і допоміжних утиліт. Налаштування, вказані тут, є значеннями за замовчуванням — `.use()` перевизначає їх на рівні вузла.
 
 <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 @@ Intlayer надає два незалежні способи рендеринг
     );
     ```
 
+
     > Підтримується MDX — будь-яка назва компонента, яка використовується всередині вашого Markdown (наприклад, `<MyCustomJSXComponent />`), розпізнається відповідно до карти `components`.
 
     Ви також можете використовувати власний рендерер markdown:
@@ -643,6 +730,7 @@ Intlayer надає два незалежні способи рендеринг
     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 @@ Intlayer надає два незалежні способи рендеринг
 
     > Динамічний імпорт вашого рендерера Markdown — чудовий спосіб зменшити розмір бандлу вашого додатка.
 
+  </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 — будь-яка назва компонента, яка використовується всередині вашого Markdown (наприклад, `<MyCustomJSXComponent />`), розпізнається відповідно до карти `components`.
+
+    Ви також можете використовувати власний рендерер 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>
+    );
+    ```
+
+    > Динамічний імпорт вашого рендерера Markdown — чудовий спосіб зменшити розмір бандлу вашого додатка.
+
   </Tab>
   <Tab label="Vue" value="vue">
 
@@ -679,6 +809,9 @@ Intlayer надає два незалежні способи рендеринг
     app.mount("#app");
     ```
 
+
+    > Підтримується MDX — будь-яка назва компонента, яка використовується всередині вашого Markdown (наприклад, `<MyCustomJSXComponent />`), розпізнається відповідно до карти `components`.
+
     Ви також можете використовувати власний рендерер markdown:
 
     ```typescript fileName="main.ts"
@@ -720,6 +853,9 @@ Intlayer надає два незалежні способи рендеринг
     </MarkdownProvider>
     ```
 
+
+    > Підтримується MDX — будь-яка назва компонента, яка використовується всередині вашого Markdown (наприклад, `<MyCustomJSXComponent />`), розпізнається відповідно до карти `components`.
+
     Ви також можете використовувати власний рендерер markdown:
 
     ```svelte fileName="App.svelte"
@@ -756,6 +892,9 @@ Intlayer надає два незалежні способи рендеринг
     );
     ```
 
+
+    > Підтримується MDX — будь-яка назва компонента, яка використовується всередині вашого Markdown (наприклад, `<MyCustomJSXComponent />`), розпізнається відповідно до карти `components`.
+
     Ви також можете використовувати власний рендерер markdown:
 
     ```tsx fileName="AppProvider.tsx"
@@ -792,6 +931,9 @@ Intlayer надає два незалежні способи рендеринг
     );
     ```
 
+
+    > Підтримується MDX — будь-яка назва компонента, яка використовується всередині вашого Markdown (наприклад, `<MyCustomJSXComponent />`), розпізнається відповідно до карти `components`.
+
     Ви також можете використовувати власний рендерер markdown:
 
     ```tsx fileName="AppProvider.tsx"
@@ -835,3 +977,191 @@ Intlayer надає два незалежні способи рендеринг
 
   </Tab>
 </Tabs>
+
+## Suspense
+
+Рендерер Markdown Intlayer завантажується динамічно. Хоча він оптимізований, базовий фрагмент аналізатора становить близько 55 кБ. Синхронне завантаження цього затримує початковий рендеринг сторінки та погіршує First Contentful Paint (FCP).
+
+Щоб запобігти блокуванню інтерфейсу користувача, Intlayer інтегрується з API Suspense від React. Він завантажує аналізатор у фоновому режимі та створює 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`) в Angular для обробки вмісту 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/uk/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)
 
 ---
 

package/docs/ur/interest_of_intlayer.md

@@ -224,7 +224,7 @@ export const ComponentExample = () => {
 
 GitHub ستارے کسی پروجیکٹ کی مقبولیت، کمیونٹی کے اعتماد اور طویل مدتی مطابقت کا ایک مضبوط اشارہ ہیں۔ اگرچہ یہ تکنیکی معیار کی براہ راست پیمائش نہیں ہے، وہ اس بات کی عکاسی کرتے ہیں کہ کتنے ڈویلپرز پروجیکٹ کو مفید پاتے ہیں، اس کی پیشرفت کی پیروی کرتے ہیں، اور اسے اپنانے کا امکان رکھتے ہیں۔ کسی پروجیکٹ کی قدر کا اندازہ لگانے کے لیے، ستارے متبادلات کے درمیان کشش کا موازنہ کرنے میں مدد کرتے ہیں اور ماحولیاتی نظام کی ترقی کے بارے میں بصیرت فراہم کرتے ہیں۔
 
-[![Star History Chart](https://api.star-history.com/svg?repos=formatjs/formatjs&repos=i18next/react-i18next&repos=i18next/i18next&repos=i18next/next-i18next&repos=lingui/js-lingui&repos=amannn/next-intl&repos=intlify/vue-i18n&repo=opral/paraglide-js&repos=aymericzip/intlayer&repos=opral/inlang&type=Date)](https://api.star-history.com/chart?repos=formatjs/formatjs%2Ci18next/react-i18next%2Ci18next/i18next%2Ci18next/next-i18next%2Clingui/js-lingui%2Amannn/next-intl%2Cintlify/vue-i18n%2Caymericzip/intlayer%2Copral/inlang&type=date&legend=top-left)
+[![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)
 
 ---