@intlayer/docs 7.5.11 → 7.5.13

package/docs/uk/roadmap.md

@@ -0,0 +1,346 @@
+---
+createdAt: 2025-03-01
+updatedAt: 2025-06-29
+title: Дорожня карта
+description: Дізнайтеся дорожню карту Intlayer. Перегляньте всі можливості, які Intlayer вже реалізував і планує реалізувати.
+keywords:
+  - Дорожня карта
+  - Intlayer
+  - Інтернаціоналізація
+  - CMS
+  - Система управління контентом
+  - Візуальний редактор
+slugs:
+  - doc
+  - roadmap
+history:
+  - version: 5.5.10
+    date: 2025-06-30
+    changes: Додано підтримку Preact та Nuxt, MCP Server, оновлено CLI
+  - version: 5.5.11
+    date: 2025-06-29
+    changes: Додано команди `docs`
+  - version: 5.5.10
+    date: 2025-06-29
+    changes: Ініціалізовано історію
+---
+
+# Intlayer: Огляд функцій та дорожня карта
+
+Intlayer — рішення для управління контентом і інтернаціоналізації, яке спрощує спосіб, яким ви оголошуєте, керуєте та оновлюєте контент у ваших застосунках. Воно пропонує потужні можливості, такі як централізоване або розподілене оголошення контенту, широкі опції інтернаціоналізації, підтримка Markdown, умовний рендеринг, інтеграція з TypeScript/JavaScript/JSON тощо. Нижче наведено всебічний огляд того, що Intlayer наразі надає, а також майбутні заплановані можливості.
+
+---
+
+## Зміст
+
+<TOC/>
+
+---
+
+## Поточні можливості
+
+### 1. Оголошення контенту
+
+#### Централізоване або розподілене
+
+- **Централізоване**: Оголошуйте весь ваш контент у одному великому файлі в корені вашого застосунку, схожому на i18next, щоб керувати всім з одного місця.
+- **Розподілена**: Альтернативно розділіть ваш контент на окремі файли на рівні компонентів або функціональних блоків для кращої підтримуваності. Це дозволяє зберігати контент поруч із відповідним кодом (components, tests, Storybook тощо). Видалення компонента гарантує, що будь-який пов'язаний контент також буде видалено, запобігаючи залишкам даних, які засмічують ваш codebase.
+
+> Ресурси:
+>
+> - [Оголошення контенту](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/dictionary/content_file.md)
+
+### 2. Інтернаціоналізація
+
+- Підтримка **230 мов та локалей** (включно з регіональними варіантами, такими як French (France), English (Canada), English (UK), Portuguese (Portugal) тощо).
+- Легко керувати перекладами для всіх цих локалей з одного місця.
+
+> Ресурси:
+>
+> - [Інтернаціоналізація](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/dictionary/translation.md)
+
+### 3. Підтримка Markdown
+
+- Оголошуйте вміст за допомогою **Markdown**, що дозволяє автоматично форматувати текст абзацами, заголовками, посиланнями та ін.
+- Ідеально підходить для блогів, статей, сторінок документації або будь-яких випадків, коли потрібне форматування багатого тексту.
+
+> Ресурси:
+>
+> - [Markdown](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/dictionary/markdown.md)
+
+### 4. Підтримка зовнішніх файлів
+
+- Імпортуйте вміст із зовнішніх файлів у текстовому форматі, таких як TXT, HTML, JSON, YAML або CSV.
+- Використовуйте функцію `file` в Intlayer, щоб вбудувати вміст зовнішнього файлу в словник, забезпечуючи безшовну інтеграцію з Intlayer Visual Editor та CMS.
+- Підтримує динамічне оновлення вмісту, тобто коли вихідний файл змінюється, вміст автоматично оновлюється в Intlayer.
+- Дозволяє керувати багатомовним вмістом, динамічно пов’язуючи Markdown-файли для конкретних мов.
+
+> Ресурси:
+>
+> - [Вбудовування вмісту файлу](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/dictionary/file.md)
+
+### 5. Динамічний вміст та отримання функцій
+
+Intlayer пропонує різні методи для вставлення та керування динамічним вмістом, забезпечуючи гнучкість і адаптивність у доставці контенту. Це включає функції для вставлення динамічного вмісту, умовного відображення, перерахування, вкладення та отримання функцій.
+
+1. Вставлення динамічного вмісту
+
+   Використовуйте функцію insert для визначення контенту з заповнювачами ({{name}}, {{age}} тощо).
+
+   Надає можливість шаблонного контенту, який адаптується залежно від введених користувачем даних, відповідей API або інших джерел динамічних даних.
+
+   Працює безшовно з TypeScript, ESM, CommonJS та конфігураціями JSON.
+
+   Легко інтегрується з React Intlayer і Next Intlayer за допомогою useIntlayer.
+
+2. Умовне відображення
+
+   Визначайте контент, який адаптується залежно від умов, специфічних для користувача, таких як мова або статус автентифікації.
+
+   Налаштовуйте персоналізований досвід без дублювання контенту у кількох файлах.
+
+3. Перерахування та множинні форми
+
+   Використовуйте функцію enu для визначення варіантів контенту на основі числових значень, діапазонів або власних ключів.
+
+   Забезпечує автоматичний вибір правильної фрази залежно від заданого значення.
+
+   Підтримує правила упорядкування, що гарантує передбачувану поведінку.
+
+4. Вкладеність і посилання на підконтент
+
+   Використовуйте функцію nest для посилання та повторного використання вмісту з іншого словника, що зменшує дублювання.
+
+   Підтримує структуроване та ієрархічне управління вмістом для полегшення супроводу.
+
+5. Отримання вмісту через функції
+
+   Intlayer дозволяє оголошувати вміст як функції, що дає змогу отримувати вміст як синхронно, так і асинхронно.
+
+   Синхронні функції: вміст генерується динамічно під час збірки.
+
+   Асинхронні функції: динамічно отримують дані з зовнішніх джерел (наприклад, API, бази даних).
+
+   Інтеграція: Працює з TypeScript, ESM і CommonJS, але не підтримується у JSON або віддалених файлах вмісту.
+
+### 6. Формати оголошення вмісту
+
+Intlayer підтримує **TypeScript** (також JavaScript) та **JSON** для оголошення вмісту.
+
+- **TypeScript**:
+  - Забезпечує правильну структуру контенту та відсутність пропущених перекладів.
+  - Пропонує суворі або більш гнучкі режими валідації.
+  - Дозволяє динамічно отримувати дані зі змінних, функцій або зовнішніх API.
+
+- **JSON**:
+  - Полегшує інтеграцію з зовнішніми інструментами (наприклад, візуальними редакторами) завдяки стандартизованому формату.
+
+  > Ресурси:
+  >
+  > - [Формати оголошення контенту](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/dictionary/content_file.md)
+
+### 7. Очищення, оптимізація бандла та динамічні імпорти
+
+- Intlayer інтегрує плагіни `Babel` та `SWC` для оптимізації вашого бандла та підвищення продуктивності. Він замінює імпорти, дозволяючи включати у бандл лише ті словники, які фактично використовуються.
+- Активувавши цю опцію, Intlayer також дозволяє динамічно імпортувати вміст словника лише для поточної локалі.
+
+> Ресурси:
+>
+> - [Build Configuration](https://intlayer.org/doc/concept/configuration#build-configuration)
+
+---
+
+## Інтеграція з фреймворками та середовищами
+
+### 1. Next.js
+
+#### a. Серверні та клієнтські компоненти
+
+- Надає **уніфікований підхід до керування контентом** як для серверних, так і для клієнтських компонентів.
+- Пропонує вбудований контекст для серверних компонентів, що спрощує реалізацію порівняно з іншими рішеннями.
+
+#### b. Метадані, карти сайтів та robots.txt
+
+- Динамічно отримуйте та вставляйте контент для генерації метаданих, карт сайтів або файлів `robots.txt`.
+
+#### c. Middleware
+
+- Додайте middleware, щоб **перенаправляти користувачів** до контенту залежно від їхньої переважної мови.
+
+#### d. Сумісність з Turbopack та Webpack
+
+- Повністю сумісний з новим Turbopack у Next.js, а також із традиційним Webpack.
+
+> Ресурси:
+>
+> - [Next.js](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/intlayer_with_nextjs_15.md)
+
+### 2. Vite
+
+- Подібно до Next.js, ви можете інтегрувати Intlayer з Vite і використовувати **middleware** для перенаправлення користувачів до контенту залежно від їхньої переважної мови.
+
+> Ресурси:
+>
+> - [Vite](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/intlayer_with_vite+react.md)
+
+### 3. Express
+
+- Керуйте контентом та інтернаціоналізуйте бекенд-сервіси, побудовані на Express.
+- Персоналізуйте електронні листи, повідомлення про помилки, push-повідомлення та інше за допомогою локалізованого тексту.
+
+> Ресурси:
+>
+> - [Express](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/intlayer_with_express.md)
+
+### 4. React Native
+
+- Інтегруйте Intlayer з React Native для керування контентом та інтернаціоналізації ваших мобільних додатків.
+- Підтримує платформи iOS та Android.
+
+> Ресурси:
+>
+> - [React Native](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/intlayer_with_react_native.md)
+
+### 5. Lynx
+
+- Інтегруйте Intlayer з Lynx для керування контентом та інтернаціоналізації ваших мобільних додатків.
+- Підтримує платформи iOS та Android.
+
+> Ресурси:
+>
+> - [Lynx](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/intlayer_with_lynx.md)
+
+### 6. Vue
+
+- Інтегруйте Intlayer з Vue для керування контентом та інтернаціоналізації ваших Vite / Vue.js додатків.
+
+> Ресурси:
+>
+> - [Vue](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/intlayer_with_vue.md)
+
+### 7. Nuxt
+
+- Інтегруйте Intlayer з Nuxt для керування контентом та інтернаціоналізації ваших Nuxt / Vue.js додатків.
+- Підтримує як серверні, так і клієнтські компоненти.
+- Інтегрує маршрутизацію та middleware для перенаправлення користувачів до контенту залежно від обраної користувачем мови.
+
+> Ресурси:
+>
+> - [Nuxt](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/intlayer_with_nuxt.md)
+
+### 8. Preact
+
+- Інтегруйте Intlayer з Preact для керування контентом та інтернаціоналізації ваших Preact-додатків.
+
+> Ресурси:
+>
+> - [Preact](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/intlayer_with_preact.md)
+
+---
+
+## Візуальні редактори та CMS
+
+### 1. Локальний візуальний редактор
+
+- **Безкоштовний локальний візуальний редактор**, який дозволяє редагувати вміст вашого застосунку, безпосередньо вибираючи елементи на сторінці.
+- Інтегрує AI‑функції для допомоги:
+  - Генерувати або виправляти переклади
+  - Перевіряти синтаксис і орфографію
+  - Пропонувати покращення
+- Може працювати локально або бути розгорнутий на віддаленому сервері.
+
+> Ресурси:
+>
+> - [Візуальний редактор](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/intlayer_visual_editor.md)
+
+### 2. Intlayer CMS (віддалений)
+
+- **Хостована CMS** — рішення, яке дозволяє керувати вмістом застосунку онлайн, не торкаючись вашого codebase.
+- Надає AI‑підтримку для декларування вмісту, керування перекладами та виправлення помилок синтаксису або орфографії.
+- Взаємодійте з вашим контентом через інтерфейс живого застосунку.
+
+> Ресурси:
+>
+> - [CMS](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/intlayer_CMS.md)
+
+---
+
+## Розширення IDE
+
+- Розширення для основних IDE, які надають **графічний інтерфейс** для керування локальними та віддаленими перекладами.
+- Функціонал може включати автоматичне генерування файлів декларації контенту для компонентів, пряму інтеграцію з Intlayer CMS та перевірку в реальному часі.
+
+---
+
+## Сервер MCP
+
+- **MCP-сервер**, який дозволяє керувати вашим контентом і перекладами за допомогою інтегрованого інструменту в IDE.
+
+---
+
+## Intlayer CLI
+
+- **Переклад та генерація файлів**: Виконуйте аудити файлів контенту, щоб згенерувати відсутні переклади та перевірити невідповідності.
+- **Віддалена взаємодія**: Push ваш локальний контент у віддалений CMS або pull віддалений контент для інтеграції у ваш локальний додаток.
+- **Переклад та перевірка документації**: Перекладайте та перевіряйте вашу документацію, файли тощо.
+
+> Resources:
+>
+> - [CLI](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/cli/index.md)
+
+---
+
+## Середовища
+
+- Використовуйте **environment variables** для налаштування Intlayer по-різному для production, testing та local середовищ.
+- Визначайте, який visual editor або віддалений проект CMS використовувати залежно від вашого середовища.
+
+---
+
+## Миттєві оновлення контенту
+
+- При використанні віддалених словників і Intlayer CMS ви можете **оновлювати контент вашого застосунку на льоту**, без необхідності повторного розгортання.
+
+> Resources:
+>
+> - [CMS](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/intlayer_CMS.md)
+
+---
+
+## Майбутні функції
+
+### 1. A/B тестування та персоналізація
+
+- **Мультиваріантне тестування (Multivariate Testing)**: тестуйте різні версії певного фрагмента контенту, щоб з’ясувати, яка показує найкращі результати (наприклад, вищий коефіцієнт кліків).
+- **Персоналізація на основі даних**: відображайте різний контент залежно від демографічних даних користувача (стать, вік, місцезнаходження тощо) або інших моделей поведінки.
+- **Автоматизована ітерація**: дозволяйте AI автоматично тестувати кілька варіантів і або вибирати найкращий виконавець, або рекомендувати опції для затвердження адміністратором.
+
+### 2. Версіонування
+
+- Відновлюйте попередні версії вашого контенту за допомогою **версіювання контенту**.
+- Відстежуйте зміни з часом і повертайтеся до попередніх станів за потреби.
+
+### 3. Автоматичний переклад
+
+- Для користувачів віддаленої CMS — **генерація перекладів в один клік** для будь-якої підтримуваної мови.
+- Система генеруватиме переклади у фоновому режимі, а потім запропонує вам їх підтвердити або відредагувати.
+
+### 4. SEO Enhancements
+
+- Інструменти для **аналізу ключових слів**, пошукового наміру користувача та виникаючих трендів.
+- Пропонувати вдосконалений контент для кращого ранжування та відстежувати довгострокову ефективність.
+
+### 5. Compatibility with More Frameworks
+
+- Проводяться роботи з підтримки **Solid, Svelte, Angular** та інших.
+- Мета — зробити Intlayer сумісним з **будь-яким додатком на базі JavaScript**.
+
+---
+
+## Висновок
+
+Intlayer прагне бути універсальним рішенням для управління контентом та інтернаціоналізації. Воно зосереджене на гнучкості (централізовані або розподілені файли), широкій підтримці мов, легкій інтеграції з сучасними фреймворками та bundlers, а також на потужних функціях, керованих AI. У міру появи нових можливостей, таких як A/B testing, версіонування та автоматичні переклади, Intlayer і надалі спрощуватиме робочі процеси з контентом і підвищуватиме якість користувацького досвіду на різних платформах.
+
+Слідкуйте за майбутніми релізами та не соромтеся досліджувати наявні можливості, щоб переконатися, як Intlayer сьогодні може допомогти централізувати та оптимізувати ваші процеси управління контентом!
+
+---

package/docs/uk/testing.md

@@ -0,0 +1,204 @@
+---
+createdAt: 2025-03-01
+updatedAt: 2025-10-05
+title: Тестування вашого контенту
+description: Дізнайтеся, як тестувати ваш контент за допомогою Intlayer.
+keywords:
+  - Тестування
+  - Intlayer
+  - Інтернаціоналізація
+  - CMS
+  - Система управління контентом
+  - Візуальний редактор
+slugs:
+  - doc
+  - testing
+history:
+  - version: 6.0.1
+    date: 2025-10-05
+    changes: Зробити тест асинхронним і додати опцію build
+  - version: 6.0.0
+    date: 2025-09-20
+    changes: Впровадження тестування
+---
+
+# Тестування вашого контенту
+
+Цей посібник показує, як автоматично перевіряти повноту ваших словників, виявляти відсутні переклади до релізу та тестувати локалізований UI у вашому додатку.
+
+---
+
+## Що ви можете перевірити
+
+- **Відсутні переклади**: провалювати CI, якщо для будь-якого словника відсутні обов'язкові локалі.
+- **Локалізований рендер UI**: відрендерити компоненти з провайдером конкретної локалі та перевірити видимий текст/атрибути.
+- **Перевірки під час збірки**: швидко виконати аудит локально через CLI.
+
+---
+
+## Швидкий старт: аудит через CLI
+
+Запустіть аудит з кореня вашого проєкту:
+
+```bash
+npx intlayer content test
+```
+
+Корисні прапорці:
+
+- `--env-file [path]`: завантажити змінні середовища з файлу.
+- `-e, --env [name]`: вибрати профіль середовища.
+- `--base-dir [path]`: встановити базову директорію додатку для вирішення шляхів.
+- `--verbose`: показувати детальні логи.
+- `--prefix [label]`: додавати префікс до рядків логу.
+- `--build [build]`: збирати словники перед тестуванням, щоб переконатися, що вміст актуальний. True примусово виконає збірку, false пропустить збірку, undefined дозволить використовувати кеш збірки.
+
+Примітка: CLI виводить детальний звіт, але не завершує виконання з ненульовим кодом при помилках. Для контролю в CI додайте модульний тест (нижче), який перевіряє, що кількість відсутніх обов'язкових локалей дорівнює нулю.
+
+---
+
+## Програмний тест (Vitest/Jest)
+
+Використайте API Intlayer CLI, щоб переконатися, що для обов'язкових локалей немає відсутніх перекладів.
+
+```ts fileName=i18n.test.ts
+/* @vitest-environment node */
+import { listMissingTranslations } from "intlayer/cli";
+import { describe, expect, it } from "vitest";
+
+describe("translations", () => {
+  it("has no missing required locales", async () => {
+    const result = await listMissingTranslations();
+
+    if (result.missingRequiredLocales.length > 0) {
+      // Корисно, коли тест не проходить локально або в CI
+      console.log(result.missingTranslations);
+    }
+
+    expect(result.missingRequiredLocales).toHaveLength(0);
+  });
+});
+```
+
+Jest еквівалент:
+
+```ts fileName=i18n.test.ts
+import { listMissingTranslations } from "intlayer/cli";
+
+test("has no missing required locales", async () => {
+  const result = await listMissingTranslations();
+
+  if (result.missingRequiredLocales.length > 0) {
+    // Корисно, коли тест не проходить локально або в CI
+    console.log(result.missingTranslations);
+  }
+
+  expect(result.missingRequiredLocales).toHaveLength(0);
+});
+```
+
+Як це працює:
+
+- Intlayer читає вашу конфігурацію (locales, requiredLocales) та оголошені словники, а потім звітує:
+  - `missingTranslations`: по‑ключу — які локалі відсутні та з якого файлу.
+  - `missingLocales`: об'єднання всіх відсутніх локалей.
+  - `missingRequiredLocales`: підмножина, обмежена `requiredLocales` (або всі локалі, якщо `requiredLocales` не встановлено).
+
+---
+
+## Тестування локалізованого інтерфейсу (React / Next.js)
+
+Рендерте компоненти під провайдером Intlayer та перевіряйте видимий вміст.
+
+Приклад для React (Testing Library):
+
+```tsx
+import { IntlayerProvider } from "react-intlayer/client";
+import { render, screen } from "@testing-library/react";
+import { MyComponent } from "./MyComponent";
+
+test("рендерить локалізований заголовок англійською", () => {
+  render(
+    <IntlayerProvider locale="en-US">
+      <MyComponent />
+    </IntlayerProvider>
+  );
+
+  expect(
+    screen.getByText("Очікуваний заголовок англійською")
+  ).toBeInTheDocument();
+});
+```
+
+Next.js (App Router) example: use the framework wrapper:
+
+```tsx
+import { IntlayerClientProvider } from "next-intlayer/client";
+import { render, screen } from "@testing-library/react";
+import { MyPage } from "./MyPage";
+
+test("відображає локалізований заголовок французькою", () => {
+  render(
+    <IntlayerClientProvider locale="fr-FR">
+      <MyPage />
+    </IntlayerClientProvider>
+  );
+  expect(
+    screen.getByRole("heading", { name: "Titre attendu" })
+  ).toBeInTheDocument();
+});
+```
+
+Поради:
+
+- Коли потрібні сирі рядкові значення для атрибутів (наприклад, `aria-label`), отримуйте поле `.value`, яке повертає `useIntlayer` в React.
+- Тримайте словники поруч з компонентами для спрощення юніт-тестування та очищення.
+
+---
+
+## Неперервна інтеграція
+
+Додайте тест, який завершуватиме збірку з помилкою, коли відсутні обов'язкові переклади.
+
+`package.json`:
+
+```json
+{
+  "scripts": {
+    "test:i18n": "vitest run -c"
+  }
+}
+```
+
+Приклад GitHub Actions:
+
+```yaml
+name: CI
+on: [push, pull_request]
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+      - run: npm ci
+      - run: npm run test:i18n
+```
+
+Необов'язково: запустіть аудит CLI, щоб отримати зрозумілий для людини підсумок разом із тестами:
+
+```bash
+npx intlayer content test --verbose
+```
+
+---
+
+## Усунення неполадок
+
+- Переконайтеся, що ваша конфігурація Intlayer визначає `locales` і (за потреби) `requiredLocales`.
+- Якщо ваш застосунок використовує динамічні або віддалені словники, запускайте тести в середовищі, де ці словники доступні.
+- Для змішаних монорепозиторіїв використовуйте `--base-dir`, щоб вказати CLI правильний корінь застосунку.
+
+---