@intlayer/docs 5.5.8

package/ru/configuration.md

@@ -0,0 +1,507 @@
+# Intlayer Конфигурационная Документация
+
+## Обзор
+
+Файлы конфигурации Intlayer позволяют настроить различные аспекты плагина, такие как интернационализация, middleware и обработка контента. Этот документ предоставляет подробное описание каждого свойства в конфигурации.
+
+---
+
+## Поддержка файлов конфигурации
+
+Intlayer принимает форматы файлов конфигурации JSON, JS, MJS и TS:
+
+- `intlayer.config.ts`
+- `intlayer.config.js`
+- `intlayer.config.json`
+- `intlayer.config.cjs`
+- `intlayer.config.mjs`
+- `.intlayerrc`
+
+---
+
+## Пример файла конфигурации
+
+```typescript fileName="intlayer.config.ts" codeFormat="typescript"
+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;
+```
+
+```javascript fileName="intlayer.config.cjs" codeFormat="commonjs"
+const { Locales } = require("intlayer");
+
+/** @type {import('intlayer').IntlayerConfig} */
+const config = {
+  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,
+  },
+};
+
+module.exports = config;
+```
+
+```json5 fileName=".intlayerrc" codeFormat="json"
+{
+  "internationalization": {
+    "locales": ["en"],
+  },
+  "content": {
+    "typesDir": "content/types",
+  },
+  "middleware": {
+    "noPrefix": false,
+  },
+}
+```
+
+---
+
+## Справочник по конфигурации
+
+Следующие разделы описывают различные настройки конфигурации, доступные для 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 должны храниться в секрете и не должны быть общедоступными. Убедитесь, что они хранятся в безопасном месте, например, в переменных окружения.
+
+- **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](https://intlayer.org/dashboard/project) с использованием ключа доступа. 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 шаблон.