---
createdAt: 2025-11-25
updatedAt: 2025-11-25
title: Оптимизация размера и производительности i18n-бандла
description: Сократите размер бандла приложения, оптимизируя контент интернационализации (i18n). Узнайте, как использовать tree shaking и ленивую загрузку словарей с Intlayer.
keywords:
  - Оптимизация бандла
  - Автоматизация контента
  - Динамический контент
  - Intlayer
  - Next.js
  - JavaScript
  - React
slugs:
  - doc
  - concept
  - bundle-optimization
history:
  - version: 6.0.0
    date: 2025-11-25
    changes: Инициализация истории
---

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

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

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

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

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

## Содержание

<TOC />

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

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

```typescript fileName="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](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ru/configuration.md)

### Опции сборки

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

| Свойство              | Тип                             | Значение по умолчанию           | Описание                                                                                                                                                                                               |
| :-------------------- | :------------------------------ | :------------------------------ | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **`optimize`**        | `boolean`                       | `undefined`                     | Управляет включением оптимизации сборки. Если `true`, Intlayer заменяет вызовы словарей на оптимизированные инъекции. Если `false`, оптимизация отключена. В идеале устанавливать `true` в продакшене. |
| **`importMode`**      | `'static' , 'dynamic' , 'live'` | `'static'`                      | Определяет способ загрузки словарей (подробнее см. ниже).                                                                                                                                              |
| **`traversePattern`** | `string[]`                      | `['**/*.{js,ts,jsx,tsx}', ...]` | Глобальные шаблоны, определяющие, какие файлы Intlayer должен сканировать для оптимизации. Используйте это, чтобы исключить несвязанные файлы и ускорить сборку.                                       |
| **`outputFormat`**    | `'esm', 'cjs'`                  | `'esm', 'cjs'`                  | Управляет форматом вывода собранных словарей.                                                                                                                                                          |

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

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

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

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

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

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

```tsx
// Ваш код
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 на уровне локали.** Пользователь, просматривающий английскую версию, загрузит _только_ английский словарь. Французский словарь никогда не загружается.
- **Недостатки:** Во время гидратации для каждого компонента выполняется сетевой запрос (загрузка ассета).
- **Лучше всего подходит для:** Больших текстовых блоков, статей или приложений, поддерживающих множество языков, где критичен размер бандла.

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

```tsx
// Ваш код
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](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ru/intlayer_CMS.md)

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

| Особенность            | Статический режим                          | Динамический режим                                  |
| :--------------------- | :----------------------------------------- | :-------------------------------------------------- |
| **Размер JS-бандла**   | Больше (включает все языки для компонента) | Самый маленький (только код, без контента)          |
| **Начальная загрузка** | Мгновенно (контент включен в бандл)        | Небольшая задержка (загрузка JSON)                  |
| **Сетевые запросы**    | 0 дополнительных запросов                  | 1 запрос на каждый словарь                          |
| **Tree Shaking**       | На уровне компонента                       | На уровне компонента + локали                       |
| **Лучшее применение**  | UI-компоненты, небольшие приложения        | Страницы с большим количеством текста, много языков |
