Получайте уведомления о предстоящих релизах Intlayer
    Создание:2024-08-13Последнее обновление:2025-06-29

    Документация по конфигурации Intlayer

    Обзор

    Файлы конфигурации Intlayer позволяют настраивать различные аспекты плагина, такие как интернационализация, middleware и обработка контента. В этом документе приведено подробное описание каждого свойства конфигурации.

    Поддержка файлов конфигурации

    Intlayer поддерживает форматы файлов конфигурации JSON, JS, MJS и TS:

    • intlayer.config.ts
    • intlayer.config.js
    • intlayer.config.json
    • intlayer.config.cjs
    • intlayer.config.mjs
    • .intlayerrc

    Пример файла конфигурации

    intlayer.config.ts
    import { Locales, type IntlayerConfig } from "intlayer";const config: IntlayerConfig = {  internationalization: {    locales: [Locales.ENGLISH],  },  content: {    contentDir: ["src", "../ui-library"],  },  middleware: {    noPrefix: false,  },  editor: {    applicationURL: "https://example.com",  },  ai: {    apiKey: process.env.OPENAI_API_KEY,    applicationContext: "Это тестовое приложение",  },  build: {    importMode: "dynamic",  },};export default config;

    Справочник по конфигурации

    В следующих разделах описаны различные настройки конфигурации, доступные в Intlayer.

    Конфигурация интернационализации

    Определяет настройки, связанные с интернационализацией, включая доступные локали и локаль по умолчанию для приложения.

    Свойства

    • locales:

      • Тип: string[]
      • По умолчанию: ['en']
      • Описание: Список поддерживаемых локалей в приложении.
      • Пример: ['en', 'fr', 'es']
    • requiredLocales:
      • Тип: string[]
      • По умолчанию: []
      • Описание: Список обязательных локалей в приложении.
      • Пример: []
      • Примечание: Если пусто, все локали обязательны в режиме strict.
      • Примечание: Убедитесь, что обязательные локали также определены в поле locales.

    • strictMode:

      • Тип: string
      • По умолчанию: inclusive
      • Описание: Обеспечивает строгую реализацию интернационализированного контента с использованием TypeScript.
      • Примечание: Если установлено значение "strict", функция перевода t потребует, чтобы каждая объявленная локаль была определена. Если одна локаль отсутствует или локаль не объявлена в вашей конфигурации, будет выброшена ошибка.
      • Примечание: Если установлено значение "inclusive", функция перевода t потребует, чтобы каждая объявленная локаль была определена. Если одна локаль отсутствует, будет выдано предупреждение. Но будет принято, если локаль не объявлена в вашей конфигурации, но существует.
      • Примечание: Если установлено значение "loose", функция перевода t примет любую существующую локаль.

    • defaultLocale:

      • Тип: string
      • По умолчанию: 'en'
      • Описание: Локаль по умолчанию, используемая в качестве резервной, если запрашиваемая локаль не найдена.
      • Пример: 'en'
      • Примечание: Используется для определения локали, если она не указана в URL, cookie или заголовке.

    Конфигурация редактора

    Определяет настройки, связанные с интегрированным редактором, включая порт сервера и активный статус.

    Свойства

    • applicationURL:

      • Тип: string
      • По умолчанию: http://localhost:3000
      • Описание: URL приложения. Используется для ограничения происхождения редактора в целях безопасности.
      • Пример:
        • 'http://localhost:3000'
        • 'https://example.com'
        • process.env.INTLAYER_EDITOR_URL
      • Примечание: URL приложения. Используется для ограничения происхождения редактора в целях безопасности. Если установлено значение '*', редактор доступен с любого источника.

    • port:

      • Тип: number
      • По умолчанию: 8000
      • Описание: Порт, используемый сервером визуального редактора.

    • editorURL:

      • Тип: string
      • По умолчанию: 'http://localhost:8000'
      • Описание: URL сервера редактора. Используется для ограничения происхождения редактора в целях безопасности.
        • 'http://localhost:3000'
        • 'https://example.com'
        • process.env.INTLAYER_EDITOR_URL
      • Примечание: URL сервера редактора для доступа из приложения. Используется для ограничения источников, которые могут взаимодействовать с приложением в целях безопасности. Если установлено значение '*', редактор доступен с любого источника. Должно быть установлено, если порт изменен или если редактор размещен на другом домене.

    • cmsURL:

      • Тип: string
      • По умолчанию: 'https://intlayer.org'
      • Описание: URL CMS Intlayer.
      • Пример: 'https://intlayer.org'
      • Примечание: URL CMS Intlayer.

    • backendURL:

      • Тип: string
      • По умолчанию: https://back.intlayer.org
      • Описание: URL сервера backend.
      • Пример: http://localhost:4000

    • enabled:

      • Тип: boolean
      • По умолчанию: true
      • Описание: Указывает, взаимодействует ли приложение с визуальным редактором.
      • Пример: process.env.NODE_ENV !== 'production'
      • Примечание: Если true, редактор сможет взаимодействовать с приложением. Если false, редактор не сможет взаимодействовать с приложением. В любом случае редактор может быть включен только визуальным редактором. Отключение редактора для определенных сред - это способ обеспечения безопасности.

    • clientId:

      • Тип: string | undefined
      • По умолчанию: undefined
      • Описание: clientId и clientSecret позволяют пакетам intlayer аутентифицироваться с backend с использованием аутентификации oAuth2. Токен доступа используется для аутентификации пользователя, связанного с проектом. Чтобы получить токен доступа, перейдите на https://intlayer.org/dashboard/project и создайте учетную запись.
      • Пример: true
      • Примечание: Важно: clientId и clientSecret должны храниться в секрете и не должны быть общедоступными. Убедитесь, что они хранятся в безопасном месте, например, в переменных окружения.

    • clientSecret:

      • Тип: string | undefined
      • По умолчанию: undefined
      • Описание: clientId и clientSecret позволяют пакетам Intlayer аутентифицироваться с backend с использованием аутентификации oAuth2. Токен доступа используется для аутентификации пользователя, связанного с проектом. Чтобы получить токен доступа, перейдите на https://intlayer.org/dashboard/project и создайте учетную запись.
      • Пример: true
      • Примечание: Важно: clientId и clientSecret должны храниться в секрете и не должны быть общедоступными. Убедитесь, что они хранятся в безопасном месте, например, в переменных окружения.

    • liveSync:

      • Тип: boolean
      • По умолчанию: false
      • Описание: Указывает, должно ли приложение автоматически обновлять конфигурации локалей при обнаружении изменений.
      • Пример: true
      • Примечание: Например, когда добавляется или обновляется новый словарь, приложение обновит контент для отображения на странице.
      • Примечание: Поскольку горячая перезагрузка требует постоянного соединения с сервером, она доступна только для клиентов с планом enterprise.

    • dictionaryPriorityStrategy:

      • Тип: string
      • По умолчанию: 'local_first'
      • Описание: Стратегия приоритизации словарей в случае наличия как локальных, так и удаленных словарей. Если установлено значение 'distant_first', приложение будет отдавать приоритет удаленным словарям над локальными. Если установлено значение 'local_first', приложение будет отдавать приоритет локальным словарям над удаленными.
      • Пример: 'distant_first'

    Конфигурация Middleware

    Настройки, которые управляют поведением middleware, включая то, как приложение обрабатывает cookies, заголовки и префиксы URL для управления локалями.

    Свойства

    • headerName:

      • Тип: string
      • По умолчанию: 'x-intlayer-locale'
      • Описание: Имя HTTP-заголовка, используемого для определения локали.
      • Пример: 'x-custom-locale'
      • Примечание: Это полезно для определения локали на основе API.

    • cookieName:

      • Тип: string
      • По умолчанию: 'intlayer-locale'
      • Описание: Имя cookie, используемого для хранения локали.
      • Пример: 'custom-locale'
      • Примечание: Используется для сохранения локали между сессиями.

    • prefixDefault:

      • Тип: boolean
      • По умолчанию: false
      • Описание: Включать ли локаль по умолчанию в URL.
      • Пример: true
      • Примечание:
        • Если true и defaultLocale = 'en': path = /en/dashboard или /fr/dashboard
        • Если false и defaultLocale = 'en': path = /dashboard или /fr/dashboard

    • basePath:

      • Тип: string
      • По умолчанию: ''
      • Описание: Базовый путь для URL приложения.
      • Пример: '/my-app'
      • Примечание:
        • Если приложение размещено на https://example.com/my-app
        • Базовый путь '/my-app'
        • URL будет https://example.com/my-app/en
        • Если базовый путь не установлен, URL будет https://example.com/en

    • serverSetCookie:

      • Тип: string
      • По умолчанию: 'always'
      • Описание: Правило для установки cookie локали на сервере.
      • Опции: 'always', 'never'
      • Пример: 'never'
      • Примечание: Управляет, устанавливается ли cookie локали при каждом запросе или никогда.

    • noPrefix:

      • Тип: boolean
      • По умолчанию: false
      • Описание: Исключать ли префикс локали из URL.
      • Пример: true
      • Примечание:
        • Если true: Без префикса в URL
        • Если false: С префиксом в URL
        • Пример с basePath = '/my-app':
          • Если noPrefix = false: URL будет https://example.com/my-app/en
          • Если noPrefix = true: URL будет https://example.com

    • detectLocaleOnPrefetchNoPrefix:

      • Тип: boolean
      • По умолчанию: false
      • Описание: Управляет, происходит ли обнаружение локали во время запросов предварительной загрузки Next.js.
      • Пример: true
      • Примечание: Эта настройка влияет на то, как Next.js обрабатывает предварительную загрузку локали:
        • Пример сценария:
          • Язык браузера пользователя 'fr'
          • Текущая страница /fr/about
          • Ссылка предварительно загружает /about
        • С detectLocaleOnPrefetchNoPrefix: true:
          • Предварительная загрузка обнаруживает локаль 'fr' из браузера
          • Перенаправляет предварительную загрузку на /fr/about
        • С detectLocaleOnPrefetchNoPrefix: false (по умолчанию):
          • Предварительная загрузка использует локаль по умолчанию
          • Перенаправляет предварительную загрузку на /en/about (предполагая, что 'en' по умолчанию)
        • Когда использовать true:
          • Ваше приложение использует нелокализованные внутренние ссылки (например, <a href="/about">)
          • Вы хотите согласованное поведение обнаружения локали между обычными и предварительными запросами
        • Когда использовать false (по умолчанию):
          • Ваше приложение использует ссылки с префиксом локали (например, <a href="/fr/about">)
          • Вы хотите оптимизировать производительность предварительной загрузки
          • Вы хотите избежать потенциальных циклов перенаправления

    Конфигурация контента

    Настройки, связанные с обработкой контента в приложении, включая имена директорий, расширения файлов и производные конфигурации.

    Свойства

    • watch:

      • Тип: boolean
      • По умолчанию: process.env.NODE_ENV === 'development'
      • Описание: Указывает, должен ли Intlayer отслеживать изменения в файлах декларации контента в приложении для пересборки связанных словарей.

    • fileExtensions:

      • Тип: string[]
      • По умолчанию: ['.content.ts', '.content.js', '.content.cjs', '.content.mjs', '.content.json', '.content.tsx', '.content.jsx']
      • Описание: Расширения файлов, которые нужно искать при построении словарей.
      • Пример: ['.data.ts', '.data.js', '.data.json']
      • Примечание: Настройка расширений файлов может помочь избежать конфликтов.

    • baseDir:

      • Тип: string
      • По умолчанию: process.cwd()
      • Описание: Базовая директория для проекта.
      • Пример: '/path/to/project'
      • Примечание: Используется для разрешения всех связанных с Intlayer директорий.

    • dictionaryOutput:

      • Тип: string[]
      • По умолчанию: ['intlayer']
      • Описание: Тип вывода словаря, например, 'intlayer' или 'i18next'.

    • contentDir:

      • Тип: string[]
      • По умолчанию: ['src']
      • Пример: ['src', '../../ui-library', require.resolve("@my-package/content")]
      • Описание: Путь к директории, где хранится контент.

    • dictionariesDir:

      • Тип: string
      • По умолчанию: '.intlayer/dictionaries'
      • Описание: Путь к директории для хранения промежуточных или выходных результатов.

    • moduleAugmentationDir:

      • Тип: string
      • По умолчанию: '.intlayer/types'
      • Описание: Директория для расширения модулей, что позволяет улучшить подсказки IDE и проверку типов.
      • Пример: 'intlayer-types'
      • Примечание: Обязательно включите эту директорию в tsconfig.json.

    • unmergedDictionariesDir:

      • Тип: string
      • По умолчанию: '.intlayer/unmerged_dictionary'
      • Описание: Директория для хранения несмёрженных словарей.
      • Пример: 'translations'

    • dictionariesDir:

      • Тип: string
      • По умолчанию: '.intlayer/dictionary'
      • Описание: Директория для хранения словарей локализации.
      • Пример: 'translations'

    • i18nextResourcesDir:

      • Тип: string
      • По умолчанию: 'i18next_dictionary'
      • Описание: Директория для хранения словарей i18n.
      • Пример: 'translations'
      • Примечание: Убедитесь, что эта директория настроена для типа вывода i18next.

    • typesDir:

      • Тип: string
      • По умолчанию: 'types'
      • Описание: Директория для хранения типов словарей.
      • Пример: 'intlayer-types'

    • mainDir:

      • Тип: string
      • По умолчанию: 'main'
      • Описание: Директория, где хранятся основные файлы приложения.
      • Пример: 'intlayer-main'

    • excludedPath:

      • Тип: string[]
      • По умолчанию: ['node_modules']
      • Описание: Директории, исключённые из поиска контента.
      • Примечание: Эта настройка пока не используется, но планируется к реализации в будущем.

    Конфигурация логгера

    Настройки, управляющие логгером, включая используемый префикс.

    Свойства

    • mode:

      • Тип: string
      • По умолчанию: default
      • Описание: Указывает режим работы логгера.
      • Опции: default, verbose, disabled
      • Пример: default
      • Примечание: Режим логгера. Режим verbose будет выводить больше информации, но может использоваться для отладки. Режим disabled отключает логгер.

    • prefix:

      • Тип: string
      • По умолчанию: '[intlayer] '
      • Описание: Префикс логгера.
      • Пример: '[my custom prefix] '
      • Примечание: Префикс логгера.

    Конфигурация AI

    Настройки, управляющие функциями AI в Intlayer, включая провайдера, модель и API-ключ. Эта конфигурация является необязательной, если вы зарегистрированы на Intlayer Dashboard с использованием ключа доступа. Intlayer автоматически управляет наиболее эффективным и экономичным AI-решением для ваших нужд. Использование настроек по умолчанию обеспечивает лучшую долгосрочную поддержку, так как Intlayer постоянно обновляется для использования наиболее актуальных моделей.

    Если вы предпочитаете использовать свой собственный API-ключ или конкретную модель, вы можете определить свою пользовательскую конфигурацию AI. Эта конфигурация AI будет использоваться глобально во всей вашей среде Intlayer. Команды CLI будут использовать эти настройки по умолчанию для команд (например, fill), а также SDK, Visual Editor и CMS. Вы можете переопределить эти значения по умолчанию для конкретных случаев использования, используя параметры команд. Intlayer поддерживает нескольких провайдеров AI для повышения гибкости и выбора. В настоящее время поддерживаются следующие провайдеры:

    • OpenAI (по умолчанию)
    • Anthropic Claude
    • Mistral AI
    • DeepSeek
    • Google Gemini
    • Meta Llama

    Свойства

    • provider:

      • Тип: string
      • По умолчанию: 'openai'
      • Описание: Провайдер, используемый для функций AI в Intlayer.
      • Опции: 'openai', 'anthropic', 'mistral', 'deepseek', 'gemini'
      • Пример: 'anthropic'
      • Примечание: Разные провайдеры могут требовать разные API-ключи и иметь разные модели ценообразования.

    • model:

      • Тип: string
      • По умолчанию: Нет
      • Описание: Модель, используемая для функций AI в Intlayer.
      • Пример: 'gpt-4o-2024-11-20'
      • Примечание: Конкретная модель зависит от провайдера.

    • temperature:

      • Тип: number
      • По умолчанию: Нет
      • Описание: Температура контролирует случайность ответов AI.
      • Пример: 0.1
      • Примечание: Более высокая температура делает AI более креативным и менее предсказуемым.

    • apiKey:

      • Тип: string
      • По умолчанию: Нет
      • Описание: Ваш API-ключ для выбранного провайдера.
      • Пример: process.env.OPENAI_API_KEY
      • Примечание: Важно: API-ключи должны храниться в секрете и не должны быть общедоступными. Убедитесь, что они хранятся в безопасном месте, например, в переменных окружения.

    • applicationContext:

      • Тип: string
      • По умолчанию: Нет
      • Описание: Предоставляет дополнительный контекст о вашем приложении для AI-модели, помогая ей генерировать более точные и контекстно-подходящие переводы. Это может включать информацию о домене вашего приложения, целевой аудитории, тоне или специальной терминологии.

    Конфигурация сборки

    Настройки, которые контролируют, как Intlayer оптимизирует и собирает интернационализацию вашего приложения.

    Параметры сборки применяются к плагинам @intlayer/babel и @intlayer/swc.

    В режиме разработки Intlayer использует статические импорты для словарей, чтобы упростить процесс разработки.

    При оптимизации Intlayer заменит вызовы словарей для оптимизации разделения на чанки, чтобы финальный бандл импортировал только действительно используемые словари.

    Свойства

    • optimize:

      • Тип: boolean
      • По умолчанию: process.env.NODE_ENV === 'production'
      • Описание: Контролирует, должна ли быть оптимизирована сборка.
      • Пример: true
      • Примечание: При включении Intlayer заменит все вызовы словарей для оптимизации разделения на чанки. Таким образом, финальный бандл будет импортировать только используемые словари. Все импорты останутся статическими, чтобы избежать асинхронной обработки при загрузке словарей.
      • Примечание: Intlayer заменит все вызовы useIntlayer на режим, определенный опцией importMode, и getIntlayer на getDictionary.
      • Примечание: Эта опция зависит от плагинов @intlayer/babel и @intlayer/swc.
      • Примечание: Убедитесь, что все ключи объявлены статически в вызовах useIntlayer. например: useIntlayer('navbar').

    • importMode:

      • Тип: 'static' | 'dynamic' | 'async'
      • По умолчанию: 'static'
      • Описание: Контролирует, как импортируются словари.
      • Пример: 'dynamic'
      • Примечание: Доступные режимы:
        • "static": Словари импортируются статически. Заменяет useIntlayer на useDictionary.
        • "dynamic": Словари импортируются динамически с использованием Suspense. Заменяет useIntlayer на useDictionaryDynamic.
        • "async": Словари импортируются динамически асинхронно. Заменяет useIntlayer на await useDictionaryAsync.
      • Примечание: Динамические импорты зависят от Suspense и могут немного влиять на производительность рендеринга.
      • Примечание: Если отключено, все локали будут загружены одновременно, даже если они не используются.
      • Примечание: Эта опция зависит от плагинов @intlayer/babel и @intlayer/swc.
      • Примечание: Убедитесь, что все ключи объявлены статически в вызовах useIntlayer. например: useIntlayer('navbar').
      • Примечание: Эта опция будет проигнорирована, если optimize отключен.
      • Примечание: В большинстве случаев "dynamic" будет использоваться для React-приложений, "async" для Vue.js-приложений.
      • Примечание: Эта опция не повлияет на функции getIntlayer, getDictionary, useDictionary, useDictionaryAsync и useDictionaryDynamic.

    • traversePattern:

      • Тип: string[]
      • По умолчанию: ['**/*.{js,ts,mjs,cjs,jsx,tsx,mjx,cjx}', '!**/node_modules/**']
      • Описание: Шаблоны, определяющие, какие файлы должны быть обработаны во время оптимизации.
        • Пример: ['src/**/*.{ts,tsx}', '../ui-library/**/*.{ts,tsx}', '!**/node_modules/**']
      • Примечание: Используйте это для ограничения оптимизации релевантными файлами кода и улучшения производительности сборки.
      • Примечание: Эта опция будет проигнорирована, если optimize отключен.
      • Примечание: Используйте шаблоны glob.

    История документации

    • 5.5.11 - 2025-06-29: Добавлены команды docs
    Как работает Intlayer
    CLI
    Получайте уведомления о предстоящих релизах Intlayer