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

Обзор

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

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

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

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

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

import { Locales, type IntlayerConfig } from "intlayer";const config: IntlayerConfig = {  internationalization: {    locales: [Locales.ENGLISH], // локали для интернационализации  },  content: {    autoFill: "./{{fileName}}.content.json", // автозаполнение контента из файла    contentDir: ["src", "../ui-library"], // директории с контентом  },  middleware: {    noPrefix: false, // использовать префикс в маршрутах  },  editor: {    applicationURL: "https://example.com", // URL приложения для редактора  },  ai: {    apiKey: process.env.OPENAI_API_KEY, // ключ API для AI    applicationContext: "This is a test application", // контекст приложения для AI  },  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 Intlayer CMS.
  • Пример: 'https://intlayer.org'
  • Примечание: URL Intlayer CMS.

• backendURL:

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

• enabled:

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

• clientId:

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

• clientSecret:

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

• dictionaryPriorityStrategy:

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

• liveSync:

  • Тип: boolean
  • По умолчанию: false
  • Описание: Указывает, должен ли сервер приложения автоматически обновлять содержимое приложения при обнаружении изменений в CMS / Визуальном редакторе / Бэкенде.
  • Пример: true
  • Примечание: Например, когда добавляется или обновляется новый словарь, приложение обновит содержимое для отображения на странице.
  • Примечание: Live sync требует внешнего размещения контента приложения на другом сервере. Это может немного повлиять на производительность приложения. Чтобы ограничить это, мы рекомендуем размещать приложение и сервер live sync на одной машине. Также комбинация live sync и optimize может привести к значительному количеству запросов к серверу live sync. В зависимости от вашей инфраструктуры, мы рекомендуем протестировать оба варианта и их комбинацию.

• liveSyncPort:

  • Тип: number
  • По умолчанию: 4000
  • Описание: Порт сервера live sync.
  • Пример: 4000
  • Примечание: Порт сервера live sync.

• liveSyncURL:

  • Тип: string
  • По умолчанию: 'http://localhost:{liveSyncPort}'
  • Описание: URL сервера live sync.
  • Пример: 'https://example.com'
  • Примечание: По умолчанию указывает на localhost, но может быть изменён на любой URL в случае удалённого сервера live sync.

Конфигурация 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': путь = /en/dashboard или /fr/dashboard
    • Если false и defaultLocale = 'en': путь = /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
  • Описание: Управляет тем, происходит ли определение локали во время запросов предварительной загрузки (prefetch) в 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">)
      • Вы хотите оптимизировать производительность предварительной загрузки
      • Вы хотите избежать потенциальных циклов перенаправления

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

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

Свойства

• autoFill:

  • Тип: boolean | string | { [key in Locales]?: string }
  • По умолчанию: undefined
  • Описание: Указывает, как содержимое должно автоматически заполняться с помощью ИИ. Может быть объявлено глобально в файле intlayer.config.ts.
  • Пример: true
  • Пример: './{{fileName}}.content.json'
  • Пример: { fr: './{{fileName}}.fr.content.json', es: './{{fileName}}.es.content.json' }
  • Примечание: Конфигурация автозаполнения. Может быть:
    • boolean: Включить автозаполнение для всех локалей
    • string: Путь к одному файлу или шаблону с переменными
    • object: Пути к файлам для каждой локали

• 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', '../../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] '
  • Примечание: Префикс логгера.

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

Настройки, управляющие функциями ИИ в Intlayer, включая провайдера, модель и API-ключ.

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

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

Intlayer поддерживает несколько провайдеров ИИ для повышения гибкости и выбора. В настоящее время поддерживаются следующие провайдеры:

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

Свойства

• provider:

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

• model:

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

• temperature:

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

• apiKey:

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

• applicationContext:

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

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

Настройки, которые контролируют, как 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' | 'live'
  • По умолчанию: 'static'
  • Описание: Управляет способом импорта словарей.
  • Пример: 'dynamic'
  • Примечание: Доступные режимы:
    • "static": Словари импортируются статически. Заменяет useIntlayer на useDictionary.
    • "dynamic": Словари импортируются динамически с использованием Suspense. Заменяет useIntlayer на useDictionaryDynamic.
• "live": Словари загружаются динамически с использованием API живой синхронизации. Заменяет useIntlayer на useDictionaryFetch.
• Примечание: Динамические импорты зависят от Suspense и могут незначительно повлиять на производительность рендеринга.
• Примечание: Если отключено, все локали будут загружены одновременно, даже если они не используются.
• Примечание: Эта опция зависит от плагинов @intlayer/babel и @intlayer/swc.
• Примечание: Убедитесь, что все ключи объявлены статически в вызовах useIntlayer, например useIntlayer('navbar').

• Примечание: Эта опция будет игнорироваться, если optimize отключен.

  • Примечание: Если установлено значение "live", только словари, содержащие удалённый контент и помеченные флагом "live", будут преобразованы в режим live. Остальные будут импортироваться динамически в режиме "dynamic" для оптимизации количества запросов и производительности загрузки.
  • Примечание: Режим live использует API живой синхронизации для получения словарей. Если вызов API не удаётся, словари будут импортированы динамически в режиме "dynamic".
  • Примечание: Эта опция не повлияет на функции 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.

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