Skip to content

compiler.md

Latest commit

 

History

History
347 lines (272 loc) · 17 KB

compiler.md

File metadata and controls

347 lines (272 loc) · 17 KB
createdAt 2025-09-09
updatedAt 2026-03-12
title Intlayer Compiler | Автоматизоване витягування контенту для i18n
description Автоматизуйте процес інтернаціоналізації за допомогою Intlayer Compiler. Витягуйте контент безпосередньо з ваших компонентів для швидшого та ефективнішого i18n у Vite, Next.js та інших.
keywords
Intlayer
Compiler
Інтернаціоналізація
i18n
Автоматизація
Екстракція
Швидкість
Vite
Next.js
React
Vue
Svelte
slugs
doc
compiler
history
version date changes
8.2.0
2026-03-09
Оновлення опцій компілятора, додана підтримка FilePathPattern
version date changes
8.1.7
2026-02-25
Оновлення опцій компілятора
version date changes
7.3.1
2025-11-27
Випуск компілятора

Intlayer Compiler | Автоматизоване витягування контенту для i18n

Що таке Intlayer Compiler?

Intlayer Compiler - це потужний інструмент, розроблений для автоматизації процесу інтернаціоналізації (i18n) у ваших додатках. Він сканує ваш вихідний код (JSX, TSX, Vue, Svelte) на наявність декларацій контенту, витягує їх і автоматично генерує необхідні файли словників. Це дозволяє зберігати контент поруч із компонентами, тоді як Intlayer займається керуванням та синхронізацією ваших словників.

Чому використовувати Intlayer Compiler?

  • Автоматизація: Усуває ручне копіювання та вставляння контенту у словники.
  • Швидкість: Оптимізоване витягування контенту забезпечує швидкість процесу збірки.
  • Досвід розробника: Тримайте декларації контенту там, де вони використовуються, що покращує підтримуваність.
  • Оновлення в реальному часі: Підтримує Hot Module Replacement (HMR) для миттєвого зворотного зв'язку під час розробки.

Див. статтю в блозі Compiler vs. Declarative i18n для глибшого порівняння.

Чому не використовувати Intlayer Compiler?

Хоча компілятор пропонує чудовий досвід «just works», він також вносить певні компроміси, про які варто знати:

  • Евристична неоднозначність: Компілятор має вгадувати, що є контентом для користувача, а що - логікою додатка (наприклад, className="active", коди статусів, ID продуктів). У складних кодових базах це може призводити до хибних спрацьовувань або пропущених рядків, що вимагатиме ручних анотацій та винятків.
  • Тільки статична екстракція: Екстракція на основі компілятора покладається на статичний аналіз. Рядки, які існують лише під час виконання (коди помилок API, поля CMS тощо), не можуть бути виявлені або перекладені лише компілятором, тому вам усе одно знадобиться додаткова стратегія i18n під час виконання.

Для глибшого архітектурного порівняння див. статтю в блозі Compiler vs. Declarative i18n.

Як альтернативу, щоб автоматизувати ваш процес i18n і зберегти повний контроль над контентом, Intlayer також пропонує команду автоматичної екстракції intlayer extract (див. документацію CLI), або команду Intlayer: extract content to Dictionary з розширення Intlayer для VS Code (див. документацію розширення VS Code).

Використання

Vite

Для додатків на базі Vite (React, Vue, Svelte тощо) найпростіший спосіб використовувати компілятор - через плагін vite-intlayer.

Встановлення

npm install vite-intlayer

Налаштування

Оновіть ваш vite.config.ts, щоб включити плагін intlayerCompiler:

import { defineConfig } from "vite";
import { intlayer, intlayerCompiler } from "vite-intlayer";

export default defineConfig({
  plugins: [
    intlayer(),
    intlayerCompiler(), // Додає плагін компілятора
  ],
});

See complete tutorial: Intlayer Compiler with Vite+React

Підтримка фреймворків

Плагін Vite автоматично визначає та обробляє різні типи файлів:

  • React / JSX / TSX: Обробляються нативно.
  • Vue: Потребує @intlayer/vue-compiler.
  • Svelte: Потребує @intlayer/svelte-compiler.

Переконайтеся, що встановили відповідний пакет компілятора для вашого фреймворку:

# Для Vue
npm install @intlayer/vue-compiler

# Для Svelte
npm install @intlayer/svelte-compiler

Next.js (Babel)

Для Next.js або інших додатків на базі Webpack, що використовують Babel, ви можете налаштувати компілятор за допомогою плагіна @intlayer/babel.

Встановлення

npm install @intlayer/babel

Налаштування

Оновіть ваш babel.config.js (або babel.config.json), щоб додати плагін для екстракції. Ми надаємо хелпер getExtractPluginOptions, який автоматично завантажує вашу конфігурацію Intlayer.

const {
  intlayerExtractBabelPlugin,
  intlayerOptimizeBabelPlugin,
  getExtractPluginOptions,
  getOptimizePluginOptions,
} = require("@intlayer/babel");

module.exports = {
  presets: ["next/babel"],
  plugins: [
    // Витягує контент з компонентів у словники
    [intlayerExtractBabelPlugin, getExtractPluginOptions()],
    // Оптимізує імпорти, замінюючи useIntlayer на прямі імпорти словників
    [intlayerOptimizeBabelPlugin, getOptimizePluginOptions()],
  ],
};

Ця конфігурація гарантує, що контент, оголошений у ваших компонентах, буде автоматично витягнутий і використаний для генерації словників під час процесу збірки.

See complete tutorial: Intlayer Compiler with Next.js

Користувацька конфігурація

Щоб налаштувати поведінку компілятора, ви можете оновити файл intlayer.config.ts у корені вашого проєкту.

import { type IntlayerConfig, Locales } from "intlayer";

const config: IntlayerConfig = {
  compiler: {
    /**
     * Вказує, чи має бути увімкнено компілятор.
     * Встановіть значення 'build-only', щоб пропустити компілятор під час розробки та прискорити запуск.
     */
    enabled: true,

    /**
     * Визначає шлях до вихідних файлів. Замінює `outputDir`.
     *
     * - Шляхи, що починаються з `./`, розв'язуються відносно каталогу компонента.
     * - Шляхи, що починаються з `/`, розв'язуються відносно кореня проєкту (`baseDir`).
     *
     * - Включення змінної `{{locale}}` у шлях дозволить генерувати словники, розділені за локалями.
     *
     * Приклади:
     * ```ts
     * {
     *   // Створює багатомовні файли .content.ts поруч із компонентом
     *   output: ({ fileName, extension }) => `./${fileName}${extension}`,
     *
     *   // output: './{{fileName}}{{extension}}', // Еквівалент з використанням рядкового шаблону
     * }
     * ```
     *
     * ```ts
     * {
     *   // Створює централізовані JSON-файли за локалями в корені проєкту
     *   output: ({ key, locale }) => `/locales/${locale}/${key}.content.json`,
     *
     *   // output: '/locales/{{locale}}/{{key}}.content.json', // Еквівалент з використанням рядкового шаблону
     * }
     * ```
     *
     * Список змінних:
     *   - `fileName`: Назва файлу.
     *   - `key`: Ключ контенту.
     *   - `locale`: Локаль контенту.
     *   - `extension`: Розширення файлу.
     *   - `componentFileName`: Назва файлу компонента.
     *   - `componentExtension`: Розширення файлу компонента.
     *   - `format`: Формат словника.
     *   - `componentFormat`: Формат словника компонента.
     *   - `componentDirPath`: Шлях до каталогу компонента.
     */
    output: ({ fileName, extension }) => `./${fileName}${extension}`,

    /**
     * Вказує, чи мають компоненти зберігатися після трансформації.
     * Таким чином компілятор можна запустити лише один раз для трансформації додатка, а потім видалити.
     */
    saveComponents: false,

    /**
     * Вставляє лише контент у згенерований файл. Корисно для виводу JSON для i18next або ICU MessageFormat для кожної локалі.
     *
     * - `output: ({ locale, key }) => `./locale/${locale}/${key}.json`,`
     */
    noMetadata: false,

    /**
     * Префікс ключа словника
     */
    dictionaryKeyPrefix: "", // Додає необов'язковий префікс для витягнутих ключів словника
  },
};

export default config;

Довідник з конфігурації компілятора

Наступні властивості можна налаштувати в блоці compiler вашого файлу intlayer.config.ts:

  • enabled:

    • Тип: boolean | 'build-only'
    • Типово: true
    • Опис: Вказує, чи має бути увімкнено компілятор.

  • dictionaryKeyPrefix:

    • Тип: string
    • Типово: ''
    • Опис: Префікс для витягнутих ключів словника.

  • transformPattern:

    • Тип: string | string[]
    • Типово: ['**/*.{js,ts,mjs,cjs,jsx,tsx,vue,svelte}', '!**/node_modules/**']
    • Опис: (Застаріло: використовуйте build.traversePattern) Шаблони для обходу коду для оптимізації.

  • excludePattern:

    • Тип: string | string[]
    • Типово: ['**/node_modules/**']
    • Опис: (Застаріло: використовуйте build.traversePattern) Шаблони для виключення з оптимізації.

  • output:

    • Тип: FilePathPattern
    • Типово: ({ key }) => 'compiler/${key}.content.json'
    • Опис: Визначає шлях до вихідних файлів. Замінює outputDir. Обробляє динамічні змінні, такі як {{locale}}, {{key}}, {{fileName}}, {{extension}}, {{format}}, {{dirPath}}, {{componentFileName}}, {{componentExtension}} та {{componentFormat}}. Можна встановити як рядок у форматі 'my/{{var}}/path' або як функцію.
    • Примітка: Шляхи ./**/* розв'язуються відносно компонента. Шляхи /**/* розв'язуються відносно baseDir Intlayer.
    • Примітка: Якщо локаль визначена в шляху, словники будуть генеруватися для кожної локалі.
    • Приклад: output: ({ locale, key }) => 'compiler/${locale}/${key}.json'

  • noMetadata:

    • Тип: boolean
    • Типово: false
    • Опис: Вказує, чи мають метадані зберігатися у файлі. Якщо true, компілятор не зберігатиме метадані словників (ключ, оболонка вмісту). Корисно для виводу JSON для i18next або ICU MessageFormat для кожної локалі.
    • Примітка: Корисно при використанні з плагіном loadJSON.
    • Приклад: Якщо true: 
      {
  "key": "value"
}
      Якщо false: 
      {
  "key": "value",
  "content": {
    "key": "value"
  }
}

  • saveComponents:

    • Тип: boolean
    • Типово: false
    • Опис: Вказує, чи мають компоненти зберігатися після трансформації.

Заповнення відсутніх перекладів

Intlayer надає CLI-інструмент, який допоможе заповнити відсутні переклади. Ви можете використовувати команду intlayer для перевірки та заповнення відсутніх перекладів у вашому коді.

npx intlayer test         # Перевірити наявність відсутніх перекладів
yarn intlayer test         # Перевірити наявність відсутніх перекладів
pnpm intlayer test         # Перевірити наявність відсутніх перекладів
bun x intlayer test         # Перевірити наявність відсутніх перекладів
npx intlayer fill         # Заповнити відсутні переклади
yarn intlayer fill         # Заповнити відсутні переклади
pnpm intlayer fill         # Заповнити відсутні переклади
bun x intlayer fill         # Заповнити відсутні переклади

Екстракція

Intlayer надає CLI-інструмент, який допоможе вам витягти контент із вашого коду. Ви можете використовувати команду intlayer extract, щоб витягти контент із вашого коду.

npx intlayer extract
yarn intlayer extract
pnpm intlayer extract
bun x intlayer extract

Для отримання детальнішої інформації див. документацію CLI