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

# Оптимізація розміру бандла та продуктивності i18n

Одна з найпоширеніших проблем традиційних i18n-рішень, що базуються на JSON-файлах — це керування розміром контенту. Якщо розробники не розділяють контент вручну по неймспейсах, користувачі часто в кінцевому підсумку завантажують переклади для всіх сторінок і, можливо, для всіх мов лише для перегляду однієї сторінки.

Наприклад, застосунок з 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` на оптимізований код відповідно до вашої конфігурації.

Це гарантує, що:

- Якщо компонент не імпортується, його вміст не включається до бандла (видалення мертвого коду — Dead Code Elimination).
- Якщо компонент завантажується lazy-loaded, його вміст також завантажується lazy-loaded.

## Налаштування за платформою

### 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,
  },
  dictionary: {},
  build: {
    optimize: true,
    importMode: "static", // або 'dynamic'
    traversePattern: ["**/*.{js,ts,mjs,cjs,jsx,tsx}", "!**/node_modules/**"],
  },
};

export default config;
```

> У більшості випадків рекомендовано залишати опцію `optimize` за замовчуванням.

> Див. документацію з конфігурації для більш детальної інформації: [Конфігурація](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/configuration.md)

### Параметри збірки

Наступні параметри доступні в об'єкті конфігурації `build`:

| Властивість           | Тип                              | Значення за замовчуванням       | Опис                                                                                                                                                                                                              |
| :-------------------- | :------------------------------- | :------------------------------ | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **`optimize`**        | `boolean`                        | `undefined`                     | Керує тим, чи увімкнена оптимізація під час збірки. Якщо `true`, Intlayer замінює виклики словників на оптимізовані інжекти. Якщо `false`, оптимізація вимкнена. Рекомендовано встановлювати `true` у production. |
| **`importMode`**      | `'static' , 'dynamic' , 'fetch'` | `'static'`                      | **Deprecated**: Use `dictionary.importMode` instead. Визначає, як завантажуються словники (див. деталі нижче).                                                                                                    |
| **`traversePattern`** | `string[]`                       | `['**/*.{js,ts,jsx,tsx}', ...]` | Glob-шаблони, що визначають, які файли 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: {
      uk: "Мій заголовок",
      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. Живий режим

Працює аналогічно динамічному режиму, але спочатку намагається отримати словники з Intlayer Live Sync API. Якщо виклик API не вдасться або вміст не позначено для живих оновлень, виконується відкат до динамічного імпорту.

> Див. документацію CMS для детальнішої інформації: [CMS](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/intlayer_CMS.md)

## Підсумок: Статичний vs Динамічний

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