@intlayer/docs 7.5.12 → 7.5.13

package/docs/uk/dictionary/markdown.md

@@ -0,0 +1,383 @@
+---
+createdAt: 2025-02-07
+updatedAt: 2025-06-29
+title: Markdown
+description: "Дізнайтеся, як оголошувати та використовувати контент у форматі Markdown на вашому багатомовному вебсайті з Intlayer. Дотримуйтесь кроків у цій онлайн-документації, щоб безшовно інтегрувати Markdown у ваш проєкт."
+keywords:
+  - Markdown
+  - Internationalization
+  - Documentation
+  - Intlayer
+  - Next.js
+  - JavaScript
+  - React
+slugs:
+  - doc
+  - concept
+  - content
+  - markdown
+history:
+  - version: 5.5.10
+    date: 2025-06-29
+    changes: Ініціалізація історії
+---
+
+# Markdown / Форматований текст
+
+## Як працює Markdown
+
+Intlayer підтримує контент у форматі rich text, визначений за допомогою синтаксису Markdown. Це досягається за допомогою функції `md`, яка перетворює рядок у форматі Markdown у формат, яким може керувати Intlayer. Використовуючи Markdown, ви можете легко писати й підтримувати контент із багатим форматуванням, наприклад блоги, статті та інше.
+
+[Візуальний редактор Intlayer](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/intlayer_visual_editor.md) та [Intlayer CMS](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/intlayer_CMS.md) обидва підтримують керування контентом у Markdown.
+
+Під час інтеграції з React-додатком ви можете використовувати провайдера рендерингу Markdown (наприклад, [`markdown-to-jsx`](https://www.npmjs.com/package/markdown-to-jsx)), щоб перетворювати вміст Markdown на HTML. Це дозволяє писати контент у Markdown і забезпечує його коректне відображення в вашому додатку.
+
+## Налаштування Markdown-контенту
+
+Щоб налаштувати Markdown-контент у вашому проєкті Intlayer, визначте словник контенту, що використовує функцію `md`.
+
+```typescript fileName="markdownDictionary.content.ts" contentDeclarationFormat="typescript"
+import { md, type Dictionary } from "intlayer";
+
+const markdownDictionary = {
+  key: "app",
+  content: {
+    myMarkdownContent: md("## My title \n\nLorem Ipsum"),
+  },
+} satisfies Dictionary;
+
+export default markdownDictionary;
+```
+
+```javascript fileName="markdownDictionary.content.mjs" contentDeclarationFormat="esm"
+import { md } from "intlayer";
+
+// Тип словника Intlayer: import('intlayer').Dictionary
+/** @type {import('intlayer').Dictionary} */
+const markdownDictionary = {
+  key: "app",
+  content: {
+    myMarkdownContent: md("## Мій заголовок \n\nLorem Ipsum"),
+  },
+};
+
+export default markdownDictionary;
+```
+
+```javascript fileName="markdownDictionary.content.cjs" contentDeclarationFormat="commonjs"
+const { md } = require("intlayer");
+
+// Тип словника Intlayer: import('intlayer').Dictionary
+/** @type {import('intlayer').Dictionary} */
+const markdownDictionary = {
+  key: "app",
+  content: {
+    myMarkdownContent: md("## Мій заголовок \n\nLorem Ipsum"),
+  },
+};
+
+module.exports = markdownDictionary;
+```
+
+```json fileName="markdownDictionary.content.json" contentDeclarationFormat="json"
+{
+  "$schema": "https://intlayer.org/schema.json",
+  "key": "app",
+  "content": {
+    "myMarkdownContent": {
+      "nodeType": "markdown",
+      "markdown": "## My title \n\nLorem Ipsum"
+    }
+  }
+}
+```
+
+## Імпорт (багатомовний) файлу `.md`
+
+Якщо ваш Markdown-файл має розширення `.md`, ви можете імпортувати його за допомогою різних форматів імпорту, які надає JavaScript або Intlayer.
+
+Рекомендується віддавати перевагу імпорту через функцію [`file`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/dictionary/file.md), оскільки вона дозволяє Intlayer коректно керувати шляхами відносно розташування файлу та забезпечує інтеграцію цього файлу з Візуальним редактором / CMS.
+
+```typescript fileName="md.d.ts" contentDeclarationFormat="typescript"
+// Ця декларація дозволяє TypeScript розпізнавати та імпортувати Markdown (.md) файли як модулі.
+// Без цього TypeScript викинув би помилку при спробі імпортувати Markdown-файли,
+// оскільки він за замовчуванням не підтримує імпорт нечітких файлів (non-code files).
+
+declare module "*.md";
+```
+
+```typescript fileName="markdownDictionary.content.ts" contentDeclarationFormat="typescript"
+import { md, file, t, type Dictionary } from "intlayer";
+import { readFileSync } from "fs";
+import { resolve } from "path";
+
+import markdown from "./myMarkdown.md";
+
+const markdownDictionary = {
+  key: "app",
+  content: {
+    contentMultilingualFile: t({
+      en: md(file("./myMarkdown.en.md")),
+      fr: md(file("./myMarkdown.fr.md")),
+      es: md(file("./myMarkdown.es.md")),
+    }),
+
+    contentImport: md(markdown),
+    contentRequire: md(require("./myMarkdown.md")),
+    contentAsyncImport: md(
+      import("./myMarkdown.md").then((module) => module.default)
+    ),
+    contentFetch: md(fetch("https://example.com").then((res) => res.text())),
+    contentFS: md(() => {
+      const filePath = resolve(process.cwd(), "doc/test.md");
+      return readFileSync(filePath, "utf8");
+    }),
+  },
+} satisfies Dictionary;
+
+export default markdownDictionary;
+```
+
+```javascript fileName="markdownDictionary.content.mjs" contentDeclarationFormat="esm"
+import { md, file, t } from "intlayer";
+import { readFileSync } from "fs";
+import { resolve } from "path";
+
+import markdown from "./myMarkdown.md";
+
+/** @type {import('intlayer').Dictionary} */
+const markdownDictionary = {
+  key: "app",
+  content: {
+    contentMultilingualFile: t({
+      en: md(file("./myMarkdown.en.md")),
+      uk: md(file("./myMarkdown.uk.md")),
+      fr: md(file("./myMarkdown.fr.md")),
+      es: md(file("./myMarkdown.es.md")),
+    }),
+
+    contentImport: md(markdown),
+    contentRequire: md(require("./myMarkdown.md")),
+    contentAsyncImport: md(
+      import("./myMarkdown.md").then((module) => module.default)
+    ),
+    contentFetch: md(fetch("https://example.com").then((res) => res.text())),
+    contentFS: md(() => {
+      const filePath = resolve(process.cwd(), "doc/test.md");
+      return readFileSync(filePath, "utf8");
+    }),
+  },
+};
+
+export default markdownDictionary;
+```
+
+```javascript fileName="markdownDictionary.content.cjs" contentDeclarationFormat="commonjs"
+const { md, file, t } = require("intlayer");
+
+const markdown_en = require("./myMarkdown.en.md");
+const markdown_fr = require("./myMarkdown.fr.md");
+const markdown_uk = require("./myMarkdown.uk.md");
+const markdown_es = require("./myMarkdown.es.md");
+
+/** @type {import('intlayer').Dictionary} */
+const markdownDictionary = {
+  key: "app",
+  content: {
+    contentMultilingualFile: t({
+      en: md(file("./myMarkdown.en.md")),
+      fr: md(file("./myMarkdown.fr.md")),
+      es: md(file("./myMarkdown.es.md")),
+    }),
+
+    contentImport: md(markdown),
+    contentFetch: md(fetch("https://example.com").then((res) => res.text())),
+    contentFS: md(() => {
+      const filePath = resolve(process.cwd(), "doc/test.md");
+      return readFileSync(filePath, "utf8");
+    }),
+  },
+};
+
+module.exports = markdownDictionary;
+```
+
+```jsonc fileName="markdownDictionary.content.json" contentDeclarationFormat="json"
+// - Імпорт зовнішніх файлів Markdown (.md) можливий лише за допомогою вузла `file` або деклараційних файлів JS чи TS.
+// - Отримання зовнішнього вмісту Markdown можливе лише за допомогою деклараційних файлів JS або TS.
+
+{
+  "$schema": "https://intlayer.org/schema.json",
+  "key": "app",
+  "content": {
+    "": {
+        "nodeType": "file",
+        "file": "./myMarkdown.md",
+      },
+    },
+
+    "contentMultilingualFile": {
+      "nodeType": "translation",
+      "translation": {
+        "en": {
+          "nodeType": "markdown",
+          "markdown": {
+            "nodeType": "file",
+            "file": "./myMarkdown.en.md",
+          },
+        },
+        "fr": {
+          "nodeType": "markdown",
+          "markdown": {
+            "nodeType": "file",
+            "file": "./myMarkdown.fr.md",
+          },
+        },
+        "es": {
+          "nodeType": "markdown",
+          "markdown": {
+            "nodeType": "file",
+            "file": "./myMarkdown.es.md",
+          },
+        },
+      },
+    },
+  },
+}
+```
+
+## Використання Markdown з React Intlayer
+
+Щоб відобразити вміст Markdown у React-застосунку, ви можете скористатися хуком `useIntlayer` з пакета `react-intlayer` разом із провайдером рендерингу Markdown. У цьому прикладі ми використовуємо пакет [`markdown-to-jsx`](https://www.npmjs.com/package/markdown-to-jsx) для конвертації Markdown у HTML.
+
+```tsx fileName="App.tsx" codeFormat="typescript"
+import type { FC } from "react";
+import { useIntlayer, MarkdownProvider } from "react-intlayer";
+import Markdown from "markdown-to-jsx";
+
+const AppContent: FC = () => {
+  const { myMarkdownContent } = useIntlayer("app");
+
+  return <>{myMarkdownContent}</>;
+};
+
+export const AppProvider: FC = () => (
+  <MarkdownProvider
+    renderMarkdown={(markdown) => <Markdown>{markdown}</Markdown>}
+  >
+    <AppContent />
+  </MarkdownProvider>
+);
+```
+
+```jsx fileName="App.jsx" codeFormat="esm"
+import { useIntlayer, MarkdownProvider } from "react-intlayer";
+import Markdown from "markdown-to-jsx";
+
+const AppContent = () => {
+  const { myMarkdownContent } = useIntlayer("app");
+
+  return <>{myMarkdownContent}</>;
+};
+
+export const AppProvider = () => (
+  <MarkdownProvider
+    renderMarkdown={(markdown) => <Markdown>{markdown}</Markdown>}
+  >
+    <AppContent />
+  </MarkdownProvider>
+);
+```
+
+```jsx fileName="App.jsx" codeFormat="commonjs"
+const { useIntlayer, MarkdownProvider } = require("react-intlayer");
+const Markdown = require("markdown-to-jsx");
+
+const AppContent = () => {
+  const { myMarkdownContent } = useIntlayer("app");
+
+  return <>{myMarkdownContent}</>;
+};
+
+AppProvider = () => (
+  <MarkdownProvider
+    renderMarkdown={(markdown) => <Markdown>{markdown}</Markdown>}
+  >
+    <AppContent />
+  </MarkdownProvider>
+);
+
+module.exports = {
+  AppProvider,
+};
+```
+
+У цій реалізації:
+
+- Компонент `MarkdownProvider` обгортає застосунок (або відповідну його частину) та приймає функцію `renderMarkdown`. Ця функція використовується для перетворення рядків Markdown у JSX за допомогою пакету `markdown-to-jsx`.
+- Хук `useIntlayer` використовується для отримання вмісту Markdown (`myMarkdownContent`) зі словника за ключем `"app"`.
+- Вміст Markdown рендериться безпосередньо в компоненті, а рендеринг Markdown обробляється провайдером.
+
+### Використання Markdown з Next Intlayer
+
+Реалізація з пакетом `next-intlayer` схожа на наведену вище. Єдина відмінність полягає в тому, що функцію `renderMarkdown` слід передати в компонент `MarkdownProvider` у клієнтському компоненті.
+
+```tsx title="src/providers/IntlayerMarkdownProvider.tsx" codeFormat="typescript"
+"use client";
+
+import type { FC, PropsWithChildren } from "react";
+import { MarkdownProvider } from "next-intlayer";
+
+const renderMarkdown = (markdown: string) => (
+  <span style={{ color: "red" }}>{markdown}</span>
+);
+
+export const IntlayerMarkdownProvider: FC<PropsWithChildren> = ({
+  children,
+}) => (
+  <MarkdownProvider renderMarkdown={renderMarkdown}>
+    {children}
+  </MarkdownProvider>
+);
+```
+
+```jsx title="src/providers/IntlayerMarkdownProvider.msx" codeFormat="esm"
+"use client";
+
+import { MarkdownProvider } from "next-intlayer";
+
+const renderMarkdown = (markdown) => (
+  <span style={{ color: "red" }}>{markdown}</span>
+);
+
+export const IntlayerMarkdownProvider = ({ children }) => (
+  <MarkdownProvider renderMarkdown={renderMarkdown}>
+    {children}
+  </MarkdownProvider>
+);
+```
+
+```jsx title="src/providers/IntlayerMarkdownProvider.csx" codeFormat="commonjs"
+"use client";
+
+const { MarkdownProvider } = require("next-intlayer");
+
+const renderMarkdown = (markdown) => (
+  <span style={{ color: "red" }}>{markdown}</span>
+);
+
+const IntlayerMarkdownProvider = ({ children }) => (
+  <MarkdownProvider renderMarkdown={renderMarkdown}>
+    {children}
+  </MarkdownProvider>
+);
+```
+
+## Додаткові ресурси
+
+- [Документація Intlayer CLI](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/cli/index.md)
+- [Документація Intlayer для React](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/intlayer_with_create_react_app.md)
+- [Документація Intlayer для Next.js](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/intlayer_with_nextjs_15.md)
+- [markdown-to-jsx на npm](https://www.npmjs.com/package/markdown-to-jsx)
+
+Ці ресурси надають додаткову інформацію щодо налаштування та використання Intlayer з різними типами контенту та фреймворками.

package/docs/uk/dictionary/nesting.md

@@ -0,0 +1,273 @@
+---
+createdAt: 2025-02-07
+updatedAt: 2025-06-29
+title: Вкладення словника
+description: Дізнайтесь, як використовувати вкладення контенту в Intlayer, щоб ефективно повторно використовувати та структурувати багатомовний контент. Дотримуйтесь цієї документації, щоб безшовно реалізувати вкладення у вашому проєкті.
+keywords:
+  - Вкладення
+  - Повторне використання контенту
+  - Документація
+  - Intlayer
+  - Next.js
+  - JavaScript
+  - React
+slugs:
+  - doc
+  - concept
+  - content
+  - nesting
+history:
+  - version: 5.5.10
+    date: 2025-06-29
+    changes: Ініціалізація історії
+---
+
+# Вкладення / Посилання на підконтент
+
+## Як працює вкладення
+
+У Intlayer вкладення реалізується за допомогою функції `nest`, яка дозволяє посилатися на контент з іншого словника та повторно його використовувати. Замість дублювання контенту ви можете вказати на існуючий модуль контенту за його ключем.
+
+## Налаштування вкладення
+
+Щоб налаштувати вкладення у вашому проєкті Intlayer, спочатку визначте базовий контент, який ви хочете повторно використовувати. Далі, у окремому модулі контенту, використайте функцію `nest` для імпорту цього контенту.
+
+### Базовий словник
+
+Нижче наведено приклад базового словника, який можна вкладати в інший словник:
+
+```typescript fileName="firstDictionary.content.ts" contentDeclarationFormat="typescript"
+import { type Dictionary } from "intlayer";
+
+const firstDictionary = {
+  key: "key_of_my_first_dictionary",
+  content: {
+    content: "content",
+    subContent: {
+      contentNumber: 0,
+      contentString: "string",
+    },
+  },
+} satisfies Dictionary;
+
+export default firstDictionary;
+```
+
+```javascript fileName="firstDictionary.content.mjs" contentDeclarationFormat="esm"
+/** @type {import('intlayer').Dictionary} */
+const firstDictionary = {
+  key: "key_of_my_first_dictionary",
+  content: {
+    content: "content",
+    subContent: {
+      contentNumber: 0,
+      contentString: "string",
+    },
+  },
+};
+
+export default firstDictionary;
+```
+
+```javascript fileName="firstDictionary.content.cjs" contentDeclarationFormat="commonjs"
+/** @type {import('intlayer').Dictionary} */
+const firstDictionary = {
+  key: "key_of_my_first_dictionary",
+  content: {
+    content: "content",
+    subContent: {
+      contentNumber: 0,
+      contentString: "string",
+    },
+  },
+};
+
+module.exports = firstDictionary;
+```
+
+```json fileName="firstDictionary.content.json" contentDeclarationFormat="json"
+{
+  "$schema": "https://intlayer.org/schema.json",
+  "key": "key_of_my_first_dictionary",
+  "content": {
+    "content": "content",
+    "subContent": {
+      "contentNumber": 0,
+      "contentString": "string"
+    }
+  }
+}
+```
+
+### Посилання за допомогою nest
+
+Тепер створіть інший модуль вмісту, який використовує функцію `nest` для посилання на наведений вище вміст. Ви можете посилатися на весь вміст або на конкретне вкладене значення:
+
+```typescript fileName="secondDictionary.content.ts" contentDeclarationFormat="typescript"
+import { nest, type Dictionary } from "intlayer";
+
+const myNestingContent = {
+  key: "key_of_my_second_dictionary",
+  content: {
+    // Посилання на весь словник:
+    fullNestedContent: nest("key_of_my_first_dictionary"),
+    // Посилання на конкретне вкладене значення:
+    partialNestedContent: nest(
+      "key_of_my_first_dictionary",
+      "subContent.contentNumber"
+    ),
+  },
+} satisfies Dictionary;
+
+export default myNestingContent;
+```
+
+```javascript fileName="secondDictionary.content.mjs" contentDeclarationFormat="esm"
+import { nest } from "intlayer";
+
+/** @type {import('intlayer').Dictionary} */
+const myNestingContent = {
+  key: "key_of_my_second_dictionary",
+  content: {
+    fullNestedContent: nest("key_of_my_first_dictionary"),
+    partialNestedContent: nest(
+      "key_of_my_first_dictionary",
+      "subContent.contentNumber"
+    ),
+  },
+};
+
+export default myNestingContent;
+```
+
+```javascript fileName="secondDictionary.content.cjs" contentDeclarationFormat="commonjs"
+const { nest } = require("intlayer");
+
+/** @type {import('intlayer').Dictionary} */
+const myNestingContent = {
+  key: "key_of_my_second_dictionary",
+  content: {
+    fullNestedContent: nest("key_of_my_first_dictionary"),
+    partialNestedContent: nest(
+      "key_of_my_first_dictionary",
+      "subContent.contentNumber"
+    ),
+  },
+};
+
+module.exports = myNestingContent;
+```
+
+```json fileName="secondDictionary.content.json" contentDeclarationFormat="json"
+{
+  "$schema": "https://intlayer.org/schema.json",
+  "key": "key_of_my_second_dictionary",
+  "content": {
+    "fullNestedContent": {
+      "nodeType": "nested",
+      "nested": {
+        "dictionaryKey": "key_of_my_first_dictionary"
+      }
+    },
+    "partialNestedContent": {
+      "nodeType": "nested",
+      "nested": {
+        "dictionaryKey": "key_of_my_first_dictionary",
+        "path": "subContent.contentNumber"
+      }
+    }
+  }
+}
+```
+
+Як другий параметр ви можете вказати шлях до вкладеного значення в цьому вмісті. Якщо шлях не вказано, повертається весь вміст зазначеного словника.
+
+## Використання вкладення з React Intlayer
+
+Щоб використовувати вкладений вміст у React-компоненті, скористайтеся хуком `useIntlayer` з пакету `react-intlayer`. Цей хук отримує відповідний вміст на основі вказаного ключа. Ось приклад того, як його використовувати:
+
+```tsx fileName="**/*.tsx" codeFormat="typescript"
+import type { FC } from "react";
+import { useIntlayer } from "react-intlayer";
+
+const NestComponent: FC = () => {
+  const { fullNestedContent, partialNestedContent } = useIntlayer(
+    "key_of_my_second_dictionary"
+  );
+
+  return (
+    <div>
+      <p>
+        Full Nested Content: {JSON.stringify(fullNestedContent)}
+        {/* Вивід: {"content": "content", "subContent": {"contentNumber": 0, "contentString": "string"}} */}
+      </p>
+      <p>
+        Часткове вкладене значення: {partialNestedContent}
+        {/* Вивід: 0 */}
+      </p>
+    </div>
+  );
+};
+
+export default NestComponent;
+```
+
+```javascript fileName="**/*.mjx" codeFormat="esm"
+import { useIntlayer } from "react-intlayer";
+
+const NestComponent = () => {
+  const { fullNestedContent, partialNestedContent } = useIntlayer(
+    "key_of_my_second_dictionary"
+  );
+
+  return (
+    <div>
+      <p>
+        Повний вкладений вміст: {JSON.stringify(fullNestedContent)}
+        {/* Вивід: {"content": "content", "subContent": {"contentNumber": 0, "contentString": "string"}} */}
+      </p>
+      <p>
+        Часткове вкладене значення: {partialNestedContent}
+        {/* Вивід: 0 */}
+      </p>
+    </div>
+  );
+};
+
+export default NestComponent;
+```
+
+```javascript fileName="**/*.cjx" codeFormat="commonjs"
+const { useIntlayer } = require("react-intlayer");
+
+const NestComponent = () => {
+  const { fullNestedContent, partialNestedContent } = useIntlayer(
+    "key_of_my_second_dictionary"
+  );
+
+  return (
+    <div>
+      <p>
+        Full Nested Content: {JSON.stringify(fullNestedContent)}
+        {/* Вивід: {"content": "content", "subContent": {"contentNumber": 0, "contentString": "string"}} */}
+      </p>
+      <p>
+        Partial Nested Value: {partialNestedContent}
+        {/* Вивід: 0 */}
+      </p>
+    </div>
+  );
+};
+
+module.exports = NestComponent;
+```
+
+## Додаткові ресурси
+
+Для детальнішої інформації щодо конфігурації та використання зверніться до наступних ресурсів:
+
+- [Документація Intlayer CLI](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/cli/index.md)
+- [Документація React Intlayer](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/intlayer_with_create_react_app.md)
+- [Документація Next Intlayer](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/intlayer_with_nextjs_15.md)
+
+Ці ресурси надають додаткові відомості щодо налаштування та використання Intlayer в різних середовищах та з різними фреймворками.