Как работает Intlayer

Таблица содержания

Обзор

Основная идея Intlayer заключается в использовании управления контентом на уровне компонентов. Идея Intlayer состоит в том, чтобы позволить вам объявлять ваш контент в любом месте вашего кода, например, в той же директории, что и ваш компонент.

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

Для этого роль Intlayer заключается в том, чтобы находить все ваши файлы с объявлением контента во всех различных форматах, присутствующих в вашем проекте, а затем генерировать из них словари.

Таким образом, есть два основных этапа:

• Этап сборки
• Этап интерпретации

Этап сборки словарей

Этап сборки может быть выполнен тремя способами:

• с использованием CLI с помощью npx intlayer build
• с использованием расширения vscode
• с использованием плагинов приложения, таких как пакет vite-intlayer, или их эквивалентов для Next.js. При использовании одного из этих плагинов Intlayer автоматически создаст ваши словари при запуске (dev) или сборке (prod) вашего приложения.

1. Объявление файлов контента

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

2. Генерация словарей

   • Словари генерируются из файлов контента. По умолчанию словари Intlayer генерируются в директории .intlayer/dictionaries проекта.
   • Эти словари генерируются в различных форматах, чтобы удовлетворить все потребности и оптимизировать производительность приложения.

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

4. Генерация типов словарей На основе ваших словарей Intlayer будет генерировать типы, чтобы сделать их пригодными для использования в вашем приложении.

• Типы словарей генерируются из файлов декларации контента Intlayer. По умолчанию типы словарей Intlayer генерируются в директории .intlayer/types проекта.

• Расширение модулей Intlayer - это функция 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, управлять множественным числом и многое другое.

Чтобы увидеть все возможности Intlayer, вы можете прочитать документацию по словарям.

Удалённый контент

Intlayer позволяет объявлять контент локально, а затем экспортировать его в CMS, чтобы ваша нетехническая команда могла редактировать его.

Таким образом, вы сможете отправлять и получать контент из CMS в ваше приложение, аналогично тому, как вы работаете с Git для вашего кода.

Для внешних словарей, использующих CMS, Intlayer выполняет базовую операцию fetch для получения удалённых словарей и объединяет их с вашими локальными. Если это настроено в вашем проекте, Intlayer будет автоматически управлять загрузкой контента из CMS при запуске приложения (dev) / сборке (prod).

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

Intlayer также предоставляет визуальный редактор, позволяющий редактировать ваш контент визуально. Этот визуальный редактор доступен в отдельном пакете intlayer-editor.

• Сервер — это простое приложение Express, которое прослушивает запросы от клиента и получает содержимое вашего приложения, такое как dictionaries и конфигурация, чтобы сделать его доступным на стороне клиента.

• С другой стороны, клиент — это приложение React, которое используется для взаимодействия с вашим содержимым через визуальный интерфейс.

• Сервер - это простое приложение на Express, которое прослушивает запросы от клиента и получает контент вашего приложения, такой как dictionaries и конфигурация, чтобы сделать его доступным на стороне клиента.
• С другой стороны, клиент - это приложение на React, которое используется для взаимодействия с вашим контентом через визуальный интерфейс. Когда вы вызываете ваш контент с помощью useIntlayer и редактор включен, строки автоматически оборачиваются в объект Proxy с именем IntlayerNode. Этот узел использует window.postMessage для связи с обернутым iframe, содержащим интерфейс визуального редактора.
  Со стороны редактора, редактор прослушивает эти сообщения и имитирует реальное взаимодействие с вашим контентом, позволяя редактировать текст напрямую в контексте вашего приложения.

Оптимизация сборки приложения

Чтобы оптимизировать размер bundle вашего приложения, Intlayer предоставляет два плагина для оптимизации сборки вашего приложения: плагины @intlayer/babel и @intlayer/swc.

Для оптимизации размера сборки вашего приложения Intlayer предоставляет два плагина для оптимизации сборки: плагины @intlayer/babel и @intlayer/swc. Плагины Babel и SWC работают, анализируя абстрактное синтаксическое дерево (AST) вашего приложения, чтобы заменить вызовы функций Intlayer на оптимизированный код. Этот процесс делает финальный бандл легче в продакшене, гарантируя, что импортируются только действительно используемые словари, оптимизируя разбиение на чанки и уменьшая размер сборки.

В режиме разработки Intlayer использует централизованный статический импорт для словарей, чтобы упростить процесс разработки.

Активировав опцию importMode = "dynamic" в конфигурации, Intlayer будет использовать динамический импорт для загрузки словарей. Эта опция отключена по умолчанию, чтобы избежать асинхронной обработки при рендеринге приложения.

@intlayer/babel доступен по умолчанию в пакете vite-intlayer,

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

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

Пакеты

Intlayer состоит из нескольких пакетов, каждый из которых выполняет определенную роль в процессе перевода. Вот графическое представление структуры этого пакета:

intlayer

Пакет intlayer используется в приложениях для объявления контента в файлах контента.

react-intlayer

Пакет react-intlayer используется для интерпретации словарей Intlayer и их использования в React-приложениях.

next-intlayer

Пакет next-intlayer используется как слой поверх react-intlayer, чтобы сделать словари Intlayer пригодными для использования в приложениях Next.js. Он интегрирует основные функции для работы Intlayer в среде Next.js, такие как промежуточное ПО для перевода, маршрутизация или конфигурация файла next.config.js.

vue-intlayer

Пакет vue-intlayer используется для интерпретации словарей Intlayer и их использования в приложениях Vue.

nuxt-intlayer

Пакет nuxt-intlayer используется как модуль Nuxt для использования словарей Intlayer в приложениях Nuxt. Он интегрирует необходимые функции для работы Intlayer в среде Nuxt, такие как промежуточное ПО для перевода, маршрутизация и конфигурация файла nuxt.config.js.

svelte-intlayer (в разработке)

Пакет svelte-intlayer используется для интерпретации словарей Intlayer и их использования в приложениях Svelte.

solid-intlayer (в разработке)

Пакет solid-intlayer используется для интерпретации словарей Intlayer и их использования в приложениях Solid.js.

preact-intlayer

Пакет preact-intlayer используется для интерпретации словарей Intlayer и их использования в приложениях Preact.

angular-intlayer (в разработке)

Пакет angular-intlayer используется для интерпретации словарей Intlayer и их использования в приложениях Angular.

express-intlayer

Пакет express-intlayer используется для работы с Intlayer на серверной стороне Express.js.

react-native-intlayer

Пакет react-native-intlayer предоставляет инструменты, которые интегрируют плагины для работы Intlayer с Metro bundler.

lynx-intlayer

Пакет lynx-intlayer предоставляет инструменты, которые интегрируют плагины для работы Intlayer с Lynx bundler.

vite-intlayer

Включает плагин Vite для интеграции Intlayer с Vite bundler, а также промежуточное ПО для определения предпочтительной локали пользователя, управления cookies и обработки перенаправления URL.

react-scripts-intlayer

Включает команды и плагины react-scripts-intlayer для интеграции Intlayer с приложением на основе Create React App. Эти плагины основаны на craco и включают дополнительную конфигурацию для сборщика Webpack.

intlayer-editor

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

Клиент содержит элементы пользовательского интерфейса, которые будут использоваться 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, таких как доступные языки, параметры промежуточного программного обеспечения 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/dictionaries-entry & @intlayer/unmerged-dictionaries-entry & @intlayer/dynamic-dictionaries-entry

Пакеты @intlayer/dictionaries-entry, @intlayer/unmerged-dictionaries-entry и @intlayer/dynamic-dictionaries-entry возвращают путь к точке входа словарей Intlayer. Поскольку поиск по файловой системе из браузера невозможен, использование сборщиков вроде Webpack или Rollup для получения пути к словарям также невозможно. Эти пакеты предназначены для использования с псевдонимами, что позволяет оптимизировать сборку с различными сборщиками, такими как 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 предоставляет инструменты, которые оптимизируют сборку словарей для приложений на основе Vite и Webpack.

@intlayer/swc

Пакет @intlayer/swc предоставляет инструменты, которые оптимизируют сборку словарей для приложений Next.js.

@intlayer/api

Пакет @intlayer/api является SDK API для взаимодействия с бэкендом.

@intlayer/design-system

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

@intlayer/backend

Пакет @intlayer/backend экспортирует типы бэкенда и в будущем предложит бэкенд как автономный пакет.

Общайтесь с нашей умной документацией

• Задайте свои вопросы нашей умной документации

Часто задаваемые вопросы