Документація з конфігурації Intlayer

import { Locales, type IntlayerConfig } from "intlayer";
import { nextjsRewrite } from "intlayer/routing";
import { syncJSON } from "@intlayer/sync-json-plugin";
import { z } from "zod";

/**
 * Приклад конфігураційного файлу Intlayer з усіма доступними параметрами.
 */
const config: IntlayerConfig = {
  /**
   * Конфігурація налаштувань інтернаціоналізації.
   */
  internationalization: {
    /**
     * Список підтримуваних локалей у додатку.
     * За замовчуванням: [Locales.ENGLISH]
     */
    locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],

    /**
     * Список обов'язкових локалей, які повинні бути визначені в кожному словнику.
     * Якщо порожній, усі локалі є обов'язковими в режимі `strict`.
     * За замовчуванням: []
     */
    requiredLocales: [Locales.ENGLISH],

    /**
     * Рівень суворості для інтернаціоналізованого контенту.
     * - "strict": Помилка, якщо оголошені локалі відсутні або використовуються неоголошені локалі.
     * - "inclusive": Попередження, якщо оголошені локалі відсутні.
     * - "loose": Приймає будь-яку існуючу локаль.
     * За замовчуванням: "inclusive"
     */
    strictMode: "inclusive",

    /**
     * Локаль за замовчуванням, яка використовується як резервна, якщо запитувана локаль недоступна.
     * За замовчуванням: Locales.ENGLISH
     */
    defaultLocale: Locales.ENGLISH,
  },

  /**
   * Налаштування для контролю операцій зі словниками та поведінки при відсутності контенту.
   */
  dictionary: {
    /**
     * Контролює спосіб імпорту словників.
     * - "static": Статичний імпорт під час збірки.
     * - "dynamic": Динамічний імпорт за допомогою Suspense.
     * - "fetch": Динамічне отримання через Live Sync API.
     * За замовчуванням: "static"
     */
    importMode: "static",

    /**
     * Стратегія автоматичного заповнення відсутніх перекладів за допомогою AI.
     * Може бути логічним значенням або шаблоном шляху для збереження заповненого контенту.
     * За замовчуванням: true
     */
    fill: true,

    /**
     * Фізичне місце розташування файлів словників.
     * - "local": Зберігаються у локальній файловій системі.
     * - "remote": Зберігаються в Intlayer CMS.
     * - "hybrid": Зберігаються і локально, і в Intlayer CMS.
     * - "plugin" (або будь-який рядок): Надаються плагіном або власним джерелом.
     * За замовчуванням: "local"
     */
    location: "local",

    /**
     * Чи слід автоматично перетворювати контент (наприклад, Markdown у HTML).
     * За замовчуванням: false
     */
    contentAutoTransformation: false,
  },

  /**
   * Конфігурація маршрутизації та проміжного ПЗ.
   */
  routing: {
    /**
     * Стратегія маршрутизації локалей.
     * - "prefix-no-default": Префікс для всіх мов, крім стандартної (наприклад, /dashboard, /fr/dashboard).
     * - "prefix-all": Префікс для всіх мов (наприклад, /en/dashboard, /fr/dashboard).
     * - "no-prefix": Локаль не вказується в URL.
     * - "search-params": Використовувати ?locale=...
     * За замовчуванням: "prefix-no-default"
     */
    mode: "prefix-no-default",

    /**
     * Вмикає проксі маршрутизації локалей Intlayer (middleware).
     * Відповідає за визначення локалі, перенаправлення та перезапис URL у dev, preview та SSR.
     * - не задано (auto): сервери dev і preview зберігають маршрутизацію за URL,
     *   ігноруючи локаль, збережену в cookie та заголовках. Префікси й далі
     *   розв’язуються, локаль і далі зберігається, а визначення Accept-Language
     *   і далі діє. У продакшені поводиться як `true`.
     * - true: повна поведінка в усіх середовищах.
     * - false: маршрутизація локалей вимкнена.
     * За замовчуванням: undefined (auto)
     */
    enableProxy: undefined,

    /**
     * Де зберігається вибрана користувачем локаль.
     * Варіанти: 'cookie', 'localStorage', 'sessionStorage', 'header' або їх масив.
     * За замовчуванням: ['cookie', 'header']
     */
    storage: ["cookie", "header"],

    /**
     * Базовий шлях для URL додатка.
     * За замовчуванням: ""
     */
    basePath: "",

    /**
     * Власні правила перенаправлення URL для конкретних локалізованих шляхів.
     */
    rewrite: nextjsRewrite({
      "/[locale]/about": {
        en: "/[locale]/about",
        fr: "/[locale]/a-propos",
      },
    }),

    /**
     * Відображає локалі на імена хостів доменів для маршрутизації на основі доменів.
     * URL для цих локалей будуть абсолютними (наприклад, https://intlayer.cn/).
     * Домен сам по собі вказує на локаль, тому префікс локалі не додається до шляху.
     * За замовчуванням: undefined
     */
    domains: {
      en: "intlayer.org",
      zh: "intlayer.cn",
    },
  },

  /**
   * Налаштування для пошуку та обробки файлів контенту.
   */
  content: {
    /**
     * Розширення файлів для сканування словників.
     * За замовчуванням: ['.content.ts', '.content.js', '.content.json' тощо]
     */
    fileExtensions: [".content.ts", ".content.js", ".content.json"],

    /**
     * Директорії для файлів .content.
     * За замовчуванням: ["."]
     */
    contentDir: ["src"],

    /**
     * Директорія вихідного коду.
     * Використовується для оптимізації збірки та перетворень коду.
     * За замовчуванням: ["."]
     */
    codeDir: ["src"],

    /**
     * Шаблони для виключення зі сканування.
     * За замовчуванням: ['node_modules', '.intlayer' тощо]
     */
    excludedPath: ["node_modules"],

    /**
     * Чи слід відстежувати зміни та перегенеровувати словники під час розробки.
     * За замовчуванням: true у режимі розробки
     */
    watch: true,

    /**
     * Команда для форматування новостворених / оновлених файлів .content.
     */
    formatCommand: 'npx prettier --write "{{file}}"',
  },

  /**
   * Конфігурація візуального редактора.
   */
  editor: {
    /**
     * Чи ввімкнено візуальний редактор.
     * За замовчуванням: false
     */
    enabled: true,

    /**
     * URL вашого додатка для перевірки джерела.
     * За замовчуванням: ""
     */
    applicationURL: "http://localhost:3000",

    /**
     * Порт сервера локального редактора.
     * За замовчуванням: 8000
     */
    port: 8000,

    /**
     * Публічний URL редактора.
     * За замовчуванням: "http://localhost:8000"
     */
    editorURL: "http://localhost:8000",

    /**
     * URL Intlayer CMS.
     * За замовчуванням: "https://app.intlayer.org"
     */
    cmsURL: "https://app.intlayer.org",

    /**
     * URL бекенд-сервера API.
     * За замовчуванням: "https://back.intlayer.org"
     */
    backendURL: "https://back.intlayer.org",

    /**
     * Чи ввімкнено синхронізацію контенту в реальному часі.
     * За замовчуванням: false
     */
    liveSync: true,
  },

  /**
   * Конфігурація аналітики (analytics).
   */
  analytics: {
    /**
     * Чи увімкнено збір аналітики (перегляди сторінок, показ контенту, події A/B).
     * Потребує встановленого пакета `@intlayer/analytics` та встановленого `editor.clientId` для атрибуції.
     * За замовчуванням: true
     */
    enabled: true,

    /**
     * Мілісекунди між автоматичними пакетними відправками на бекенд.
     * За замовчуванням: 20000
     */
    flushInterval: 20000,

    /**
     * Частка сеансів для запису, від 0 (жодного) до 1 (усі).
     * За замовчуванням: 1
     */
    sampleRate: 1,
  },

  /**
   * Налаштування для перекладів та генерації за допомогою AI.
   */
  ai: {
    /**
     * Використовуваний провайдер AI.
     * Варіанти: 'openai', 'anthropic', 'mistral', 'deepseek', 'gemini', 'ollama', 'openrouter', 'alibaba', 'fireworks', 'groq', 'huggingface', 'bedrock', 'googlevertex', 'togetherai', 'lmstudio', 'moonshotai'
     * За замовчуванням: 'openai'
     */
    provider: "openai",

    /**
     * Модель, що використовується для вибраного провайдера.
     */
    model: "gpt-4o",

    /**
     * API-ключ для провайдера.
     */
    apiKey: process.env.OPENAI_API_KEY,

    /**
     * Глобальний контекст для допомоги AI під час генерації перекладів.
     */
    applicationContext: "Це додаток для бронювання подорожей.",

    /**
     * Базовий URL для AI API.
     */
    baseURL: "http://localhost:3000",

    /**
     * Серіалізація даних (Data Serialization)
     *
     * Варіанти:
     * - "json": за замовчуванням, надійний; використовує більше токенів.
     * - "toon": швидше, менше токенів, менш стабільний за JSON.
     *
     * За замовчуванням: "json"
     */
    dataSerialization: "json",
  },

  /**
   * Налаштування збірки та оптимізації.
   */
  build: {
    /**
     * Режим виконання збірки.
     * - "auto": Автоматична збірка під час збірки додатка.
     * - "manual": Потрібна явна команда для збірки.
     * За замовчуванням: "auto"
     */
    mode: "auto",

    /**
     * Чи слід оптимізувати пакет додатка шляхом видалення невикористовуваних словників.
     * За замовчуванням: true у виробничому середовищі
     */
    optimize: true,

    /**
     * Мініфікувати словники для зменшення розміру бандла.
     * За замовчуванням: true
     *
     * Примітка:
     * - Цей параметр буде ігноруватися, якщо `optimize` вимкнено.
     * - Цей параметр буде ігноруватися, якщо `editor.enabled` має значення true.
     */
    minify: true,

    /**
     * Видалити невикористовувані ключі в словниках.
     * За замовчуванням: true
     *
     * Примітка:
     * - Цей параметр буде ігноруватися, якщо `optimize` вимкнено.
     */
    purge: true,

    /**
     * Групувати чанки словників за локаллю відповідно до межі розділення коду, яка
     * їх використовує, щоб ліниво завантажена сторінка отримувала свій вміст одним
     * запитом.
     * За замовчуванням: true
     *
     * Примітка:
     * - Застосовується лише до словників з `importMode: 'dynamic'`.
     */
    chunkGrouping: true,

    /**
     * Завантажувати словник разом із чанком, який його використовує, замість
     * отримання після рендерингу цього чанка. Читання рендеряться синхронно
     * замість призупинення, тому під час навігації більше не блимає стан
     * завантаження.
     * За замовчуванням: true
     *
     * Примітка:
     * - Очікується лише визначена локаль, тому сторінка завантажує тільки ту мову,
     *   яку відображає.
     */
    dictionariesPreload: true,

    /**
     * Формат виводу для згенерованих файлів словників.
     * За замовчуванням: ['cjs', 'esm']
     */
    outputFormat: ["cjs", "esm"],

    /**
     * Чи виконувати перевірку типів TypeScript під час збірки.
     * За замовчуванням: false
     */
    checkTypes: false,
  },

  /**
   * Конфігурація логера.
   */
  log: {
    /**
     * Режим логування.
     * - "default": Стандартне логування.
     * - "verbose": Детальне логування для відлагодження.
     * - "disabled": Вимкнути логування.
     * За замовчуванням: "default"
     */
    mode: "default",

    /**
     * Префікс для всіх повідомлень у логах.
     * За замовчуванням: "[intlayer]"
     */
    prefix: "[intlayer]",
  },

  /**
   * Системна конфігурація (для просунутого використання)
   */
  system: {
    /**
     * Директорія, де зберігаються локалізовані словники.
     */
    dictionariesDir: ".intlayer/dictionary",

    /**
     * Директорія для module augmentation.
     */
    moduleAugmentationDir: ".intlayer/types",

    /**
     * Директорія для незлитих словників.
     */
    unmergedDictionariesDir: ".intlayer/unmerged_dictionary",

    /**
     * Директорія для типів словників.
     */
    typesDir: ".intlayer/types",

    /**
     * Де знаходяться основні файли додатка.
     */
    mainDir: ".intlayer/main",

    /**
     * Директорія для скомпільованих файлів конфігурації.
     */
    configDir: ".intlayer/config",

    /**
     * Директорія для кеш-файлів.
     */
    cacheDir: ".intlayer/cache",
  },

  /**
   * Конфігурація компілятора (для просунутого використання)
   */
  compiler: {
    /**
     * Чи ввімкнено компілятор.
     *
     * - false: вимкнути компілятор.
     * - true: увімкнути компілятор.
     * - "build-only": пропускати компілятор під час розробки для швидшого запуску.
     *
     * За замовчуванням: false
     */
    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: ({ locale, key }) => `compiler/${locale}/${key}.json`,

    /**
     * Чи зберігати компоненти після їх перетворення.
     * Таким чином, можна запустити компілятор один раз для перетворення додатка, а потім видалити його.
     */
    saveComponents: false,

    /**
     * Залишати лише контент у згенерованому файлі. Корисно для форматів i18next або ICU MessageFormat JSON по локалях.
     */
    noMetadata: false,

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

  /**
   * Настроювані схеми для валідації контенту словників.
   */
  schemas: {
    "my-schema": z.object({
      title: z.string(),
    }),
  },

  /**
   * Конфігурація словника.
   */
  dictionary: {
    /**
     * Керує способом імпорту словників.
     * - "static": Статично імпортується під час збірки.
     * - "dynamic": Динамічно імпортується за допомогою Suspense.
     * - "fetch": Динамічно завантажується через API живої синхронізації.
     */
    importMode: "static",

    /**
     * Формат повідомлень за замовчуванням для всіх словників у проекті.
     * - 'intlayer': Власний формат intlayer (за замовчуванням).
     * - 'icu': Формат повідомлень ICU.
     * - 'i18next': Формат i18next.
     * - 'vue-i18n': Формат Vue I18n.
     * - 'po': Формат GNU Gettext PO.
     */
    format: "icu",
  },

  /**
   * Конфігурація плагінів.
   */
  plugins: [
    syncJSON({
      format: "icu",
      source: ({ locale }) => `./messages/${locale}.json`,
    }),
  ],
};

export default config;

routing: {
  mode: "prefix-no-default", // Резервна стратегія
  rewrite: nextjsRewrite({
    "/about": {
      en: "/about",
      fr: "/a-propos",
    },
    "/product/[slug]": {
      en: "/product/[slug]",
      fr: "/produit/[slug]",
    },
    "/blog/[category]/[id]": {
      en: "/blog/[category]/[id]",
      fr: "/journal/[category]/[id]",
    },
  }),
}

import { Locales, type IntlayerConfig } from "intlayer";
// intlayer.config.ts
const config: IntlayerConfig = {
  internationalization: {
    locales: ["en", "fr", "es"],
    defaultLocale: "en",
  },
  routing: {
    mode: "prefix-no-default",
    storage: "localStorage",
    basePath: "",
  },
};

export default config;

import { Locales, type IntlayerConfig } from "intlayer";
// intlayer.config.ts
const config: IntlayerConfig = {
  internationalization: {
    locales: ["en", "fr", "es"],
    defaultLocale: "en",
  },
  routing: {
    mode: "prefix-no-default",
    storage: [
      {
        type: "localStorage",
        name: "user-locale",
      },
      {
        type: "cookie",
        name: "user-locale",
        secure: true,
        sameSite: "strict",
        httpOnly: false,
      },
    ],
    basePath: "",
  },
};

export default config;

import { Locales, type IntlayerConfig } from "intlayer";
// intlayer.config.ts
const config: IntlayerConfig = {
  internationalization: {
    locales: ["en", "fr", "es"],
    defaultLocale: "en",
  },
  routing: {
    mode: "search-params",
    storage: "localStorage",
    basePath: "",
  },
};

export default config;

import { Locales, type IntlayerConfig } from "intlayer";
// intlayer.config.ts
const config: IntlayerConfig = {
  internationalization: {
    locales: ["en", "fr", "es"],
    defaultLocale: "en",
  },
  routing: {
    mode: "no-prefix",
    storage: {
      type: "sessionStorage",
      name: "app-locale",
    },
    basePath: "/my-app",
  },
};

export default config;

// intlayer.config.ts
import { nextjsRewrite } from "intlayer/routing";

const config: IntlayerConfig = {
  internationalization: {
    locales: ["en", "fr"],
    defaultLocale: "en",
  },
  routing: {
    mode: "prefix-no-default", // Резервний варіант для неперенаправлених шляхів
    storage: "cookie",
    rewrite: nextjsRewrite({
      "/about": {
        en: "/about",
        fr: "/a-propos",
      },
      "/product/[slug]": {
        en: "/product/[slug]",
        fr: "/produit/[slug]",
      },
      "/blog/[category]/[id]": {
        en: "/blog/[category]/[id]",
        fr: "/journal/[category]/[id]",
      },
    }),
  },
};

export default config;

dictionary: {
  fill: {
    en: "/locales/en/{{key}}.content.json",
    fr: ({ key }) => `/locales/fr/${key}.content.json`,
    es: false,
  },
};