Оптимизация размера и производительности i18n-бандла

Одна из самых распространённых проблем традиционных решений i18n, основанных на JSON-файлах, — это управление размером контента. Если разработчики не разделяют контент вручную по namespace, пользователи часто загружают переводы для каждой страницы и, возможно, для каждого языка, чтобы просмотреть всего одну страницу.

Например, приложение с 10 страницами, переведёнными на 10 языков, может привести к тому, что пользователь загрузит контент 100 страниц, хотя ему нужна только одна (текущая страница на текущем языке). Это приводит к излишнему расходу трафика и замедлению времени загрузки.

Для обнаружения этой проблемы можно использовать анализаторы бандлов, такие как rollup-plugin-visualizer (vite), @next/bundle-analyzer (next.js) или webpack-bundle-analyzer (React CRA / Angular / и др.).

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

Содержание

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

Intlayer использует подход на уровне компонентов. В отличие от глобальных JSON-файлов, ваш контент определяется рядом с компонентами или внутри них. Во время процесса сборки Intlayer:

1. Анализирует ваш код, чтобы найти вызовы useIntlayer.
2. Формирует соответствующий словарь с контентом.
3. Заменяет вызов useIntlayer на оптимизированный код в соответствии с вашей конфигурацией.

Это гарантирует, что:

• Если компонент не импортируется, его контент не включается в бандл (удаление неиспользуемого кода).
• Если компонент загружается лениво, его контент также загружается лениво.

Настройка по платформам

Next.js

Next.js требует плагин @intlayer/swc для обработки трансформации, так как Next.js использует SWC для сборки.

Этот плагин установлен по умолчанию, поскольку плагины SWC для Next.js всё ещё находятся в экспериментальной стадии. В будущем это может измениться.

Vite

Vite использует плагин @intlayer/babel, который включён как зависимость в vite-intlayer. Оптимизация включена по умолчанию.

Webpack

Чтобы включить оптимизацию бандла с Intlayer в Webpack, необходимо установить и настроить соответствующий плагин Babel (@intlayer/babel) или SWC (@intlayer/swc).

Expo / Lynx

Оптимизация бандла пока недоступна для этой платформы. Поддержка будет добавлена в будущих релизах.

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

Вы можете управлять тем, как Intlayer оптимизирует ваш бандл, через свойство build в вашем файле intlayer.config.ts.

import { Locales, type IntlayerConfig } from "intlayer";const config: IntlayerConfig = {  internationalization: {    locales: [Locales.ENGLISH, Locales.FRENCH], // локали    defaultLocale: Locales.ENGLISH, // локаль по умолчанию  },  build: {    optimize: true, // включить оптимизацию    importMode: "static", // или 'dynamic' - режим импорта    traversePattern: ["**/*.{js,ts,mjs,cjs,jsx,tsx}", "!**/node_modules/**"], // шаблоны обхода файлов  },};export default config;

Рекомендуется сохранять значение по умолчанию для optimize в большинстве случаев.

Подробнее о конфигурации смотрите в документации: Configuration

Опции сборки

Следующие параметры доступны в объекте конфигурации build:

Режимы импорта

Настройка importMode определяет, как содержимое словаря внедряется в ваш компонент.

1. Статический режим (default)

В статическом режиме Intlayer заменяет useIntlayer на useDictionary и внедряет словарь непосредственно в JavaScript-бандл.

• Преимущества: Мгновенный рендеринг (синхронный), отсутствие дополнительных сетевых запросов во время гидратации.
• Недостатки: Бандл включает переводы для всех доступных языков для данного компонента.
• Лучше всего подходит для: Одностраничных приложений (SPA).

Пример преобразованного кода:

// Ваш кодconst content = useIntlayer("my-key");// Оптимизированный код (Статический)const content = useDictionary({  key: "my-key",  content: {    nodeType: "translation",    translation: {      en: "My title",      fr: "Mon titre",    },  },});

2. Динамический режим

В динамическом режиме Intlayer заменяет useIntlayer на useDictionaryAsync. Это использует import() (механизм, похожий на Suspense) для ленивой загрузки JSON-файла конкретно для текущей локали.

• Преимущества: Tree shaking на уровне локали. Пользователь, просматривающий английскую версию, загрузит только английский словарь. Французский словарь никогда не загружается.
• Недостатки: Во время гидратации для каждого компонента выполняется сетевой запрос (загрузка ассета).
• Лучше всего подходит для: Больших текстовых блоков, статей или приложений, поддерживающих множество языков, где критичен размер бандла.

Пример преобразованного кода:

// Ваш кодconst content = useIntlayer("my-key");// Оптимизированный код (Динамический)const content = useDictionaryAsync({  en: () =>    import(".intlayer/dynamic_dictionary/my-key/en.json").then(      (mod) => mod.default    ),  fr: () =>    import(".intlayer/dynamic_dictionary/my-key/fr.json").then(      (mod) => mod.default    ),});

При использовании importMode: 'dynamic', если на одной странице 100 компонентов используют useIntlayer, браузер попытается выполнить 100 отдельных запросов. Чтобы избежать такой "водопадной" загрузки, группируйте контент в меньшее количество файлов .content (например, один словарь на секцию страницы), а не по одному на каждый атомарный компонент.

В настоящее время importMode: 'dynamic' не полностью поддерживается для Vue и Svelte. Рекомендуется использовать importMode: 'static' для этих фреймворков до выхода дальнейших обновлений.

3. Live Mode

Ведет себя аналогично динамическому режиму, но сначала пытается получить словари через Intlayer Live Sync API. Если вызов API не удался или контент не помечен для живых обновлений, происходит возврат к динамическому импорту.

Подробнее смотрите в документации CMS: CMS

Сводка: Статический vs Динамический