Документація системи керування контентом Intlayer (CMS)

Intlayer CMS, це застосунок, який дозволяє винести вміст вашого проєкту Intlayer у зовнішню систему (CMS).

Для цього Intlayer вводить поняття «віддалених словників» (distant dictionaries).

Зміст

Розуміння віддалених словників

Intlayer розрізняє 'local' та 'remote' словники.

• 'local' словник, це словник, який оголошений у вашому проєкті Intlayer. Наприклад файл декларації кнопки або ваша панель навігації. Виносити контент назовні в такому випадку не має сенсу, оскільки цей контент зазвичай не змінюється часто.

• 'remote' словник, це словник, яким керують через Intlayer CMS. Це може бути корисно, щоб дозволити вашій команді керувати контентом безпосередньо на вашому вебсайті, а також для використання функцій A/B тестування та автоматичної SEO-оптимізації.

Візуальний редактор проти CMS

Редактор Intlayer Visual, це інструмент, який дозволяє керувати вашим вмістом у візуальному редакторі для локальних словників. Після внесення зміни вміст буде замінено в code-base. Це означає, що застосунок буде перебудовано, а сторінка перезавантажиться для відображення нового вмісту.

На відміну від цього, Intlayer CMS, це інструмент, який дозволяє керувати вмістом у візуальному редакторі для віддалених словників. Після внесення зміни вміст не вплине на ваш code-base. Вебсайт автоматично відобразить змінений вміст.

Інтеграція

Для детальнішої інформації про встановлення пакета див. відповідний розділ нижче:

Інтеграція з Next.js

Для інтеграції з Next.js зверніться до керівництва з налаштування.

Інтеграція з Create React App

Для інтеграції з Create React App зверніться до керівництва з налаштування.

Інтеграція з Vite + React

Для інтеграції з Vite + React зверніться до керівництва з налаштування.

Конфігурація

Запустіть наступну команду, щоб увійти в Intlayer CMS:

npx intlayer login

Це відкриє ваш браузер за замовчуванням, щоб завершити процес автентифікації й отримати необхідні облікові дані (Client ID та Client Secret) для використання сервісів Intlayer.

У файлі конфігурації Intlayer ви можете налаштувати параметри CMS:

import type { IntlayerConfig } from "intlayer";

const config: IntlayerConfig = {
  // ... інші налаштування конфігурації
  editor: {
    /**
     * Обов'язково
     *
     * URL застосунку.
     * Це URL, що використовується візуальним редактором.
     */
    applicationURL: process.env.INTLAYER_APPLICATION_URL,

    /**
     * Обов'язково
     *
     * Client ID та client secret потрібні для увімкнення редактора.
     * Вони дозволяють ідентифікувати користувача, який редагує контент.
     * Їх можна отримати, створивши нового клієнта в Intlayer Dashboard - Projects (https://app.intlayer.org/projects).
     * clientId: process.env.INTLAYER_CLIENT_ID,
     * clientSecret: process.env.INTLAYER_CLIENT_SECRET,
     */
    clientId: process.env.INTLAYER_CLIENT_ID,
    clientSecret: process.env.INTLAYER_CLIENT_SECRET,

    /**
     * Необов'язково
     *
     * Якщо ви розгортаєте Intlayer CMS самостійно, ви можете вказати URL CMS.
     *
     * URL Intlayer CMS.
     * За замовчуванням встановлено на https://intlayer.org
     */
    cmsURL: process.env.INTLAYER_CMS_URL,

    /**
     * Необов'язково
     *
     * У випадку, якщо ви самостійно розгортаєте Intlayer CMS, ви можете вказати URL бекенду.
     *
     * URL Intlayer CMS.
     * За замовчуванням встановлено на https://back.intlayer.org
     */
    backendURL: process.env.INTLAYER_BACKEND_URL,
  },
};

export default config;

Якщо у вас немає client ID та client secret, ви можете отримати їх, створивши нового клієнта в Intlayer Dashboard - Projects.

Щоб побачити всі доступні параметри, зверніться до документації з конфігурації.

Використання CMS

Надіслати вашу конфігурацію

Щоб налаштувати Intlayer CMS, ви можете використовувати команди intlayer CLI.

npx intlayer config push

Якщо ви використовуєте змінні оточення в файлі конфігурації intlayer.config.ts, ви можете вказати потрібне оточення за допомогою аргументу --env:

npx intlayer config push --env production

Ця команда завантажує вашу конфігурацію в Intlayer CMS.

Відправити словник

Щоб перетворити ваші локальні словники у віддалений словник, ви можете використовувати команди intlayer CLI.

npx intlayer dictionary push -d my-first-dictionary-key

Якщо ви використовуєте змінні середовища у вашому файлі конфігурації intlayer.config.ts, ви можете вказати потрібне середовище за допомогою аргументу --env:

npx intlayer dictionary push -d my-first-dictionary-key --env production

Ця команда завантажує ваші початкові словники контенту, роблячи їх доступними для асинхронного отримання та редагування через платформу Intlayer.

Редагування словника

Потім ви зможете переглядати та керувати своїм словником у Intlayer CMS.

Live Sync

Live Sync дозволяє вашому застосунку відображати зміни контенту з CMS під час виконання. Немає потреби у перебудові або повторному розгортанні. Коли увімкнено, оновлення передаються на сервер Live Sync, який оновлює словники, які читає ваш застосунок.

Увімкніть Live Sync, оновивши конфігурацію Intlayer:

import type { IntlayerConfig } from "intlayer";

const config: IntlayerConfig = {
  // ... other configuration settings
  editor: {
    /**
     * Увімкнення гарячого перезавантаження конфігурацій локалей при виявленні змін.
     * Наприклад, коли словник додається або оновлюється, застосунок оновлює
     * вміст, що відображається на сторінці.
     *
     * Оскільки гаряче перезавантаження вимагає постійного з'єднання з сервером,
     * воно доступне лише клієнтам плану `enterprise`.
     *
     * За замовчуванням: false
     */
    liveSync: true,
  },
  dictionary: {
    /**
     * Керує способом імпорту словників:
     *
     * - "live": словники завантажуються динамічно за допомогою Live Sync API.
     *   Замінює useIntlayer на useDictionaryDynamic.
     *
     * Примітка: режим live використовує Live Sync API для отримання словників. Якщо виклик API
     * не вдасться, словники імпортуються динамічно.
     * Примітка: режим live використовується лише для словників з віддаленим контентом і прапорцем "live".
     * Інші використовують динамічний режим для кращої продуктивності.
     */
    importMode: "fetch",
  },
};

export default config;

Запустіть Live Sync сервер, щоб обгорнути ваш додаток:

Приклад із окремим (standalone) сервером:

{  "scripts": {    // ... інші скрипти    "live:start": "npx intlayer live",  },}

Ви також можете запустити сервер вашого додатку паралельно, використовуючи аргумент --process.

Приклад із Next.js:

{  "scripts": {    // ... інші скрипти    "build": "next build",    "dev": "next dev",    "start": "npx intlayer live --with 'next start'",  },}

Приклад із Vite:

{  "scripts": {    // ... інші скрипти    "build": "vite build",    "dev": "vite dev",    "start": "npx intlayer live --with 'vite start'",  },}

Live Sync-сервер обгортає ваш додаток і автоматично застосовує оновлений контент у міру його надходження.

Щоб отримувати сповіщення про зміни з CMS, Live Sync-сервер підтримує SSE-з'єднання з бекендом. Коли вміст у CMS змінюється, бекенд пересилає оновлення до Live Sync-сервера, який записує нові словники. Ваш додаток відобразить оновлення при наступній навігації або перезавантаженні браузера, без необхідності перебудови.

Схема потоку (CMS/Backend -> Live Sync Server -> Application Server -> Frontend):

Як це працює:

Робочий процес розробки (локально)

• Під час розробки всі віддалені словники завантажуються при запуску застосунку, тож ви можете швидко тестувати оновлення.
• Щоб протестувати Live Sync локально з Next.js, обгорніть ваш dev-сервер:

{  "scripts": {    // ... інші скрипти    "dev": "npx intlayer live --with 'next dev'",    // "dev": "npx intlayer live --with 'vite dev'", // Для Vite  },}

Увімкніть оптимізацію, щоб Intlayer застосовував трансформації Live import під час розробки:

import type { IntlayerConfig } from "intlayer";

const config: IntlayerConfig = {
  editor: {
    applicationURL: "http://localhost:5173",
    liveSyncURL: "http://localhost:4000",
    liveSync: true,
  },
  dictionary: {
    importMode: "fetch",
  },
  build: {
    optimize: true,
  },
};

export default config;

Ця конфігурація обгортає ваш dev-сервер Live Sync-сервером, завантажує віддалені словники при старті та передає оновлення з CMS через SSE. Оновіть сторінку, щоб побачити зміни.

Примітки та обмеження:

• Додайте origin Live Sync до політики безпеки вашого сайту (CSP). Переконайтеся, що URL Live Sync дозволений у connect-src (і в frame-ancestors, якщо це доречно).
• Live Sync не працює зі статичним виводом. Для Next.js сторінка має бути динамічною, щоб отримувати оновлення під час виконання (наприклад, використовуйте generateStaticParams, generateMetadata, getServerSideProps або getStaticProps відповідно, щоб уникнути повного обмеження лише статикою).
• У CMS кожний словник має прапорець live. Лише словники з live=true завантажуються через API live sync; інші імпортуються динамічно і залишаються незмінними під час виконання.
• Прапорець live оцінюється для кожного словника під час збірки. Якщо віддалений контент не мав live=true під час збірки, потрібно перебудувати проект, щоб увімкнути Live Sync для цього словника.
• Сервер live sync має мати можливість записувати в .intlayer. У контейнерах переконайтеся, що є права запису до /.intlayer.

Налагодження

Якщо у вас виникли проблеми з CMS, перевірте наступне:

• Застосунок запущено.

• Налаштування editor правильно встановлені у вашому конфігураційному файлі Intlayer.

  • Обов'язкові поля:
    • URL застосунку має відповідати тому, що ви вказали в конфігурації редактора (applicationURL).
    • URL CMS

• Переконайтеся, що конфігурацію проєкту було pushed до Intlayer CMS.

• Візуальний редактор використовує iframe для відображення вашого вебсайту. Переконайтеся, що Content Security Policy (CSP) вашого сайту дозволяє URL CMS у frame-ancestors ('https://app.intlayer.org' за замовчуванням). Перевірте консоль редактора на наявність помилок.