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: "This is a test application",  },  build: {    activateDynamicImport: true,  },};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. Токен доступа используется для аутентификации пользователя, связанного с проектом. Чтобы получить токен доступа, перейдите на /dashboard/project и создайте учетную запись.
- Пример: true
- Примечание: Важно: clientId и clientSecret должны храниться в секрете и не должны быть общедоступными. Убедитесь, что они хранятся в безопасном месте, например, в переменных окружения.
clientSecret:
- Тип: string | undefined
- По умолчанию: undefined
- Описание: clientId и clientSecret позволяют пакетам Intlayer аутентифицироваться с backend с использованием аутентификации oAuth2. Токен доступа используется для аутентификации пользователя, связанного с проектом. Чтобы получить токен доступа, перейдите на /dashboard/project и создайте учетную запись.
- Пример: true
- Примечание: Важно: clientId и clientSecret должны храниться в секрете и не должны быть общедоступными. Убедитесь, что они хранятся в безопасном месте, например, в переменных окружения.
hotReload:
- Тип: 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
- По умолчанию: true
- Описание: Включать ли локаль по умолчанию в URL.
- Пример: false
- Примечание: Если false, URL для локали по умолчанию не будут содержать префикс локали.
basePath:
- Тип: string
- По умолчанию: ''
- Описание: Базовый путь для URL приложения.
- Пример: '/my-app'
- Примечание: Это влияет на то, как формируются URL для приложения.
serverSetCookie:
- Тип: string
- По умолчанию: 'always'
- Описание: Правило для установки cookie локали на сервере.
- Опции: 'always', 'never'
- Пример: 'never'
- Примечание: Управляет, устанавливается ли cookie локали при каждом запросе или никогда.
noPrefix:
- Тип: boolean
- По умолчанию: false
- Описание: Исключать ли префикс локали из URL.
- Пример: true
- Примечание: Если true, URL не будут содержать информацию о локали.

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

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

Свойства

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']
- Описание: Путь к директории, где хранится контент.
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 заменит все вызовы словарей для оптимизации разделения на чанки. Таким образом, финальный бандл будет импортировать только используемые словари.

Примечание: @intlayer/babel доступен по умолчанию в пакете vite-intlayer, но @intlayer/swc не установлен по умолчанию в пакете next-intlayer, так как плагины SWC все еще экспериментальны в Next.js.

Свойства

optimize:
- Тип: boolean
- По умолчанию: process.env.NODE_ENV === 'production'
- Описание: Контролирует, должна ли быть оптимизирована сборка.
- Пример: true
- Примечание: Позволит импортировать в бандл только используемые словари. Но все импорты останутся статическими, чтобы избежать асинхронной обработки при загрузке словарей.
- Примечание: При включении Intlayer оптимизирует разделение словарей на чанки, заменяя все вызовы useIntlayer на useDictionary и getIntlayer на getDictionary.
- Примечание: Убедитесь, что все ключи объявлены статически в вызовах useIntlayer. например: useIntlayer('navbar').
activateDynamicImport:
- Тип: boolean
- По умолчанию: false
- Описание: Контролирует, должно ли содержимое словаря импортироваться динамически для каждой локали.
- Пример: true
- Примечание: Позволит динамически импортировать содержимое словаря только для текущей локали.
- Примечание: Динамические импорты зависят от React Suspense и могут немного влиять на производительность рендеринга. Но если отключено, все локали будут загружены одновременно, даже если они не используются.
- Примечание: При включении Intlayer оптимизирует разделение словарей на чанки, заменяя все вызовы useIntlayer на useDynamicDictionary.
- Примечание: Эта опция будет проигнорирована, если optimize отключен.
- Примечание: Убедитесь, что все ключи объявлены статически в вызовах useIntlayer. например: useIntlayer('navbar').
traversePattern:
- Тип: string[]
- По умолчанию: ['**/*.{js,ts,mjs,cjs,jsx,tsx,mjx,cjx,vue,svelte,svte}', '!**/node_modules/**']
- Описание: Шаблоны, определяющие, какие файлы должны быть обработаны во время оптимизации.
- Пример: ['src/**/*.{ts,tsx}', '../ui-library/**/*.{ts,tsx}', '!**/node_modules/**']
- Примечание: Используйте это для ограничения оптимизации релевантными файлами кода и улучшения производительности сборки.
- Примечание: Эта опция будет проигнорирована, если optimize отключен.
- Примечание: Используйте glob шаблон.

Если у вас есть идея по улучшению этой документации, не стесняйтесь внести свой вклад, подав запрос на вытягивание на GitHub.

Ссылка на документацию GitHub

Как работает Intlayer Объявление контента