Як працює Intlayer

Зміст

Огляд

Головна ідея Intlayer, застосувати керування контентом на рівні компонентів. Іншими словами, Intlayer дозволяє вам декларувати контент будь-де у вашому codebase, наприклад у тій самій директорії, що й компонент.

.
└── Components
    └── MyComponent
        ├── index.content.ts
        └── index.tsx

Для цього роль Intlayer полягає в тому, щоб знайти всі ваші content declaration files у всіх доступних форматах у проєкті, а потім згенерувати з них dictionaries.

Отже, є два основні етапи:

• Етап побудови
• Етап інтерпретації

Етап побудови словників

Етап побудови можна виконати трьома способами:

• за допомогою CLI з npx intlayer build
• використовуючи розширення VS Code
• за допомогою плагінів застосунку, таких як пакет vite-intlayer, або їхніх еквівалентів для Next.js. Коли ви використовуєте один із цих плагінів, Intlayer автоматично збирає ваші словники під час запуску (dev) або збірки (prod) застосунку.

1. Оголошення файлів контенту

   • Файли контенту можна визначати в різних форматах, таких як TypeScript, ECMAScript, CommonJS або JSON.
   • Файли контенту можуть бути визначені в будь-якому місці проєкту, що дозволяє кращу підтримку та масштабованість. Важливо дотримуватися конвенцій щодо розширень файлів контенту. Це розширення за замовчуванням, *.content.{js|cjs|mjs|ts|tsx|json}, але його можна змінити у файлі конфігурації.

2. Генерація dictionaries

   • Словники генеруються з файлів контенту. За замовчуванням словники Intlayer створюються в директорії .intlayer/dictionaries проєкту.
   • Ці словники генеруються в різних форматах, щоб задовольнити всі потреби та оптимізувати продуктивність застосунку.

3. Генерація типів словників

На основі ваших dictionaries Intlayer згенерує типи, щоб зробити їх доступними у вашому застосунку.

• Типи словників генеруються з файлів оголошень вмісту Intlayer (content declaration files). За замовчуванням типи словників Intlayer генеруються в директорії .intlayer/types проєкту.

• Intlayer module augmentation, це можливість TypeScript, яка дозволяє визначати додаткові типи для Intlayer. Це спрощує досвід розробки, підказуючи доступні або обов'язкові аргументи. Серед згенерованих типів, типи словників Intlayer або навіть типи конфігурації мов додаються до файлу types/intlayer.d.ts і використовуються іншими пакетами. Для цього необхідно, щоб файл tsconfig.json був налаштований на включення директорії types проекту.

Крок інтерпретації словників

За допомогою Intlayer ви будете отримувати доступ до вашого контенту в застосунку, використовуючи хук useIntlayer.

const MyComponent = () => {
  const content = useIntlayer("my-component");
  return <div>{content.title}</div>;
};

Цей хук керуватиме визначенням локалі за вас і повертатиме контент для поточної локалі. Використовуючи цей хук, ви також зможете інтерпретувати markdown, керувати pluralization та багато іншого.

Щоб побачити всі можливості Intlayer, ви можете прочитати документацію словників.

Віддалений контент

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

Таким чином ви зможете відправляти (push) та отримувати (pull) контент між CMS та вашим додатком, подібно до того, як ви працюєте з Git для вашого коду.

Для зовнішніх словників, які використовують CMS, Intlayer виконує базову операцію fetch для отримання віддалених словників і об'єднує їх з локальними. Якщо це налаштовано в проекті, Intlayer автоматично керуватиме отриманням контенту з CMS під час запуску додатка (dev) або під час збірки (prod).

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

Intlayer також надає візуальний редактор, щоб дозволити редагувати ваш контент у візуальний спосіб. Цей візуальний редактор доступний у зовнішньому пакеті intlayer-editor.

• Сервер, це проста Express-аплікація, яка прослуховує запити від клієнта та отримує вміст вашого застосунку, такий як dictionaries, і конфігурацію, щоб зробити їх доступними на стороні клієнта.
• З іншого боку, клієнт, це React-аплікація, яка використовується для взаємодії з вашим контентом за допомогою візуального інтерфейсу.

Коли ви викликаєте свій контент за допомогою useIntlayer і редактор увімкнений, він автоматично обгортає ваші рядки об'єктом Proxy з ім'ям IntlayerNode. Цей вузол використовує window.postMessage для зв'язку з вкладеним iframe, що містить інтерфейс візуального редактора. На стороні редактора він прослуховує ці повідомлення та імітує реальну взаємодію з вашим контентом, дозволяючи редагувати текст безпосередньо в контексті вашого додатку.

Оптимізація збірки додатку

Щоб оптимізувати розмір бандлу вашого додатку, Intlayer надає два плагіни для оптимізації збірки: @intlayer/babel та @intlayer/swc.

Плагіни Babel та SWC працюють шляхом аналізу абстрактного синтаксичного дерева (AST) вашого додатка, щоб замінити виклики функцій Intlayer на оптимізований код. Цей процес робить ваш фінальний bundle легшим у production, забезпечуючи імпорт лише тих словників, які фактично використовуються, оптимізуючи chunking та зменшуючи розмір bundle.

У режимі розробки Intlayer використовує централізований статичний імпорт словників, щоб спростити досвід розробки.

Активувавши опцію importMode = "dynamic" у configuration, Intlayer використовуватиме динамічний імпорт для завантаження словників. Ця опція вимкнена за замовчуванням, щоб уникнути асинхронної обробки під час рендерингу додатка.

@intlayer/babel доступний за замовчуванням у пакеті vite-intlayer,

@intlayer/babel доступний за замовчуванням у пакеті vite-intlayer,

@intlayer/swc не встановлений за замовчуванням у пакеті next-intlayer, оскільки плагіни SWC все ще експериментальні в Next.js.

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

Пакети

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

intlayer

Пакет intlayer використовується в застосунках для оголошення контенту у файлах контенту.

Фронтенд-фреймворки

Бекенд-фреймворки

vite-intlayer

Містить плагін Vite для інтеграції Intlayer з бандлером Vite, а також middleware для визначення пріоритетної локалі користувача, керування cookie та обробки перенаправлень URL.

react-scripts-intlayer

Містить команди та плагіни react-scripts-intlayer для інтеграції Intlayer з додатком на базі Create React App. Ці плагіни засновані на craco і включають додаткову конфігурацію для бандлера Webpack.

eslint-plugin-intlayer

Пакет eslint-plugin-intlayer надає правила ESLint та oxlint для виявлення неперекладених рядків, перевірки визначень словників та дотримання найкращих практик i18n.

intlayer-editor

Пакет intlayer-editor використовується для забезпечення можливості використання візуального редактора. Цей пакет є опціональним, його можна встановити в застосунках, і він буде використовуватися пакетом react-intlayer. Він складається з двох частин: сервера та клієнта.

Клієнт містить UI-елементи, які будуть використовуватися react-intlayer.

Сервер, на базі Express, використовується для отримання запитів від візуального редактора та керування або модифікації файлів контенту.

intlayer-cli

Пакет intlayer-cli можна використовувати для генерації словників за допомогою команди npx intlayer dictionaries build. Якщо intlayer вже встановлено, CLI встановлюється автоматично і цей пакет не є необхідним.

@intlayer/core

Пакет @intlayer/core є основним пакетом Intlayer. Він містить функції перекладу та керування словниками. @intlayer/core є багатоплатформним і використовується іншими пакетами для виконання інтерпретації словників.

@intlayer/config

Пакет @intlayer/config використовується для налаштування параметрів Intlayer, таких як доступні мови, параметри middleware Next.js або налаштування інтегрованого редактора.

@intlayer/webpack

Пакет @intlayer/webpack використовується для надання конфігурації Webpack, щоб застосунок на основі Webpack працював з Intlayer. Пакет також надає плагін, який можна додати до наявного застосунку Webpack.

@intlayer/cli

Пакет @intlayer/cli є NPM-пакетом, який використовується для оголошення скриптів, пов’язаних із командними інтерфейсами Intlayer. Він забезпечує узгодженість усіх CLI-команд Intlayer. Цей пакет, зокрема, використовується пакетами intlayer-cli та intlayer.

@intlayer/mcp

Пакет @intlayer/mcp забезпечує сервер MCP (Model Context Protocol), який надає підтримку IDE на базі ШІ, адаптовану до екосистеми Intlayer. Він автоматично завантажує документацію та інтегрується з Intlayer CLI.

@intlayer/lsp

Пакет @intlayer/lsp надає сервер Language Server Protocol (LSP), адаптований для Intlayer. Він забезпечує функції IDE, такі як перехід до визначення, пошук посилань, попередній перегляд при наведенні, автодоповнення ключів словника та діагностичні попередження.

@intlayer/ai

Пакет @intlayer/ai надає можливості SDK для програм Intlayer, уможливлюючи автоматизований переклад і генерацію контенту за допомогою ШІ.

@intlayer/analytics

Пакет @intlayer/analytics надає інструменти для збору метрик показів контенту, аналітики на рівні сторінок/локалей та вузлів, а також забезпечує A/B-тестування контенту.

@intlayer/dictionaries-entry

Пакет @intlayer/dictionaries-entry повертає шлях entry словників Intlayer: об'єднані словники з кореня, а також необ'єднані, віддалені, динамічні та fetch-словники з підшляхів /unmerged, /remote, /dynamic та /fetch. Оскільки з браузера неможливо виконувати пошук по файловій системі, використання bundler-ів, таких як Webpack або Rollup, для отримання шляху entry словників неможливе. Пакет та його підшляхи розроблені для того, щоб їх можна було alias-ити, що дозволяє оптимізувати bundling для різних збирачів, таких як Vite, Webpack та Turbopack.

@intlayer/engine

Пакет @intlayer/engine використовується для моніторингу файлів контенту та перегенерації зміненого словника при кожній модифікації.

@intlayer/editor

Пакет @intlayer/editor надає утиліти, пов'язані з редактором словників. Зокрема, він містить API для з'єднання застосунку з редактором Intlayer, а також утиліти для роботи зі словниками. Цей пакет є кросплатформним.

@intlayer/editor-react

Пакет @intlayer/editor-react надає стани, контексти, хуки та компоненти для з'єднання застосунку React з редактором Intlayer.

@intlayer/babel

Пакет @intlayer/babel надає інструменти, що оптимізують bundling словників для застосунків на основі Vite та Webpack.

@intlayer/swc

Пакет @intlayer/swc надає інструменти, що оптимізують bundling словників для застосунків Next.js.

@intlayer/api

Пакет @intlayer/api є API SDK для взаємодії з бекендом.

@intlayer/design-system

Пакет @intlayer/design-system використовується для обміну елементами дизайну між CMS і візуальним редактором.

@intlayer/backend

Пакет @intlayer/backend експортує типи бекенду та згодом надасть бекенд як окремий пакет.

Чат з нашою розумною документацією

Часто задавані запитання