@intlayer/docs 9.4.4 → 9.5.0

package/blog/uk/next-i18next_vs_next-intl_vs_intlayer.md

@@ -34,16 +34,12 @@ author: aymericzip
 >
 > Частою помилкою розробників є думка, що `next-intl`, це версія `react-intl` для Next.js. Це не так: `next-intl` підтримується [Amann](https://github.com/amannn), тоді як `react-intl` підтримується [FormatJS](https://github.com/formatjs/formatjs).
 
----
-
 ## Коротко
 
 - **next-intl** - Легкий, простий механізм форматування повідомлень із надійною підтримкою Next.js. Центральні каталоги є поширеними; DX простий, але безпека та масштабне обслуговування переважно залишаються вашою відповідальністю.
 - **next-i18next** - i18next у варіанті для Next.js. Зріла екосистема та функціональність через плагіни (наприклад, ICU), але конфігурація може бути громіздкою, а каталоги мають тенденцію централізуватися в міру зростання проєкту.
 - **Intlayer** - Компонентно-орієнтована модель контенту для Next.js, **строга типізація TS**, **перевірки на етапі збірки**, **tree-shaking**, **вбудовані middleware і SEO-помічники**, опційний **візуальний редактор/CMS** та **AI-підтримані переклади**.
 
----
-
 | Бібліотека             | Зірки GitHub                                                                                                                                                                            | Загальна кількість комітів                                                                                                                                                              | Останній коміт                                                                                                                                           | Перша версія  | Версія NPM                                                                                                          | Завантаження з NPM                                                                                                                |
 | ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- | ------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
 | `aymericzip/intlayer`  | [![Зірки репозиторію GitHub](https://img.shields.io/github/stars/aymericzip/intlayer?style=for-the-badge&label=%E2%AD%90%20stars)](https://github.com/aymericzip/intlayer/stargazers)   | [![Активність комітів GitHub](https://img.shields.io/github/commit-activity/t/aymericzip/intlayer?style=for-the-badge&label=commits)](https://github.com/aymericzip/intlayer/commits)   | [![Останній коміт](https://img.shields.io/github/last-commit/aymericzip/intlayer?style=for-the-badge)](https://github.com/aymericzip/intlayer/commits)   | квітень 2024  | [![npm](https://img.shields.io/npm/v/intlayer?style=for-the-badge)](https://www.npmjs.com/package/intlayer)         | [![завантаження npm](https://img.shields.io/npm/dm/intlayer?style=for-the-badge)](https://www.npmjs.com/package/intlayer)         |
@@ -53,8 +49,6 @@ author: aymericzip
 
 > Значки оновлюються автоматично. Знімки можуть змінюватися з часом.
 
----
-
 ## Порівняння функцій бок-о-бок (орієнтовано на Next.js)
 
 | Функція                                                         | `next-intlayer` (Intlayer)                                                                                                                         | `next-intl`                                                                                                                   | `next-i18next`                                                                                                                |
@@ -80,16 +74,12 @@ author: aymericzip
 | **Управління великими проєктами**                               | ✅ Заохочує модульність, підходить для дизайн-систем                                                                                               | ✅ Модульний за умови налаштування                                                                                            | ✅ Модульний за умови налаштування                                                                                            |
 | **Тестування відсутніх перекладів (CLI/CI)**                    | ✅ CLI: `npx intlayer content test` (аудит, придатний для CI)                                                                                      | ⚠️ Не вбудовано; у документації радять `npx @lingual/i18n-check`                                                              | ⚠️ Не вбудовано; покладається на інструменти i18next або runtime `saveMissing`                                                |
 
----
-
 ## Вступ
 
 Next.js надає вбудовану підтримку інтернаціоналізованої маршрутизації (наприклад, locale segments). Але ця функція сама по собі не виконує переклади. Вам все одно потрібна бібліотека, щоб відображати локалізований контент користувачам.
 
 Існує багато i18n-бібліотек, але в екосистемі Next.js сьогодні три з них набувають популярності: next-i18next, next-intl та Intlayer.
 
----
-
 ## Архітектура та масштабованість
 
 /// **next-intl / next-i18next**: За замовчуванням використовують **централізовані каталоги** для кожної локалі (плюс **namespaces** у i18next). Добре працює на початкових етапах, але часто перетворюється на велику спільну поверхню зі зростаючою зв’язністю та хаотичністю ключів.
@@ -175,8 +165,6 @@ Next.js надає вбудовану підтримку інтернаціон
 | -------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
 | ![оптимізований бандл](https://github.com/aymericzip/intlayer/blob/main/docs/assets/bundle.png?raw=true) | ![неоптимізований бандл](https://github.com/aymericzip/intlayer/blob/main/docs/assets/bundle_no_optimization.png?raw=true) |
 
----
-
 ## TypeScript і безпека
 
 <Columns>
@@ -201,12 +189,11 @@ Next.js надає вбудовану підтримку інтернаціон
 - **Генерує строгі типи** з вашого контенту. **Автодоповнення IDE** та **помилки на етапі компіляції** виявляють опечатки та відсутні ключі перед деплоєм.
 
   </Column>
+
 </Columns>
 
 **Чому це важливо:** Сильна типізація зміщує помилки вліво (CI/build) замість вправо (runtime).
 
----
-
 ## Обробка відсутніх перекладів
 
 <Columns>
@@ -231,12 +218,11 @@ Next.js надає вбудовану підтримку інтернаціон
 - **Виявлення під час збірки** з **попередженнями/помилками** для відсутніх локалей або ключів.
 
   </Column>
+
 </Columns>
 
 **Чому це важливо:** Виявлення прогалин під час збірки запобігає появі 'undefined' рядків у продакшені.
 
----
-
 ## Маршрутизація, middleware та стратегія URL
 
 <Columns>
@@ -263,12 +249,11 @@ Next.js надає вбудовану підтримку інтернаціон
 - Надає middleware.
 
   </Column>
+
 </Columns>
 
 **Чому це важливо:** Допомагає для SEO, покращує видимість і досвід користувача.
 
----
-
 ## Узгодження із Server Components (RSC)
 
 <Columns>
@@ -296,12 +281,11 @@ Next.js надає вбудовану підтримку інтернаціон
 - Надає синхронний API для дочірніх серверних компонент.
 
   </Column>
+
 </Columns>
 
 **Чому це важливо:** Підтримка серверних компонент, ключова особливість Next.js 13+, що покращує продуктивність. Передача через props `locale` або функції `t` від батьківської до дочірньої серверної компоненти робить ваші компоненти менш повторно використовуваними.
 
----
-
 ## Інтеграція з платформами локалізації (TMS)
 
 Великі організації часто покладаються на системи керування перекладами (TMS), такі як **Crowdin**, **Phrase**, **Lokalise**, **Localizely** або **Localazy**.
@@ -321,8 +305,6 @@ Next.js надає вбудовану підтримку інтернаціон
 
 > Примітка: `next-intl` та `i18next` також підтримують TypeScript-каталоги. Якщо ваша команда зберігає повідомлення в файлах `.ts` або децентралізує їх за функціоналом, ви можете зіштовхнутися з подібними проблемами інтеграції з TMS. Однак багато налаштувань `next-intl` залишаються централізованими в папці `locales/`, що трохи простіше перетворити в JSON для TMS.
 
----
-
 ## Досвід розробника
 
 У цій частині виконується детальне порівняння трьох рішень. Замість розгляду простих випадків, як описано в розділі 'Початок роботи' для кожного рішення, ми розглянемо реальний сценарій використання, ближчий до справжнього проєкту.
@@ -954,8 +936,6 @@ const ClientComponentExample = () => {
   - **next-intl** гнучкий; завантажуйте повідомлення так, як ви налаштуєте.
   - **Intlayer** зберігає контент у словниках TS/JS та звертається по ключу.
 
----
-
 ### Використання в server component
 
 Розглянемо випадок UI-компонента. Цей компонент, server component, і він повинен мати можливість бути вставленим як дочірній елемент client component. (page (server component) -> client component -> server component). Оскільки цей компонент може бути вставлений як дочірній елемент client component, він не може бути async.
@@ -1068,7 +1048,7 @@ const ServerComponent = ({ count }: ServerComponentProps) => {
 Розробники часто забувають правильно посилатися на свої сторінки в різних локалях.
 
 <Tabs defaultTab="next-intl" group='techno'>
- 
+
   <Tab label="next-i18next" value="next-i18next">
 
 ```ts fileName="i18n.config.ts"
@@ -1451,9 +1431,8 @@ export const config = {
 - **Вбудовані інструменти**: Скористайтеся вбудованим роутингом, допоміжними інструментами для SEO та підтримкою візуального редактора.
 
   </Tab>
-</Tabs>
 
----
+</Tabs>
 
 ## А переможець…
 
@@ -1481,6 +1460,7 @@ export const config = {
 - створений для сучасного Next.js, з модульним контентом, type safety, інструментами та меншим boilerplate. Якщо ви цінуєте **component-scoped content**, **strict TypeScript**, **build-time guarantees**, **tree-shaking**, і **batteries-included** інструменти для маршрутизації/SEO/редакторів, особливо для **Next.js App Router**, design-systems та **великих, модульних codebases**.
 
   </Column>
+
 </Columns>
 
 Якщо ви віддаєте перевагу мінімальній конфігурації і готові до деякої ручної інтеграції, next-intl, хороший вибір. Якщо вам потрібні всі функції і вас не лякає складність, next-i18next теж підходить. Але якщо ви хочете сучасне, масштабоване, модульне рішення з готовими інструментами, Intlayer прагне надати це "з коробки".
@@ -1495,8 +1475,6 @@ export const config = {
 
 [![Графік історії зірок](https://api.star-history.com/chart?repos=i18next/next-i18next%2Camannn/next-intl%2Caymericzip/intlayer&type=date&legend=top-left)](https://www.star-history.com/#i18next/next-i18next&amannn/next-intl&aymericzip/intlayer)
 
----
-
 ## Висновок
 
 Усі три бібліотеки успішно справляються з базовою локалізацією. Різниця полягає в тому, **скільки роботи вам доведеться виконати**, щоб досягти надійної, масштабованої конфігурації в **сучасному Next.js**:

package/blog/uk/nextjs-multilingual-seo-comparison.md

@@ -26,8 +26,6 @@ author: aymericzip
 
 У цьому блозі ми розглянемо, чому **i18n, це суперсила для SEO**, і як правильно реалізувати її в Next.js за допомогою `next-intl`, `next-i18next` та `Intlayer`.
 
----
-
 ## Чому SEO та i18n
 
 Додавання мов, це не лише про UX. Це також потужний важіль для **органічної видимості**. Ось чому:
@@ -37,8 +35,6 @@ author: aymericzip
 3. **Кращий UX:** Відвідувачі потрапляють одразу на потрібну версію вашого сайту.
 4. **Конкурентна перевага:** Лише небагато сайтів правильно реалізують багатомовне SEO, тож ви можете виділитися.
 
----
-
 ## Найкращі практики для багатомовного SEO в Next.js
 
 Ось контрольний список, який має реалізувати кожен багатомовний додаток:
@@ -57,8 +53,6 @@ author: aymericzip
 
 Це прості кроки, але їх пропуск може коштувати вам видимості.
 
----
-
 ## Приклади реалізації
 
 Розробники часто забувають правильно посилатися на свої сторінки для різних локалей, тож давайте подивимось, як це працює на практиці з різними бібліотеками.
@@ -341,14 +335,10 @@ export default robots;
   </Tab>
 </Tabs>
 
----
-
 ## Перевірте свій веб-сайт за допомогою Intlayer SEO Scanner
 
 Щоб переконатися, що ваш багатомовний додаток ідеально оптимізовано, ми рекомендуємо використовувати [Intlayer SEO Scanner](https://intlayer.org/i18n-seo-scanner). Це спеціалізований інструмент для перевірки багатомовних веб-сайтів, який допомагає виявити відсутні теги hreflang, непрацюючі посилання та інші проблеми SEO на всіх ваших локалізованих сторінках.
 
----
-
 ## Висновок
 
 Правильна реалізація i18n у Next.js, це не просто переклад тексту, а забезпечення того, щоб пошукові системи та користувачі точно знали, яку версію вашого контенту показувати.

package/blog/uk/rag_powered_documentation_assistant.md

@@ -71,7 +71,6 @@ RAG став популярним не випадково: це один із н
 6.  **Логування запитів для зворотного зв'язку** Кожен запит користувача зберігається. Це золото для розуміння больових точок, відсутньої документації або нових можливостей.
 
 <Steps>
-
 <Step number={1} title="Читання документації">
 
 Перший крок був простим: мені потрібно було просканувати папку docs/ на предмет усіх .md файлів. Використовуючи Node.js та glob, я завантажив вміст кожного Markdown-файлу в пам'ять.
@@ -79,7 +78,6 @@ RAG став популярним не випадково: це один із н
 Це робить конвеєр гнучким: замість Markdown ви можете отримувати документацію з бази даних, CMS або навіть через API.
 
 </Step>
-
 <Step number={2} title="Розбиття документації на чанки">
 
 Навіщо розбивати? Тому що мовні моделі мають **обмеження контексту**. Підживлення їх цілою книгою документації не спрацює.
@@ -103,7 +101,6 @@ RAG став популярним не випадково: це один із н
 - Занадто великий → ви перевантажите розмір контексту.
 
 </Step>
-
 <Step number={3} title="Генерація embeddings">
 
 Як тільки документи розбиті на чанки, ми генеруємо **embeddings**, високорозмірні вектори, що представляють кожний чанк.
@@ -123,7 +120,6 @@ RAG став популярним не випадково: це один із н
 Кожний вектор, це математичний відбиток тексту, що дозволяє виконувати пошук за схожістю.
 
 </Step>
-
 <Step number={4} title="Індексування та збереження embeddings">
 
 Щоб уникнути багаторазової регенерації embeddings, я зберіг їх у embeddings.json.
@@ -138,7 +134,6 @@ RAG став популярним не випадково: це один із н
 Векторні БД обробляють індексування, масштабованість і швидкий пошук. Але для мого прототипу локальний JSON працював добре.
 
 </Step>
-
 <Step number={5} title="Отримання за допомогою **косинусної схожості**">
 
 Коли користувач ставить запитання:
@@ -152,7 +147,6 @@ RAG став популярним не випадково: це один із н
 Таким чином система знаходить найближчі фрагменти документації до запиту.
 
 </Step>
-
 <Step number={6} title="Розширення (Augmentation) + Генерація">
 
 Тепер починається магія. Ми беремо топові сегменти та вставляємо їх у **system prompt** для ChatGPT.
@@ -162,7 +156,6 @@ RAG став популярним не випадково: це один із н
 Результат: точні, **відповіді, засновані на документації**.
 
 </Step>
-
 <Step number={7} title="Логування запитів користувачів">
 
 Це прихована суперсила.
@@ -177,7 +170,6 @@ RAG став популярним не випадково: це один із н
 This turns your RAG assistant into a **continuous user research tool**.
 
 </Step>
-
 <Step number={8} title="Скільки це коштує?">
 
 Одне з поширених зауважень щодо RAG, це вартість. Насправді це дивно дешево:
@@ -189,7 +181,6 @@ This turns your RAG assistant into a **continuous user research tool**.
 Крім того, можна додати вартість хостингу.
 
 </Step>
-
 <Step number={9} title="Деталі реалізації">
 
 Стек:
@@ -255,7 +246,6 @@ User query :
 👉 [Спробувати демо тут](https://intlayer.org/doc/why) 👉 [Переглянути шаблон коду на GitHub](https://github.com/aymericzip/smart_doc_RAG)
 
 </Step>
-
 <Step number={10} title="Подальші кроки">
 
 Цей проєкт, мінімальна реалізація. Але ви можете розширити його багатьма способами:
@@ -269,7 +259,6 @@ User query :
 - Покращені підказки → reranking, filtering та гібридний пошук (ключові слова + семантичний)
 
 </Step>
-
 <Step number={11} title="Обмеження, з якими ми зіткнулися">
 
 - Розбивка на фрагменти (chunking) та перекриття мають емпіричний характер. Пошук правильного балансу (розмір фрагмента, відсоток перекриття, кількість витягнутих фрагментів) вимагає ітерацій та тестування.
@@ -277,7 +266,6 @@ User query :
 - У цьому прототипі embeddings зберігаються в JSON. Це підходить для демо, але засмічує репозиторій Git. В продакшні краще використовувати базу даних або спеціалізоване сховище векторів (vector store).
 
 </Step>
-
 <Step number={12} title="Чому це важливо поза межами документації">
 
 Цікаво не лише в чат-боті. Це, механізм зворотного зв'язку (feedback loop).
@@ -299,7 +287,6 @@ User query :
 Це, **product intelligence** прямо від ваших користувачів.
 
 </Step>
-
 <Step number={13} title="Висновок">
 
 RAG, це один із найпростіших і найпотужніших способів зробити LLMs практичними. Поєднавши **retrieval + generation**, ви можете перетворити статичну документацію на **smart assistant** і, одночасно, отримувати безперервний потік insights про продукт.

package/blog/uk/react-i18next_vs_react-intl_vs_intlayer.md

@@ -37,16 +37,12 @@ author: aymericzip
 
 > **tl;dr**: Усі три можуть локалізувати React-додаток. Якщо ви хочете **контент, прив'язаний до компонентів**, **суворі TypeScript-типи**, **перевірки відсутніх ключів під час збірки**, **tree-shaken словники**, та вбудовані редакційні інструменти (Visual Editor/CMS + необов'язковий AI-переклад), **Intlayer** є найповнішим вибором для модульних React-кодових баз.
 
----
-
 ## Високорівневе позиціонування
 
 - **react-intl** - орієнтований на ICU, форматування, узгоджене зі стандартами (дати/числа/множини), зі зрілим API. Каталоги зазвичай централізовані; безпека ключів і перевірки на етапі збірки в основному на вас.
 - **react-i18next** - надзвичайно популярний і гнучкий; namespaces, detectors і багато плагінів (ICU, backends). Потужний, але конфігурація може розростатися зі збільшенням проєкту.
 - **Intlayer** - модель контенту, орієнтована на компоненти для React, зі **строгим типізуванням TS**, **перевірками на етапі збірки**, **tree-shaking**, а також **Visual Editor/CMS** і **AI‑асистованими перекладами**. Працює з React Router, Vite, CRA тощо.
 
----
-
 ## Матриця функцій (фокус на React)
 
 | Особливість                                                     | `react-intlayer` (Intlayer)                                                                                                                  | `react-i18next` (i18next)                                                                                                    | `react-intl` (FormatJS)                                                                                   |
@@ -71,8 +67,6 @@ author: aymericzip
 | **Очищення невикористовуваного контенту**                       | ✅ Так, для кожного словника під час збірки                                                                                                  | ❌ Ні, лише через ручну сегментацію неймспейсів                                                                              | ❌ Ні, усі оголошені повідомлення включені в бандл                                                        |
 | **Управління великими проєктами**                               | ✅ Заохочує модульність, підходить для design-system                                                                                         | ⚠️ Потребує доброї дисципліни в організації файлів                                                                           | ⚠️ Центральні каталоги можуть стати великими                                                              |
 
----
-
 ## Поглиблене порівняння
 
 ### 1) Архітектура та масштабованість
@@ -82,8 +76,6 @@ author: aymericzip
 
 **Чому це важливо:** Модульний контент відображає модульний UI. Великі React codebases залишаються чистішими, коли переклади живуть разом із компонентами, яким вони належать.
 
----
-
 ### 2) TypeScript & безпека
 
 - **react-intl**: Надійна типізація, але **немає автоматичної типізації ключів**; вам доводиться самостійно запроваджувати патерни для забезпечення безпеки.
@@ -92,8 +84,6 @@ author: aymericzip
 
 **Чому це важливо:** Перенесення помилок **вліво** (на етап збірки/CI) зменшує проблеми в продакшені та пришвидшує цикл зворотного зв’язку для розробників.
 
----
-
 ### 3) Обробка відсутніх перекладів
 
 - **react-intl / react-i18next**: За замовчуванням використовують **запасні варіанти під час виконання** (відображення ключа або локаль за замовчуванням). Можна додати лінтери/плагіни, але це не гарантується на етапі збірки.
@@ -101,8 +91,6 @@ author: aymericzip
 
 **Чому це важливо:** Якщо CI падає через відсутні рядки, це запобігає витоку «таємної англійської» в інтерфейси іншими мовами.
 
----
-
 ### 4) Багатий контент і форматування
 
 - **react-intl**: Відмінна підтримка **ICU** для plurals, selects, дат/чисел та композиції повідомлень. Можна використовувати JSX, але ментальна модель залишається орієнтованою на повідомлення.
@@ -111,8 +99,6 @@ author: aymericzip
 
 **Чому це важливо:** Складні тексти інтерфейсу (посилання, виділені фрагменти, інлайнові компоненти) простіше реалізовувати, коли бібліотека природно працює з React-нодами.
 
----
-
 ### 5) Продуктивність і поведінка завантаження
 
 - **react-intl / react-i18next**: Зазвичай ви вручну керуєте **розбиттям каталогів (catalog splitting)** та **ледачим завантаженням (lazy loading)** (namespaces/dynamic imports). Ефективно, але вимагає дисципліни.
@@ -120,8 +106,6 @@ author: aymericzip
 
 **Чому це важливо:** Менші бандли і менше невикористаних рядків покращують час запуску та продуктивність навігації.
 
----
-
 ### 6) DX, інструменти та супровід
 
 - **react-intl / react-i18next**: Широка екосистема спільноти; для редакційних робочих процесів ви зазвичай використовуєте зовнішні платформи локалізації.
@@ -129,24 +113,18 @@ author: aymericzip
 
 **Чому це важливо:** Вбудовані інструменти скорочують цикл між розробниками та авторами контенту, менше допоміжного коду, менше залежностей від постачальників.
 
----
-
 ## Коли обирати який варіант?
 
 - **Оберіть react-intl** якщо ви хочете **форматування повідомлень, орієнтоване на ICU**, з простим, відповідним стандартам API, і ваша команда комфортно підтримує каталоги та перевірки вручну.
 - **Оберіть react-i18next** якщо вам потрібна **широта екосистеми i18next** (детектори, бекенди, плагін ICU, інтеграції) і ви готові до більшої конфігурації заради гнучкості.
 - **Обирайте Intlayer** якщо ви цінуєте **component-scoped content**, **strict TypeScript**, **build-time guarantees**, **tree-shaking** та **batteries-included** редакторські інструменти, особливо для **large, modular** React-додатків, design-systems тощо.
 
----
-
 ## Сумісність з `react-intl` та `react-i18next`
 
 `intlayer` також може допомогти керувати вашими неймспейсами `react-intl` і `react-i18next`.
 
 Використовуючи `intlayer`, ви можете оголошувати ваш контент у форматі улюбленої i18n-бібліотеки, і intlayer згенерує ваші неймспейси у вибраному місці (приклад: `/messages/{{locale}}/{{namespace}}.json`).
 
----
-
 ## Зірки GitHub
 
 GitHub-зірки, це вагомий індикатор популярності проєкту, довіри спільноти та його довгострокової релевантності. Хоча вони не є прямим показником технічної якості, вони відображають, скільки розробників вважають проєкт корисним, стежать за його розвитком і ймовірно його приймуть. Для оцінки цінності проєкту зірки допомагають порівнювати популярність між альтернативами та дають уявлення про зростання екосистеми.