Документация по конфигурации 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": Статический импорт во время сборки (build time).
     * - "dynamic": Динамический импорт с использованием Suspense.
     * - "fetch": Динамическое получение через API Live Sync.
     * По умолчанию: "static"
     */
    importMode: "static",

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

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

    /**
     * Нужно ли автоматически преобразовывать контент (например, Markdown в HTML).
     * По умолчанию: false
     */
    contentAutoTransformation: false,
  },

  /**
   * Конфигурация маршрутизации и middleware.
   */
  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 вашего приложения для валидации источника (origin).
     * По умолчанию: ""
     */
    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: {
    /**
     * Используемый ИИ-провайдер.
     * Опции: '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,

    /**
     * Глобальный контекст для направления ИИ при генерации переводов.
     */
    applicationContext: "Это приложение для бронирования путешествий.",

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

    /**
     * Сериализация данных
     *
     * Опции:
     * - "json": По умолчанию, надежно; потребляет больше токенов.
     * - "toon": Меньше токенов, менее стабильно, чем JSON.
     *
     * По умолчанию: "json"
     */
    dataSerialization: "json",
  },

  /**
   * Настройки сборки и оптимизации.
   */
  build: {
    /**
     * Режим выполнения сборки.
     * - "auto": Автоматическая сборка во время сборки (build time) приложения.
     * - "manual": Требуется явная команда сборки.
     * По умолчанию: "auto"
     */
    mode: "auto",

    /**
     * Нужно ли оптимизировать итоговый бандл, удаляя неиспользуемые словари.
     * По умолчанию: true в продакшене
     */
    optimize: true,

    /**
     * Минимизировать словари для уменьшения размера бандла.
     * По умолчанию: false
     *
     * Примечание:
     * - Эта опция будет проигнорирована, если `optimize` отключена.
     * - Эта опция будет проигнорирована, если `editor.enabled` имеет значение true.
     */
    minify: true,

    /**
     * Удалить неиспользуемые ключи в словарях.
     * По умолчанию: false
     *
     * Примечание:
     * - Эта опция будет проигнорирована, если `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",

    /**
     * Директория для хранения неслитых (unmerged) словарей.
     */
    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`: Язык контента (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,
  },
};