@intlayer/docs 8.6.10 → 8.7.0-canary.1

package/docs/ru/bundle_optimization.md

@@ -0,0 +1,454 @@
+---
+createdAt: 2025-11-25
+updatedAt: 2026-04-08
+title: Оптимизация размера бандла i18n и производительности
+description: Уменьшите размер бандла вашего приложения, оптимизируя контент интернационализации (i18n). Узнайте, как использовать tree shaking и lazy loading для словарей с помощью Intlayer.
+keywords:
+  - Оптимизация бандла
+  - Автоматизация контента
+  - Динамический контент
+  - Intlayer
+  - Next.js
+  - JavaScript
+  - React
+slugs:
+  - doc
+  - concept
+  - bundle-optimization
+history:
+  - version: 8.7.0
+    date: 2026-04-08
+    changes: "Добавлены опции `minify` и `purge` в конфигурацию сборки"
+---
+
+# Оптимизация размера бандла i18n и производительности
+
+Одной из наиболее распространенных проблем традиционных i18n-решений, полагающихся на JSON-файлы, является управление размером контента. Если разработчики вручную не разделяют контент на пространства имен (namespaces), пользователи часто скачивают переводы для каждой страницы и, возможно, для каждого языка только для того, чтобы просмотреть одну страницу.
+
+Например, приложение с 10 страницами, переведенными на 10 языков, может привести к тому, что пользователь скачает контент 100 страниц, хотя ему нужна только **одна** (текущая страница на текущем языке). Это ведет к напрасной трате трафика и замедлению времени загрузки.
+
+**Intlayer решает эту проблему с помощью оптимизации на этапе сборки.** Он анализирует ваш код, чтобы определить, какие словари действительно используются в каждом компоненте, и внедряет только необходимый контент в ваш бандл.
+
+## Содержание
+
+<TOC />
+
+## Сканирование бандла
+
+Анализ бандла — это первый шаг к выявлению "тяжелых" JSON-файлов и возможностей разделения кода. Эти инструменты генерируют визуальную древовидную карту (treemap) скомпилированного кода вашего приложения, позволяя вам точно увидеть, какие библиотеки занимают больше всего места.
+
+<Tabs>
+ <Tab value="vite">
+
+### Vite / Rollup
+
+Vite использует Rollup под капотом. Плагин `rollup-plugin-visualizer` генерирует интерактивный HTML-файл, показывающий размер каждого модуля в вашем графе.
+
+```bash
+npm install -D rollup-plugin-visualizer
+```
+
+```typescript fileName="vite.config.ts"
+import { defineConfig } from "vite";
+import { visualizer } from "rollup-plugin-visualizer";
+
+export default defineConfig({
+  plugins: [
+    visualizer({
+      open: true, // Автоматически открыть отчет в браузере
+      filename: "stats.html",
+      gzipSize: true,
+      brotliSize: true,
+    }),
+  ],
+});
+```
+
+ </Tab>
+ <Tab value="nextjs (turbopack)">
+
+### Next.js (Turbopack)
+
+Для проектов, использующих App Router и Turbopack, Next.js предоставляет встроенный экспериментальный анализатор, не требующий дополнительных зависимостей.
+
+```bash packageManager='npm'
+npx next experimental-analyze
+```
+
+```bash packageManager='yarn'
+yarn next experimental-analyze
+```
+
+```bash packageManager='pnpm'
+pnpm next experimental-analyze
+```
+
+```bash packageManager='bun'
+bun next experimental-analyze
+```
+
+ </Tab>
+ <Tab value="nextjs (Webpack)">
+
+### Next.js (Webpack)
+
+Если вы используете стандартный сборщик Webpack в Next.js, используйте официальный анализатор бандлов. Запустите его, установив переменную окружения во время сборки.
+
+```bash packageManager='npm'
+npm install -D @next/bundle-analyzer
+```
+
+```bash packageManager='yarn'
+yarn add -D @next/bundle-analyzer
+```
+
+```bash packageManager='pnpm'
+pnpm add -D @next/bundle-analyzer
+```
+
+```bash packageManager='bun'
+bun add -d @next/bundle-analyzer
+```
+
+```javascript fileName="next.config.js"
+const withBundleAnalyzer = require("@next/bundle-analyzer")({
+  enabled: process.env.ANALYZE === "true",
+});
+
+module.exports = withBundleAnalyzer({
+  // Ваша конфигурация Next.js
+});
+```
+
+**Использование:**
+
+```bash
+ANALYZE=true npm run build
+```
+
+ </Tab>
+ <Tab value="Webpack (CRA / Angular / etc)">
+
+### Стандартный Webpack
+
+Для Create React App (ejected), Angular или кастомных настроек Webpack используйте отраслевой стандарт `webpack-bundle-analyzer`.
+
+```bash packageManager='npm'
+npm install -D webpack-bundle-analyzer
+```
+
+```bash packageManager='yarn'
+yarn add -D webpack-bundle-analyzer
+```
+
+```bash packageManager='pnpm'
+pnpm add -D webpack-bundle-analyzer
+```
+
+```bash packageManager='bun'
+bun add -d webpack-bundle-analyzer
+```
+
+```typescript fileName="webpack.config.ts
+import { BundleAnalyzerPlugin } from "webpack-bundle-analyzer";
+
+export default {
+  plugins: [
+    new BundleAnalyzerPlugin({
+      analyzerMode: "static",
+      reportFilename: "bundle-analyzer.html",
+      openAnalyzer: false,
+    }),
+  ],
+};
+```
+
+ </Tab>
+</Tabs>
+
+## Как это работает
+
+Intlayer использует **подход на уровне компонентов**. В отличие от глобальных JSON-файлов, ваш контент определяется рядом с вашими компонентами или внутри них. В процессе сборки Intlayer:
+
+1.  **Анализирует** ваш код на наличие вызовов `useIntlayer`.
+2.  **Собирает** соответствующий контент словаря.
+3.  **Заменяет** вызов `useIntlayer` оптимизированным кодом на основе вашей конфигурации.
+
+Это гарантирует, что:
+
+- Если компонент не импортирован, его контент не включается в бандл (удаление мертвого кода).
+- Если компонент загружается лениво (lazy-loading), его контент также загружается лениво.
+
+## Настройка по платформам
+
+<Tabs>
+ <Tab value="nextjs">
+
+### Next.js
+
+Для трансформации Next.js требуется плагин `@intlayer/swc`, так как Next.js использует SWC для сборки.
+
+> Этот плагин не устанавливается по умолчанию, так как плагины SWC для Next.js все еще находятся в стадии эксперимента. Это может измениться в будущем.
+
+```bash packageManager="npm"
+npm install -D @intlayer/swc
+```
+
+```bash packageManager="yarn"
+yarn add -D @intlayer/swc
+```
+
+```bash packageManager="pnpm"
+pnpm add -D @intlayer/swc
+```
+
+```bash packageManager="bun"
+bun add -d @intlayer/swc
+```
+
+После установки Intlayer автоматически обнаружит и будет использовать плагин.
+
+ </Tab>
+ <Tab value="vite">
+
+### Vite
+
+Vite использует плагин `@intlayer/babel`, который включен как зависимость `vite-intlayer`. Оптимизация включена по умолчанию. Ничего больше делать не нужно.
+
+ </Tab>
+ <Tab value="webpack">
+
+### Webpack
+
+Чтобы включить оптимизацию бандла с помощью Intlayer в Webpack, вам необходимо установить и настроить соответствующий плагин Babel (`@intlayer/babel`) или SWC (`@intlayer/swc`).
+
+```bash packageManager="npm"
+npm install -D @intlayer/babel
+```
+
+```bash packageManager="yarn"
+yarn add -D @intlayer/babel
+```
+
+```bash packageManager="pnpm"
+pnpm add -D @intlayer/babel
+```
+
+```bash packageManager="bun"
+bun add -d @intlayer/babel
+```
+
+```typescript fileName="babel.config.js"
+const {
+  getOptimizePluginOptions,
+  intlayerOptimizeBabelPlugin,
+} = require("@intlayer/babel");
+
+module.exports = {
+  plugins: [[intlayerOptimizeBabelPlugin, getOptimizePluginOptions()]],
+};
+```
+
+ </Tab>
+</Tabs>
+
+## Конфигурация
+
+Вы можете управлять тем, как 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: {
+    importMode: "dynamic",
+  },
+  build: {
+    /**
+     * Минифицировать словари для уменьшения размера бандла.
+     */
+     minify: true;
+
+    /**
+     * Удалять неиспользуемые ключи в словарях (purge)
+     */
+     purge: true;
+
+    /**
+     * Указывает, должна ли сборка проверять типы TypeScript
+     */
+    checkTypes: false;
+  },
+};
+
+export default config;
+```
+
+> В подавляющем большинстве случаев рекомендуется оставлять значение по умолчанию для параметра `optimize`.
+
+> Подробности см. в документации по конфигурации: [Конфигурация](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ru/configuration.md)
+
+### Опции сборки
+
+В объекте конфигурации `build` доступны следующие опции:
+
+| Свойство       | Тип       | По умолчанию | Описание                                                                                                                                                                                           |
+| :------------- | :-------- | :----------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **`optimize`** | `boolean` | `undefined`  | Управляет включением оптимизации сборки. Если `true`, Intlayer заменяет вызовы словаря оптимизированными вставками. Если `false`, оптимизация отключена. В идеале в продакшене должно быть `true`. |
+| **`minify`**   | `boolean` | `false`      | Минифицировать ли словари для уменьшения размера бандла.                                                                                                                                           |
+| **`purge`**    | `boolean` | `false`      | Удалять ли неиспользуемые ключи в словарях.                                                                                                                                                        |
+
+### Минификация
+
+Минификация словарей удаляет ненужные пробелы, комментарии и уменьшает размер содержимого JSON. Это особенно полезно для больших словарей.
+
+```typescript fileName="intlayer.config.ts"
+import type { IntlayerConfig } from "intlayer";
+
+const config: IntlayerConfig = {
+  build: {
+    minify: true,
+  },
+};
+
+export default config;
+```
+
+> Примечание: Минификация игнорируется, если `optimize` отключен или если включен Визуальный редактор (так как редактору требуется полный контент для возможности редактирования).
+
+### Очистка (Purging)
+
+Очистка гарантирует, что в финальный бандл словарей будут включены только те ключи, которые действительно используются в вашем коде. Это может значительно уменьшить размер вашего бандла, если у вас есть большие словари со множеством ключей, которые используются не во всех частях вашего приложения.
+
+```typescript fileName="intlayer.config.ts"
+import type { IntlayerConfig } from "intlayer";
+
+const config: IntlayerConfig = {
+  build: {
+    purge: true,
+  },
+};
+
+export default config;
+```
+
+> Примечание: Очистка игнорируется, если параметр `optimize` отключен.
+
+### Режим импорта (Import Mode)
+
+Для больших приложений, включающих множество страниц и локалей, ваши JSON-файлы могут составлять значительную часть размера бандла. Intlayer позволяет вам контролировать способ загрузки словарей.
+
+Режим импорта может быть определен по умолчанию глобально в вашем файле `intlayer.config.ts`.
+
+```typescript fileName="intlayer.config.ts"
+import type { IntlayerConfig } from "intlayer";
+
+const config: IntlayerConfig = {
+  build: {
+    minify: true,
+  },
+};
+
+export default config;
+```
+
+А также для каждого словаря в ваших файлах `.content.{{ts|tsx|js|jsx|mjs|cjs|json|jsonc|json5}}`.
+
+```ts
+import { type Dictionary, t } from "intlayer";
+
+const appContent: Dictionary = {
+  key: "app",
+  importMode: "dynamic", // Переопределить режим импорта по умолчанию
+  content: {
+    // ...
+  },
+};
+
+export default appContent;
+```
+
+| Свойство         | Тип                                | По умолчанию | Описание                                                                                                                |
+| :--------------- | :--------------------------------- | :----------- | :---------------------------------------------------------------------------------------------------------------------- |
+| **`importMode`** | `'static'`, `'dynamic'`, `'fetch'` | `'static'`   | **Устарело**: Используйте `dictionary.importMode` вместо этого. Определяет, как загружаются словари (подробности ниже). |
+
+Настройка `importMode` определяет, как содержимое словаря внедряется в ваш компонент.
+Вы можете определить его глобально в файле `intlayer.config.ts` в объекте `dictionary` или переопределить для конкретного словаря в его файле `.content.ts`.
+
+### 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` (например, один словарь на раздел страницы), а не по одному на каждый мелкий компонент.
+
+### 3. Режим Fetch
+
+Ведет себя аналогично динамическому режиму, но сначала пытается получить словари из API Intlayer Live Sync. Если вызов API завершается неудачей или контент не помечен для живых обновлений, он переключается на динамический импорт.
+
+> Подробности см. в документации CMS: [CMS](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ru/intlayer_CMS.md)
+
+> В режиме fetch нельзя использовать очистку (purge) и минификацию.
+
+## Резюме: Статический vs Динамический
+
+| Функция                          | Статический режим                          | Динамический режим                                  |
+| :------------------------------- | :----------------------------------------- | :-------------------------------------------------- |
+| **Размер JS бандла**             | Больше (включает все языки для компонента) | Меньше всего (только код, контента нет)             |
+| **Начальная загрузка**           | Мгновенно (контент уже в бандле)           | Небольшая задержка (загрузка JSON)                  |
+| **Сетевые запросы**              | 0 дополнительных запросов                  | 1 запрос на каждый словарь                          |
+| **Tree Shaking**                 | На уровне компонентов                      | На уровне компонентов + на уровне локалей           |
+| **Лучший вариант использования** | UI-компоненты, небольшие приложения        | Страницы с большим количеством текста, много языков |

package/docs/ru/intlayer_with_next-i18next.md

@@ -257,7 +257,7 @@ export default function LocaleLayout({
   params: { locale: string };
 }) {
   const locale: Locale = (locales as readonly string[]).includes(params.locale)
-    ? (params.locale as any)
+    ? params.locale
     : defaultLocale;
 
   const dir = isRtl(locale) ? "rtl" : "ltr";

package/docs/ru/intlayer_with_next-intl.md

@@ -103,7 +103,7 @@ async function loadMessages(locale: string) {
 }
 
 export default getRequestConfig(async ({ locale }) => {
-  if (!locales.includes(locale as any)) notFound();
+  if (!locales.includes(locale)) notFound();
 
   return {
     messages: await loadMessages(locale),

package/docs/ru/intlayer_with_tanstack+solid.md

@@ -194,9 +194,7 @@ const RootComponent: ParentComponent = (props) => {
       </head>
       <body>
         <IntlayerProvider locale={locale}>
-          <Suspense>
-            {props.children}
-          </Suspense>
+          <Suspense>{props.children}</Suspense>
         </IntlayerProvider>
         <Scripts />
       </body>
@@ -506,12 +504,33 @@ export const Route = createFileRoute("/{-$locale}/")({
   component: RouteComponent,
   head: ({ params }) => {
     const { locale } = params;
-    const metaContent = getIntlayer("page-metadata", locale);
+    const path = "/"; // The path for this route
+
+    const metaContent = getIntlayer("app", locale);
 
     return {
+      links: [
+        // Canonical link: Points to the current localized page
+        { rel: "canonical", href: getLocalizedUrl(path, locale) },
+
+        // Hreflang: Tell Google about all localized versions
+        ...localeMap(({ locale: mapLocale }) => ({
+          rel: "alternate",
+          hrefLang: mapLocale,
+          href: getLocalizedUrl(path, mapLocale),
+        })),
+
+        // x-default: For users in unmatched languages
+        // Define the default fallback locale (usually your primary language)
+        {
+          rel: "alternate",
+          hrefLang: "x-default",
+          href: getLocalizedUrl(path, defaultLocale),
+        },
+      ],
       meta: [
         { title: metaContent.title },
-        { content: metaContent.description, name: "description" },
+        { name: "description", content: metaContent.meta.description },
       ],
     };
   },

package/docs/ru/intlayer_with_tanstack.md

@@ -225,9 +225,7 @@ function RootDocument({ children }: { children: ReactNode }) {
         <HeadContent />
       </head>
       <body>
-        <IntlayerProvider locale={locale}>
-          {children}
-        </IntlayerProvider>
+        <IntlayerProvider locale={locale}>{children}</IntlayerProvider>
         <Scripts />
       </body>
     </html>
@@ -326,30 +324,20 @@ import { getPrefix } from "intlayer";
 
 export const LOCALE_ROUTE = "{-$locale}" as const;
 
-// Основная утилита
-export type RemoveLocaleParam<T> = T extends string
-  ? RemoveLocaleFromString<T>
-  : T;
+export type To = StripLocalePrefix<LinkComponentProps["to"]>;
 
-export type To = RemoveLocaleParam<LinkComponentProps["to"]>;
-
-type CollapseDoubleSlashes<S extends string> =
-  S extends `${infer H}//${infer T}` ? CollapseDoubleSlashes<`${H}/${T}`> : S;
+export type StripLocalePrefix<T extends string | undefined> = T extends
+  | `/${typeof LOCALE_ROUTE}/`
+  | `/${typeof LOCALE_ROUTE}`
+  ? "/"
+  : T extends `/${typeof LOCALE_ROUTE}/${infer Rest}`
+    ? `/${Rest}`
+    : T;
 
 type LocalizedLinkProps = {
   to?: To;
 } & Omit<LinkComponentProps, "to">;
 
-// Вспомогательные типы
-type RemoveAll<
-  S extends string,
-  Sub extends string,
-> = S extends `${infer H}${Sub}${infer T}` ? RemoveAll<`${H}${T}`, Sub> : S;
-
-type RemoveLocaleFromString<S extends string> = CollapseDoubleSlashes<
-  RemoveAll<S, typeof LOCALE_ROUTE>
->;
-
 export const LocalizedLink: FC<LocalizedLinkProps> = (props) => {
   const { locale } = useLocale();
   const { localePrefix } = getPrefix(locale);
@@ -378,26 +366,26 @@ export const LocalizedLink: FC<LocalizedLinkProps> = (props) => {
 import { useNavigate } from "@tanstack/react-router";
 import { getPrefix } from "intlayer";
 import { useLocale } from "react-intlayer";
-import { LOCALE_ROUTE } from "@/components/localized-link";
+import type { StripLocalePrefix } from "@/components/localized-link";
 import type { FileRouteTypes } from "@/routeTree.gen";
 
-type StripLocalePrefix<T extends string> = T extends
-  | `/${typeof LOCALE_ROUTE}`
-  | `/${typeof LOCALE_ROUTE}/`
-  ? "/"
-  : T extends `/${typeof LOCALE_ROUTE}/${infer Rest}`
-    ? `/${Rest}`
-    : never;
+type NavigateFn = ReturnType<typeof useNavigate>;
+type BaseNavigateOptions = Parameters<NavigateFn>[0];
 
 type LocalizedTo = StripLocalePrefix<FileRouteTypes["to"]>;
 
-type LocalizedNavigate = {
-  (to: LocalizedTo): ReturnType<ReturnType<typeof useNavigate>>;
-  (
-    opts: { to: LocalizedTo } & Record<string, unknown>
-  ): ReturnType<ReturnType<typeof useNavigate>>;
+export type LocalizedNavigateOptions = Omit<
+  BaseNavigateOptions,
+  "to" | "params"
+> & {
+  to: LocalizedTo;
+  params?: Omit<NonNullable<BaseNavigateOptions["params"]>, "locale">;
 };
 
+type LocalizedNavigate = (
+  options: LocalizedNavigateOptions
+) => ReturnType<NavigateFn>;
+
 export const useLocalizedNavigate = () => {
   const navigate = useNavigate();
 
@@ -444,38 +432,6 @@ import { useLocalizedNavigate } from "@/hooks/useLocalizedNavigate";
 
 export const Route = createFileRoute("/{-$locale}/")({
   component: RouteComponent,
-  head: ({ params }) => {
-    const { locale } = params;
-    const path = "/"; // The path for this route
-
-    const metaContent = getIntlayer("app", locale);
-
-    return {
-      links: [
-        // Canonical link: Points to the current localized page
-        { rel: "canonical", href: getLocalizedUrl(path, locale) },
-
-        // Hreflang: Tell Google about all localized versions
-        ...localeMap(({ locale: mapLocale }) => ({
-          rel: "alternate",
-          hrefLang: mapLocale,
-          href: getLocalizedUrl(path, mapLocale),
-        })),
-
-        // x-default: For users in unmatched languages
-        // Define the default fallback locale (usually your primary language)
-        {
-          rel: "alternate",
-          hrefLang: "x-default",
-          href: getLocalizedUrl(path, defaultLocale),
-        },
-      ],
-      meta: [
-        { title: metaContent.title },
-        { name: "description", content: metaContent.meta.description },
-      ],
-    };
-  },
 });
 
 function RouteComponent() {
@@ -630,12 +586,33 @@ export const Route = createFileRoute("/{-$locale}/")({
   component: RouteComponent,
   head: ({ params }) => {
     const { locale } = params;
-    const metaContent = getIntlayer("page-metadata", locale);
+    const path = "/"; // The path for this route
+
+    const metaContent = getIntlayer("app", locale);
 
     return {
+      links: [
+        // Canonical link: Points to the current localized page
+        { rel: "canonical", href: getLocalizedUrl(path, locale) },
+
+        // Hreflang: Tell Google about all localized versions
+        ...localeMap(({ locale: mapLocale }) => ({
+          rel: "alternate",
+          hrefLang: mapLocale,
+          href: getLocalizedUrl(path, mapLocale),
+        })),
+
+        // x-default: For users in unmatched languages
+        // Define the default fallback locale (usually your primary language)
+        {
+          rel: "alternate",
+          hrefLang: "x-default",
+          href: getLocalizedUrl(path, defaultLocale),
+        },
+      ],
       meta: [
         { title: metaContent.title },
-        { content: metaContent.description, name: "description" },
+        { name: "description", content: metaContent.meta.description },
       ],
     };
   },