Sync JSON (містки i18n) - Синхронізація JSON з підтримкою ICU / i18next

Використовуйте 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 для рендерингу.

Встановлення

pnpm add -D @intlayer/sync-json-plugin# ornpm 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-бібліотеку.

Використання обох плагінів

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.

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):

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:

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, можливо, краще не встановлювати форматер.

Приклад:

syncJSON({  source: ({ key, locale }) => `./locales/${locale}/${key}.json`,  format: "i18next", // Використовувати форматування i18next для сумісності}),

Кілька джерел JSON та пріоритет

Ви можете додавати кілька плагінів syncJSON для синхронізації різних джерел JSON. Це корисно, коли у вашому проєкті використовується декілька i18n бібліотек або різні структури JSON.

Система пріоритетів

Коли декілька плагінів орієнтуються на той самий ключ словника, параметр priority визначає, який плагін матиме перевагу:

• Вищі значення пріоритету мають перевагу над нижчими
• Пріоритет за замовчуванням для файлів .content, 0
• Пріоритет плагінів за замовчуванням, 0
• Плагіни з однаковим пріоритетом обробляються в порядку їхнього розміщення в конфігурації

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. Цей плагін лише для читання (без запису на диск):

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;

Альтернатива: макет по локалях, все ще лише для читання (завантажується тільки обрана локаль):

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

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).

Приклад:

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 для детальнішої інформації.

Поточні обмеження

• Відсутня підтримка вставок або plurals/ICU при орієнтації на сторонні бібліотеки.
• Візуальний редактор поки недоступний для рантаймів, що не є Intlayer.
• Підтримується лише синхронізація JSON; формати каталогів, відмінні від JSON, не підтримуються.

Чому це важливо

• Ми можемо рекомендувати усталені i18n-рішення й позиціонувати Intlayer як доповнення.
• Ми використовуємо їхнє SEO та ключові слова через навчальні матеріали, які наприкінці пропонують використовувати Intlayer для керування JSON.
• Розширює цільову аудиторію з «нових проєктів» до «будь-якої команди, що вже використовує i18n».