@intlayer/docs 7.5.12 → 7.5.14

package/docs/uk/plugins/sync-json.md

@@ -0,0 +1,398 @@
+---
+createdAt: 2025-03-13
+updatedAt: 2025-12-13
+title: Плагін Sync JSON
+description: Синхронізуйте словники Intlayer із зовнішніми i18n JSON-файлами (i18next, next-intl, react-intl, vue-i18n та ін.). Залишайте ваш існуючий i18n-стек і використовуйте Intlayer для керування, перекладу та тестування повідомлень.
+keywords:
+  - Intlayer
+  - Sync JSON
+  - i18next
+  - next-intl
+  - react-intl
+  - vue-i18n
+  - next-translate
+  - nuxt-i18n
+  - LinguiJS
+  - Polyglot.js
+  - Solid-i18next
+  - svelte-i18n
+  - i18n
+  - переклади
+slugs:
+  - doc
+  - plugin
+  - sync-json
+youtubeVideo: https://www.youtube.com/watch?v=MpGMxniDHNg
+history:
+  - version: 7.5.0
+    date: 2025-12-13
+    changes: Додано підтримку форматів ICU та i18next
+  - version: 6.1.6
+    date: 2025-10-05
+    changes: Початкова документація плагіна Sync JSON
+---
+
+# Sync JSON (містки i18n) - Синхронізація JSON з підтримкою ICU / i18next
+
+<iframe title="Як синхронізувати ваші JSON-переклади з Intlayer" class="m-auto aspect-16/9 w-full overflow-hidden rounded-lg border-0" allow="autoplay; gyroscope;" loading="lazy" width="1080" height="auto" src="https://www.youtube.com/embed/MpGMxniDHNg?autoplay=0&amp;origin=http://intlayer.org&amp;controls=0&amp;rel=1"/>
+
+Використовуйте Intlayer як додаток до вашого існуючого стеку i18n. Цей плагін синхронізує ваші JSON-повідомлення зі словниками Intlayer, тож ви можете:
+
+- Продовжувати використовувати i18next, next‑intl, react‑intl, vue‑i18n, next‑translate, nuxt‑i18n, Solid‑i18next, svelte‑i18n тощо.
+- Керувати та перекладати ваші повідомлення за допомогою Intlayer (CLI, CI, providers, CMS), без рефакторингу додатка.
+- Публікуйте навчальні матеріали та SEO‑контент, орієнтований на кожну екосистему, пропонуючи Intlayer як шар управління JSON.
+
+Зауваги та поточна область охоплення:
+
+- Екстерналізація в CMS працює для перекладів та звичайного тексту.
+- Поки що немає підтримки вставок, форм множини/ICU або розширених runtime‑функцій інших бібліотек.
+- Візуальний редактор поки що не підтримується для виходів сторонніх i18n‑бібліотек.
+
+### Коли використовувати цей плагін
+
+- Ви вже використовуєте i18n‑бібліотеку та зберігаєте повідомлення в JSON‑файлах.
+- Ви хочете AI‑допомогу при заповненні, тестування в CI та операції з контентом без зміни runtime для рендерингу.
+
+## Встановлення
+
+```bash
+pnpm add -D @intlayer/sync-json-plugin
+# or
+npm i -D @intlayer/sync-json-plugin
+```
+
+## Плагіни
+
+Цей пакет надає два плагіни:
+
+- `loadJSON`: Завантажувати JSON‑файли в словники Intlayer.
+  - Цей плагін використовується для завантаження JSON-файлів з джерела і поміщає їх у словники Intlayer. Він може просканувати весь codebase і знайти конкретні JSON-файли.
+    Цей плагін можна використовувати
+    - якщо ви використовуєте i18n-бібліотеку, яка вимагає певного розташування для завантаження ваших JSON (наприклад: `next-intl`, `i18next`, `react-intl`, `vue-i18n` тощо), але ви хочете розміщувати декларації контенту там, де вам зручно у вашому codebase.
+    - Також його можна використовувати, якщо ви хочете отримувати повідомлення з віддаленого джерела (наприклад: CMS, API тощо) і зберігати ці повідомлення в JSON-файлах.
+
+  > Під капотом цей плагін просканує весь codebase, знайде конкретні JSON-файли і завантажить їх у словники Intlayer.
+  > Зауважте, цей плагін не записує результат і переклади назад у JSON-файли.
+
+- `syncJSON`: Синхронізує JSON-файли зі словниками Intlayer.
+  - Цей плагін використовується для синхронізації JSON-файлів зі словниками Intlayer. Він може просканувати вказане розташування та завантажити JSON-файли, що відповідають заданому шаблону. Цей плагін корисний, якщо ви хочете отримати переваги Intlayer, використовуючи іншу i18n-бібліотеку.
+
+## Використання обох плагінів
+
+```ts fileName="intlayer.config.ts"
+import { Locales, type IntlayerConfig } from "intlayer";
+import { loadJSON, syncJSON } from "@intlayer/sync-json-plugin";
+
+const config: IntlayerConfig = {
+  internationalization: {
+    locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
+    defaultLocale: Locales.ENGLISH,
+  },
+
+  // Тримайте ваші поточні JSON-файли синхронізованими зі словниками Intlayer
+  plugins: [
+    /**
+     * Завантажить усі JSON-файли у src, що відповідають шаблону {key}.i18n.json
+     */
+    loadJSON({
+      source: ({ key }) => `./src/**/${key}.i18n.json`,
+      locale: Locales.ENGLISH,
+      priority: 1, // Ensures these JSON files take precedence over files at `./locales/en/${key}.json`
+      format: "intlayer", // Format of the JSON content
+    }),
+    /**
+     * Завантажить та запише результати й переклади назад у JSON-файли в директорії locales
+     */
+    syncJSON({
+      format: "i18next",
+      source: ({ key, locale }) => `./locales/${locale}/${key}.json`,
+      priority: 0,
+      format: "i18next",
+    }),
+  ],
+};
+
+export default config;
+```
+
+## Плагін `syncJSON`
+
+### Швидкий старт
+
+Додайте плагін до вашого `intlayer.config.ts` і вкажіть шлях до наявної структури JSON.
+
+```ts fileName="intlayer.config.ts"
+import { Locales, type IntlayerConfig } from "intlayer";
+import { syncJSON } from "@intlayer/sync-json-plugin";
+
+const config: IntlayerConfig = {
+  internationalization: {
+    locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
+    defaultLocale: Locales.ENGLISH,
+  },
+
+  // Підтримуйте поточні JSON-файли синхронізованими зі словниками Intlayer
+  plugins: [
+    syncJSON({
+      // Розміщення по локалі та namespace (наприклад, next-intl, i18next з namespaces)
+      source: ({ key, locale }) => `./locales/${locale}/${key}.json`,
+      format: "icu",
+    }),
+  ],
+};
+
+export default config;
+```
+
+Альтернатива: один файл на мову (поширено для налаштувань i18next/react-intl):
+
+```ts fileName="intlayer.config.ts"
+import { Locales, type IntlayerConfig } from "intlayer";
+import { syncJSON } from "@intlayer/sync-json-plugin";
+
+const config: IntlayerConfig = {
+  internationalization: {
+    locales: [Locales.ENGLISH, Locales.FRENCH],
+    defaultLocale: Locales.ENGLISH,
+  },
+  plugins: [
+    syncJSON({
+      format: "i18next",
+      source: ({ locale }) => `./locales/${locale}.json`,
+      format: "i18next",
+    }),
+  ],
+};
+
+export default config;
+```
+
+#### Як це працює
+
+- Зчитування: плагін знаходить JSON-файли через ваш builder `source` і завантажує їх як словники Intlayer.
+- Запис: після збірок і заповнення, він записує локалізований JSON назад за тими самими шляхами (з кінцевим символом нового рядка, щоб уникнути проблем з форматуванням).
+- Автозаповнення: плагін оголошує шлях `autoFill` для кожного словника. Запуск `intlayer fill` за замовчуванням оновлює лише відсутні переклади у ваших JSON-файлах.
+
+API:
+
+```ts
+syncJSON({
+  source: ({ key, locale }) => string, // обов'язково
+  location?: string, // необов'язковий ярлик, за замовчуванням: "plugin"
+  priority?: number, // необов'язковий пріоритет для вирішення конфліктів, за замовчуванням: 0
+  format?: 'intlayer' | 'icu' | 'i18next', // необов'язковий форматтер, використовується для сумісності з intlayer runtime
+});
+```
+
+#### `format` ('intlayer' | 'icu' | 'i18next')
+
+Визначає форматер, який буде використовуватися для вмісту словника під час синхронізації JSON-файлів. Це дозволяє використовувати різні синтакси форматування повідомлень, сумісні з Intlayer runtime.
+
+- `undefined`: Форматер не використовуватиметься, JSON-контент буде використовуватися як є.
+- `'intlayer'`: Форматер Intlayer за замовчуванням.
+- `'icu'`: Використовує форматування повідомлень ICU (сумісне з бібліотеками на кшталт react-intl, vue-i18n).
+- `'i18next'`: Використовує форматування повідомлень i18next (сумісне з i18next, next-i18next, Solid-i18next).
+
+> Зверніть увагу, що використання форматера перетворює ваш JSON-контент на вході та на виході. Для складних правил JSON, наприклад ICU plurals, парсинг може не забезпечити відповідності 1:1 між вхідними та вихідними даними. Якщо ви не використовуєте Intlayer runtime, можливо, краще не встановлювати форматер.
+
+**Приклад:**
+
+```ts
+syncJSON({
+  source: ({ key, locale }) => `./locales/${locale}/${key}.json`,
+  format: "i18next", // Використовувати форматування i18next для сумісності
+}),
+```
+
+### Кілька джерел JSON та пріоритет
+
+Ви можете додавати кілька плагінів `syncJSON` для синхронізації різних джерел JSON. Це корисно, коли у вашому проєкті використовується декілька i18n бібліотек або різні структури JSON.
+
+#### Система пріоритетів
+
+Коли декілька плагінів орієнтуються на той самий ключ словника, параметр `priority` визначає, який плагін матиме перевагу:
+
+- Вищі значення пріоритету мають перевагу над нижчими
+- Пріоритет за замовчуванням для файлів `.content` — `0`
+- Пріоритет плагінів за замовчуванням — `0`
+- Плагіни з однаковим пріоритетом обробляються в порядку їхнього розміщення в конфігурації
+
+```ts fileName="intlayer.config.ts"
+import { Locales, type IntlayerConfig } from "intlayer";
+import { syncJSON } from "@intlayer/sync-json-plugin";
+
+const config: IntlayerConfig = {
+  internationalization: {
+    locales: [Locales.ENGLISH, Locales.FRENCH],
+    defaultLocale: Locales.ENGLISH,
+  },
+
+  plugins: [
+    // Основне джерело JSON (найвищий пріоритет)
+    syncJSON({
+      format: "i18next",
+      source: ({ key, locale }) => `./locales/${locale}/${key}.json`,
+      location: "main-translations",
+      priority: 10,
+    }),
+
+    // Резервне джерело JSON (нижчий пріоритет)
+    syncJSON({
+      format: "i18next",
+      source: ({ locale }) => `./fallback-locales/${locale}.json`,
+      location: "fallback-translations",
+      priority: 5,
+    }),
+
+    // Спадкове джерело JSON (найнижчий пріоритет)
+    syncJSON({
+      format: "i18next",
+      source: ({ locale }) => `/my/other/app/legacy/${locale}/messages.json`,
+      location: "legacy-translations",
+      priority: 1,
+    }),
+  ],
+};
+
+export default config;
+```
+
+## Плагін loadJSON
+
+### Швидкий старт
+
+Додайте плагін у ваш `intlayer.config.ts`, щоб імпортувати наявні JSON-файли як словники Intlayer. Цей плагін лише для читання (без запису на диск):
+
+```ts fileName="intlayer.config.ts"
+import { Locales, type IntlayerConfig } from "intlayer";
+import { loadJSON } from "@intlayer/sync-json-plugin";
+
+const config: IntlayerConfig = {
+  internationalization: {
+    locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
+    defaultLocale: Locales.ENGLISH,
+  },
+
+  plugins: [
+    // Імпортувати JSON-повідомлення, розташовані в будь-якому місці структури вашого проєкту
+    loadJSON({
+      source: ({ key }) => `./src/**/${key}.i18n.json`,
+      // Завантажує одну локаль на екземпляр плагіна (за замовчуванням — config.defaultLocale)
+      locale: Locales.ENGLISH,
+      priority: 0,
+    }),
+  ],
+};
+
+export default config;
+```
+
+Альтернатива: макет по локалях, все ще лише для читання (завантажується тільки обрана локаль):
+
+```ts fileName="intlayer.config.ts"
+import { Locales, type IntlayerConfig } from "intlayer";
+import { loadJSON } from "@intlayer/sync-json-plugin";
+
+const config: IntlayerConfig = {
+  internationalization: {
+    locales: [Locales.ENGLISH, Locales.FRENCH],
+    defaultLocale: Locales.ENGLISH,
+  },
+  plugins: [
+    loadJSON({
+      // За цим шаблоном завантажуватимуться лише файли для Locales.FRENCH
+      source: ({ key, locale }) => `./locales/${locale}/${key}.json`,
+      locale: Locales.FRENCH,
+    }),
+  ],
+};
+
+export default config;
+```
+
+### Як це працює
+
+- Виявлення (Discover): будує glob з вашого `source` builder і збирає відповідні JSON-файли.
+- Імпорт (Ingest): завантажує кожен JSON-файл як словник Intlayer з вказаною `locale`.
+- Тільки для читання (Read‑only): не записує і не форматирує вихідні файли; використовуйте `syncJSON`, якщо вам потрібен двосторонній синхрон.
+- Готово до авто‑заповнення (Auto‑fill ready): визначає шаблон `fill`, щоб `intlayer content fill` міг заповнювати відсутні ключі.
+
+### API
+
+```ts
+loadJSON({
+  // Побудувати шляхи до ваших JSON-файлів. `locale` необов'язковий, якщо у вашій структурі немає сегмента локалі
+  source: ({ key, locale }) => string,
+
+  // Цільова локаль для словників, завантажених цим екземпляром плагіна
+  // За замовчуванням — configuration.internationalization.defaultLocale
+  locale?: Locale,
+
+  // Необов'язковий мітка для ідентифікації джерела
+  location?: string, // за замовчуванням: "plugin"
+
+  // Пріоритет, що використовується для вирішення конфліктів із іншими джерелами
+  priority?: number, // за замовчуванням: 0
+
+  // Необов'язковий форматувач для JSON-вмісту
+  format?: 'intlayer' | 'icu' | 'i18next', // за замовчуванням: 'intlayer'
+});
+```
+
+#### `format` ('intlayer' | 'icu' | 'i18next')
+
+Вказує форматувач, який використовується для вмісту словника при завантаженні JSON-файлів. Це дозволяє використовувати різні синтаксиси форматування повідомлень, сумісні з різними i18n-бібліотеками.
+
+- `'intlayer'`: Форматувач Intlayer за замовчуванням.
+- `'icu'`: Використовує форматування повідомлень ICU (сумісне з бібліотеками, такими як react-intl, vue-i18n).
+- `'i18next'`: Використовує форматування i18next (сумісне з i18next, next-i18next, Solid-i18next).
+
+**Приклад:**
+
+```ts
+loadJSON({
+  source: ({ key }) => `./src/**/${key}.i18n.json`,
+  locale: Locales.ENGLISH,
+  format: "icu", // Використовувати форматування ICU для сумісності
+}),
+```
+
+### Поведінка та конвенції
+
+- Якщо ваша маска `source` містить плейсхолдер локалі, імпортуються лише файли для обраної `locale`.
+- Якщо в масці немає сегмента `{key}`, ключ словника — "index".
+- Ключі виводяться зі шляхів файлів шляхом підстановки плейсхолдера `{key}` у вашому source builder.
+- Плагін використовує лише виявлені файли і не створює відсутні локалі чи ключі.
+- Шлях `fill` виводиться з вашого `source` і використовується для оновлення відсутніх значень через CLI, якщо ви погодитесь.
+
+## Вирішення конфліктів
+
+Коли один і той самий ключ перекладу існує в кількох JSON-джерелах:
+
+1. Плагін з найвищим пріоритетом визначає остаточне значення
+2. Джерела з нижчим пріоритетом використовуються як резервні джерела для відсутніх ключів
+3. Це дозволяє зберігати наявні (legacy) переклади під час поступової міграції до нових структур
+
+## Інтерфейс командного рядка (CLI)
+
+Синхронізовані JSON-файли розглядатимуться як інші `.content` файли. Це означає, що всі команди intlayer будуть доступні для синхронізованих JSON-файлів. Включно з:
+
+- `intlayer content test` — щоб перевірити, чи є відсутні переклади
+- `intlayer content list` — перелічити синхронізовані JSON-файли
+- `intlayer content fill` — заповнити відсутні переклади
+- `intlayer content push` — відправити (push) синхронізовані JSON-файли
+- `intlayer content pull` — отримати (pull) синхронізовані JSON-файли
+
+Дивіться [Intlayer CLI](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/cli/index.md) для детальнішої інформації.
+
+## Поточні обмеження
+
+- Відсутня підтримка вставок або plurals/ICU при орієнтації на сторонні бібліотеки.
+- Візуальний редактор поки недоступний для рантаймів, що не є Intlayer.
+- Підтримується лише синхронізація JSON; формати каталогів, відмінні від JSON, не підтримуються.
+
+## Чому це важливо
+
+- Ми можемо рекомендувати усталені i18n-рішення й позиціонувати Intlayer як доповнення.
+- Ми використовуємо їхнє SEO та ключові слова через навчальні матеріали, які наприкінці пропонують використовувати Intlayer для керування JSON.
+- Розширює цільову аудиторію з «нових проєктів» до «будь-якої команди, що вже використовує i18n».