@intlayer/docs 7.5.12 → 7.5.14

package/docs/uk/dictionary/enumeration.md

@@ -0,0 +1,245 @@
+---
+createdAt: 2025-08-23
+updatedAt: 2025-08-23
+title: Перелічення
+description: Дізнайтеся, як оголошувати та використовувати перелічення на вашому багатомовному сайті. Дотримуйтеся кроків у цій онлайн-документації, щоб налаштувати проект за кілька хвилин.
+keywords:
+  - Перелічення
+  - Інтернаціоналізація
+  - Документація
+  - Intlayer
+  - Next.js
+  - JavaScript
+  - React
+slugs:
+  - doc
+  - concept
+  - content
+  - enumeration
+history:
+  - version: 5.5.10
+    date: 2025-06-29
+    changes: Ініціалізація історії
+---
+
+# Перелічення / Утворення множини
+
+## Як працює перелічення
+
+В Intlayer перелічення реалізується за допомогою функції `enu`, яка зіставляє конкретні ключі з відповідним вмістом. Ці ключі можуть представляти числові значення, діапазони або власні ідентифікатори. При використанні з React Intlayer або Next Intlayer відповідний вміст автоматично вибирається на основі локалі застосунку та визначених правил.
+
+## Налаштування перерахувань
+
+Щоб налаштувати перерахування у вашому проєкті Intlayer, потрібно створити модуль контенту, який містить визначення перерахувань. Ось приклад простого перерахування для кількості автомобілів:
+
+```typescript fileName="**/*.content.ts" contentDeclarationFormat="typescript"
+import { enu, type Dictionary } from "intlayer";
+
+const carEnumeration = {
+  key: "car_count",
+  content: {
+    numberOfCar: enu({
+      "<-1": "Менше ніж -1 автомобіля",
+      "-1": "Мінус один автомобіль",
+      "0": "Жодних автомобілів",
+      "1": "Один автомобіль",
+      ">5": "Кілька автомобілів",
+      ">19": "Багато автомобілів",
+      "fallback": "Значення за замовчуванням", // Необов'язково
+    }),
+  },
+} satisfies Dictionary;
+
+export default carEnumeration;
+```
+
+```javascript fileName="**/*.content.mjs" contentDeclarationFormat="esm"
+import { enu } from "intlayer";
+
+/** @type {import('intlayer').Dictionary} */
+const carEnumeration = {
+  key: "car_count",
+  content: {
+    numberOfCar: enu({
+      "<-1": "Менше ніж -1 автомобіля",
+      "-1": "Мінус один автомобіль",
+      "0": "Жодних автомобілів",
+      "1": "Один автомобіль",
+      ">5": "Кілька автомобілів",
+      ">19": "Багато автомобілів",
+      "fallback": "Значення за замовчуванням", // Необов'язково
+    }),
+  },
+};
+
+export default carEnumeration;
+```
+
+```javascript fileName="**/*.content.cjs" contentDeclarationFormat="commonjs"
+const { enu } = require("intlayer");
+
+/** @type {import('intlayer').Dictionary} */
+const carEnumeration = {
+  key: "car_count",
+  content: {
+    numberOfCar: enu({
+      "<-1": "Менше ніж мінус одна машина",
+      "-1": "Мінус одна машина",
+      "0": "Немає машин",
+      "1": "Одна машина",
+      ">5": "Декілька машин",
+      ">19": "Багато машин",
+      "fallback": "Значення за замовчуванням", // Необов'язково
+    }),
+  },
+};
+
+module.exports = carEnumeration;
+```
+
+```json fileName="**/*.content.json" contentDeclarationFormat="json"
+{
+  "$schema": "https://intlayer.org/schema.json",
+  "key": "car_count",
+  "content": {
+    "numberOfCar": {
+      "nodeType": "enumeration",
+      "enumeration": {
+        "<-1": "Менше ніж мінус одна машина",
+        "-1": "Minus one car",
+        "0": "No cars",
+        "1": "One car",
+        ">5": "Some cars",
+        ">19": "Many cars",
+        "fallback": "Fallback value" // Optional
+      }
+    }
+  }
+}
+```
+
+У цьому прикладі `enu` відображає різні умови на конкретний вміст. При використанні в React-компоненті Intlayer може автоматично вибирати відповідний вміст на основі заданої змінної.
+
+> Порядок оголошення має значення в перерахуваннях Intlayer. Перше допустиме оголошення — те, яке буде обрано. Якщо застосовуються кілька умов, упевніться, що вони розташовані в правильному порядку, щоб уникнути непередбачуваної поведінки.
+
+> Якщо не вказано fallback, функція поверне `undefined`, якщо жоден ключ не підходить.
+
+## Використання перерахувань з React Intlayer
+
+Щоб використовувати enumeration в React-компоненті, ви можете скористатися хуком `useIntlayer` з пакета `react-intlayer`. Цей хук повертає правильний контент на основі вказаного ID. Ось приклад використання:
+
+```tsx fileName="**/*.tsx" codeFormat="typescript"
+import type { FC } from "react";
+import { useIntlayer } from "react-intlayer";
+
+const CarComponent: FC = () => {
+  const { numberOfCar } = useIntlayer("car_count");
+
+  return (
+    <div>
+      <p>
+        {
+          numberOfCar(0) // Вивід: Немає авто
+        }
+      </p>
+      <p>
+        {
+          numberOfCar(6) // Вивід: Декілька авто
+        }
+      </p>
+      <p>
+        {
+          numberOfCar(20) // Вивід: Багато авто
+        }
+      </p>
+      <p>
+        {
+          numberOfCar(0.01) // Вивід: Значення за замовчуванням
+        }
+      </p>
+    </div>
+  );
+};
+```
+
+```javascript fileName="**/*.mjx" codeFormat="esm"
+import { useIntlayer } from "react-intlayer";
+
+const CarComponent = () => {
+  const { numberOfCar } = useIntlayer("car_count");
+
+  return (
+    <div>
+      <p>
+        {
+          numberOfCar(0) // Вивід: Немає автомобілів
+        }
+      </p>
+      <p>
+        {
+          numberOfCar(6) // Вивід: Кілька автомобілів
+        }
+      </p>
+      <p>
+        {
+          numberOfCar(20) // Вивід: Багато автомобілів
+        }
+      </p>
+      <p>
+        {
+          numberOfCar(0.01) // Вивід: Резервне значення
+        }
+      </p>
+    </div>
+  );
+};
+
+export default CarComponent;
+```
+
+```javascript fileName="**/*.cjs" codeFormat="commonjs"
+const { useIntlayer } = require("react-intlayer");
+
+const CarComponent = () => {
+  const { numberOfCar } = useIntlayer("car_count");
+
+  return (
+    <div>
+      <p>
+        {
+          numberOfCar(0) // Вивід: Немає автомобілів
+        }
+      </p>
+      <p>
+        {
+          numberOfCar(6) // Вивід: Декілька автомобілів
+        }
+      </p>
+      <p>
+        {
+          numberOfCar(20) // Вивід: Багато автомобілів
+        }
+      </p>
+      <p>
+        {
+          numberOfCar(0.01) // Вивід: Значення за замовчуванням
+        }
+      </p>
+    </div>
+  );
+};
+
+module.exports = CarComponent;
+```
+
+У цьому прикладі компонент динамічно підлаштовує свій вивід залежно від кількості автомобілів. Правильний вміст вибирається автоматично залежно від заданого діапазону.
+
+## Додаткові ресурси
+
+Для детальнішої інформації про налаштування та використання зверніться до наступних ресурсів:
+
+- [Документація 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)
+
+Ці ресурси надають додаткову інформацію про налаштування та використання Intlayer в різних середовищах і з різними фреймворками.

package/docs/uk/dictionary/file.md

@@ -0,0 +1,232 @@
+---
+createdAt: 2025-03-13
+updatedAt: 2025-06-29
+title: Файл
+description: Дізнайтеся, як вбудовувати зовнішні файли у ваш content dictionary за допомогою функції `file`. Ця документація пояснює, як Intlayer пов’язує та динамічно керує вмістом файлів.
+keywords:
+  - Файл
+  - Інтернаціоналізація
+  - Документація
+  - Intlayer
+  - Next.js
+  - JavaScript
+  - React
+slugs:
+  - doc
+  - concept
+  - content
+  - file
+history:
+  - version: 5.5.10
+    date: 2025-06-29
+    changes: Init history
+---
+
+# Вміст файлу / Вбудовування файлів в Intlayer
+
+В Intlayer функція `file` дозволяє вбудовувати вміст зовнішніх файлів у dictionary. Такий підхід гарантує, що Intlayer розпізнає файл-джерело, що забезпечує плавну інтеграцію з Intlayer Visual Editor та CMS.
+
+## Чому використовувати `file` замість `import`, `require` або `fs`?
+
+На відміну від методів читання файлів `import`, `require` або `fs`, використання `file` пов’язує файл зі словником, що дозволяє Intlayer відстежувати та оновлювати вміст динамічно під час редагування файлу. Внаслідок цього використання `file` забезпечує кращу інтеграцію з Intlayer Visual Editor та CMS.
+
+## Налаштування вмісту файлу
+
+Щоб вбудувати вміст файлу у ваш проект Intlayer, використовуйте функцію `file` у модулі контенту. Нижче наведені приклади, що демонструють різні реалізації.
+
+```typescript fileName="**/*.content.ts" contentDeclarationFormat="typescript"
+import { file, type Dictionary } from "intlayer";
+
+const myFileContent = {
+  key: "my_key",
+  content: {
+    myFile: file("./path/to/file.txt"),
+  },
+} satisfies Dictionary;
+
+export default myFileContent;
+```
+
+```javascript fileName="**/*.content.mjs" contentDeclarationFormat="esm"
+import { file } from "intlayer";
+
+/** @type {import('intlayer').Dictionary} */
+const myFileContent = {
+  key: "my_key",
+  content: {
+    myFile: file("./path/to/file.txt"),
+  },
+};
+
+export default myFileContent;
+```
+
+```javascript fileName="**/*.content.cjs" contentDeclarationFormat="commonjs"
+const { file } = require("intlayer");
+
+/** @type {import('intlayer').Dictionary} */
+const myFileContent = {
+  key: "my_key",
+  content: {
+    myFile: file("./path/to/file.txt"),
+  },
+};
+
+module.exports = myFileContent;
+```
+
+```json5 fileName="**/*.content.json" contentDeclarationFormat="json"
+{
+  "$schema": "https://intlayer.org/schema.json",
+  "key": "my_key",
+  "content": {
+    "myFile": {
+      "nodeType": "file",
+      "value": "./path/to/file.txt",
+    },
+  },
+}
+```
+
+## Використання вмісту файлу в React Intlayer
+
+Щоб використовувати вбудований вміст файлу в React-компоненті, імпортуйте і використовуйте хук `useIntlayer` з пакета `react-intlayer`. Це отримує вміст за вказаним ключем і дозволяє відображати його динамічно.
+
+```tsx fileName="**/*.tsx" codeFormat="typescript"
+import type { FC } from "react";
+import { useIntlayer } from "react-intlayer";
+
+const FileComponent: FC = () => {
+  const { myFile } = useIntlayer("my_key");
+
+  return (
+    <div>
+      <pre>{myFile}</pre>
+    </div>
+  );
+};
+
+export default FileComponent;
+```
+
+```javascript fileName="**/*.mjx" codeFormat="esm"
+import { useIntlayer } from "react-intlayer";
+
+const FileComponent = () => {
+  const { myFile } = useIntlayer("my_key");
+
+  return (
+    <div>
+      <pre>{myFile}</pre>
+    </div>
+  );
+};
+
+export default FileComponent;
+```
+
+```javascript fileName="**/*.cjs" codeFormat="commonjs"
+const { useIntlayer } = require("react-intlayer");
+
+const FileComponent = () => {
+  const { myFile } = useIntlayer("my_key");
+
+  return (
+    <div>
+      <pre>{myFile}</pre>
+    </div>
+  );
+};
+
+module.exports = FileComponent;
+```
+
+## Приклад багатомовного Markdown
+
+Щоб підтримувати багатомовні редаговані Markdown-файли, ви можете використовувати `file` у поєднанні з `t()` та `md()` для визначення версій вмісту Markdown різними мовами.
+
+```typescript fileName="**/*.content.ts" contentDeclarationFormat="typescript"
+import { file, t, md, type Dictionary } from "intlayer";
+
+const myMultilingualContent = {
+  key: "my_multilingual_key",
+  content: {
+    myContent: md(
+      t({
+        en: file("src/components/test.en.md"),
+        fr: file("src/components/test.fr.md"),
+        es: file("src/components/test.es.md"),
+      })
+    ),
+  },
+} satisfies Dictionary;
+
+export default myMultilingualContent;
+```
+
+```javascript fileName="**/*.content.mjs" contentDeclarationFormat="esm"
+import { file, t, md } from "intlayer";
+
+/** @type {import('intlayer').Dictionary} */
+const myMultilingualContent = {
+  key: "my_multilingual_key",
+  content: {
+    myContent: md(
+      t({
+        en: file("src/components/test.en.md"),
+        fr: file("src/components/test.fr.md"),
+        es: file("src/components/test.es.md"),
+      })
+    ),
+  },
+};
+
+export default myMultilingualContent;
+```
+
+```javascript fileName="**/*.content.cjs" contentDeclarationFormat="commonjs"
+const { file, t, md } = require("intlayer");
+
+const myMultilingualContent = {
+  key: "my_multilingual_key",
+  content: {
+    myContent: md(
+      t({
+        en: file("src/components/test.en.md"),
+        fr: file("src/components/test.fr.md"),
+        es: file("src/components/test.es.md"),
+      })
+    ),
+  },
+};
+```
+
+Ця конфігурація дозволяє динамічно отримувати вміст залежно від мовних налаштувань користувача. При використанні в Intlayer Visual Editor або CMS система розпізнає, що вміст походить із зазначених Markdown-файлів, і забезпечить їхню можливість редагування.
+
+## Різні типи шляхів
+
+Коли ви використовуєте функцію `file`, можна застосовувати різні типи шляхів, щоб вказати файл для вставки.
+
+- `file("./path/to/file.txt")` - Відносний шлях відносно поточного файлу
+- `file("path/to/file.txt")` - Відносний шлях відносно кореневої директорії проєкту
+- `file("/users/username/path/to/file.txt")` - Абсолютний шлях
+
+## Як Intlayer обробляє вміст файлу
+
+Функція `file` базується на модулі `fs` у Node.js для читання вмісту вказаного файлу та вставлення його до словника. У поєднанні з Intlayer Visual Editor або CMS Intlayer може відстежувати зв’язок між словником і файлом. Це дозволяє Intlayer:
+
+- Розпізнавати, що вміст походить із конкретного файлу.
+- Автоматично оновлювати вміст словника при редагуванні пов’язаного файлу.
+- Забезпечте синхронізацію між файлом та словником, зберігаючи цілісність вмісту.
+
+## Додаткові ресурси
+
+Для детальнішої інформації щодо налаштування та використання вставки файлів в Intlayer зверніться до наступних ресурсів:
+
+- [Документація 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-контенту](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/dictionary/markdown.md)
+- [Документація з перекладу контенту](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/dictionary/translation.md)
+
+Ці ресурси надають додаткові відомості про вбудовування файлів, керування контентом та інтеграцію Intlayer із різними фреймворками.

package/docs/uk/dictionary/function_fetching.md

@@ -0,0 +1,212 @@
+---
+createdAt: 2025-08-23
+updatedAt: 2025-08-23
+title: Отримання через функції
+description: Дізнайтеся, як оголосити та використовувати отримання через функції у вашому мультимовному вебсайті. Дотримуйтесь кроків у цій онлайн-документації, щоб налаштувати проєкт за кілька хвилин.
+keywords:
+  - Отримання через функції
+  - Інтернаціоналізація
+  - Документація
+  - Intlayer
+  - Next.js
+  - JavaScript
+  - React
+slugs:
+  - doc
+  - concept
+  - content
+  - function-fetching
+history:
+  - version: 5.5.10
+    date: 2025-06-29
+    changes: Ініціалізація історії
+---
+
+# Отримання через функції
+
+Intlayer дозволяє вам оголошувати функції контенту в ваших контент-модулях, які можуть бути синхронними або асинхронними. Під час збірки застосунку Intlayer виконує ці функції, щоб отримати результат функції. Значення, що повертається, має бути JSON-об'єктом або простим значенням, таким як рядок або число.
+
+> Увага: функціональне отримання контенту наразі недоступне в JSON-оголошеннях контенту та у віддалених деклараційних файлах контенту.
+
+## Оголошення функцій
+
+Ось приклад простого синхронного отримання контенту за допомогою функції:
+
+```typescript fileName="**/*.content.ts" contentDeclarationFormat="typescript"
+import type { Dictionary } from "intlayer";
+
+const functionContent = {
+  key: "function_content",
+  content: {
+    text: () => "Це контент, який повертається функцією",
+  },
+} satisfies Dictionary;
+
+export default functionContent;
+```
+
+```javascript fileName="**/*.content.mjs" contentDeclarationFormat="esm"
+/** @type {import('intlayer').Dictionary} */
+const functionContent = {
+  key: "function_content",
+  content: {
+    text: () => "Це вміст, відрендерований функцією",
+  },
+};
+
+export default functionContent;
+```
+
+```javascript fileName="**/*.content.cjs" contentDeclarationFormat="commonjs"
+/** @type {import('intlayer').Dictionary} */
+const functionContent = {
+  key: "function_content",
+  content: {
+    text: () => "Це вміст, відрендерований функцією",
+  },
+};
+
+module.exports = functionContent;
+```
+
+```json fileName="**/*.content.json" contentDeclarationFormat="json"
+{
+  "$schema": "https://intlayer.org/schema.json",
+  "key": "function_content",
+  "content": {
+    "text": "Це вміст, відрендерений функцією"
+  }
+}
+```
+
+У цьому прикладі ключ `text` містить функцію, яка повертає рядок. Цей контент можна відобразити у ваших React-компонентах за допомогою пакетів інтерпретатора Intlayer, таких як `react-intlayer`.
+
+## Асинхронне отримання даних функцією
+
+На додаток до синхронних функцій, Intlayer також підтримує асинхронні функції, що дозволяє отримувати дані з зовнішніх джерел або імітувати отримання даних за допомогою мок-даних.
+
+Нижче наведений приклад асинхронної функції, яка імітує звернення до сервера:
+
+```typescript fileName="**/*.content.ts" contentDeclarationFormat="typescript"
+import { setTimeout } from "node:timers/promises";
+import type { Dictionary } from "intlayer";
+
+const fakeFetch = async (): Promise<string> => {
+  // Почекайте 200 мс, щоб симулювати запит до сервера
+  return await setTimeout(200).then(() => "Це вміст, отриманий із сервера");
+};
+
+const asyncFunctionContent = {
+  key: "async_function",
+  content: { text: fakeFetch },
+} satisfies Dictionary;
+
+export default asyncFunctionContent;
+```
+
+```javascript fileName="**/*.content.mjs" contentDeclarationFormat="esm"
+import { setTimeout } from "node:timers/promises";
+
+/** @type {import('intlayer').Dictionary} */
+const fakeFetch = async () => {
+  // Почекайте 200 мс, щоб симулювати запит до сервера
+  await setTimeout(200);
+  return "Це вміст, отриманий із сервера";
+};
+
+const asyncFunctionContent = {
+  key: "async_function",
+  content: { text: fakeFetch },
+};
+
+export default asyncFunctionContent;
+```
+
+```javascript fileName="**/*.content.cjs" contentDeclarationFormat="commonjs"
+const { setTimeout } = require("node:timers/promises");
+
+/** @type {import('intlayer').Dictionary} */
+const fakeFetch = async () => {
+  // Почекайте 200 мс, щоб змоделювати запит до сервера
+  await setTimeout(200);
+  return "Це вміст, отриманий із сервера";
+};
+
+const asyncFunctionContent = {
+  key: "async_function",
+  content: { text: fakeFetch },
+};
+
+module.exports = asyncFunctionContent;
+```
+
+```plaintext fileName="**/*.content.json" contentDeclarationFormat="json"
+Неможливо отримати вміст із JSON-файлу, використовуйте натомість .ts або .js файл
+```
+
+У цьому випадку функція `fakeFetch` імітує затримку, щоб симулювати час відповіді сервера. Intlayer виконує асинхронну функцію і використовує результат як вміст для ключа `text`.
+
+## Використання контенту на основі функцій у React-компонентах
+
+Щоб використовувати контент на основі функцій у React-компоненті, потрібно імпортувати `useIntlayer` з `react-intlayer` і викликати його з ідентифікатором контенту, щоб отримати вміст. Ось приклад:
+
+```typescript fileName="**/*.jsx" codeFormat="typescript"
+import type { FC } from "react";
+import { useIntlayer } from "react-intlayer";
+
+const MyComponent: FC = () => {
+  const functionContent = useIntlayer("function_content");
+  const asyncFunctionContent = useIntlayer("async_function_content");
+
+  return (
+    <div>
+      <p>{functionContent.text}</p>
+      {/* Вивід: Це вміст, відрендерений функцією */}
+      <p>{asyncFunctionContent.text}</p>
+      {/* Вивід: Це вміст, отриманий із сервера */}
+    </div>
+  );
+};
+
+export default MyComponent;
+```
+
+```javascript fileName="**/*.mjx" codeFormat="esm"
+import { useIntlayer } from "react-intlayer";
+
+const MyComponent = () => {
+  const functionContent = useIntlayer("function_content");
+  const asyncFunctionContent = useIntlayer("async_function_content");
+
+  return (
+    <div>
+      <p>{functionContent.text}</p>
+      {/* Вивід: Це вміст, відрендерений функцією */}
+      <p>{asyncFunctionContent.text}</p>
+      {/* Вивід: Це вміст, отриманий із сервера */}
+    </div>
+  );
+};
+
+export default MyComponent;
+```
+
+```javascript fileName="**/*.cjs" codeFormat="commonjs"
+const { useIntlayer } = require("react-intlayer");
+
+const MyComponent = () => {
+  const functionContent = useIntlayer("function_content");
+  const asyncFunctionContent = useIntlayer("async_function_content");
+
+  return (
+    <div>
+      <p>{functionContent.text}</p>
+      {/* Вивід: Це вміст, відрендерений функцією */}
+      <p>{asyncFunctionContent.text}</p>
+      {/* Вивід: Це вміст, отриманий з сервера */}
+    </div>
+  );
+};
+
+module.exports = MyComponent;
+```