@intlayer/docs 5.7.2-canary.3 → 5.7.3

package/docs/ru/dictionary/gender.md

@@ -0,0 +1,275 @@
+---
+createdAt: 2025-07-27
+updatedAt: 2025-07-27
+title: Контент на основе пола
+description: Узнайте, как использовать контент на основе пола в Intlayer для динамического отображения содержимого в зависимости от пола. Следуйте этой документации, чтобы эффективно реализовать контент, специфичный для пола, в вашем проекте.
+keywords:
+  - Контент на основе пола
+  - Динамическое отображение
+  - Документация
+  - Intlayer
+  - Next.js
+  - JavaScript
+  - React
+slugs:
+  - doc
+  - concept
+  - content
+  - gender
+---
+
+# Контент на основе пола / Пол в Intlayer
+
+## Как работает пол
+
+В Intlayer контент на основе пола реализуется с помощью функции `gender`, которая сопоставляет конкретные значения пола ('male', 'female') с соответствующим содержимым. Такой подход позволяет динамически выбирать контент в зависимости от указанного пола. При интеграции с React Intlayer или Next Intlayer соответствующий контент автоматически выбирается в соответствии с полом, переданным во время выполнения.
+
+## Настройка контента на основе пола
+
+Чтобы настроить контент на основе пола в вашем проекте Intlayer, создайте модуль контента, который включает определения, специфичные для пола. Ниже приведены примеры в различных форматах.
+
+```typescript fileName="**/*.content.ts" contentDeclarationFormat="typescript"
+import { gender, type Dictionary } from "intlayer";
+
+const myGenderContent = {
+  key: "my_key",
+  content: {
+    myGender: gender({
+      male: "мой контент для мужчин",
+      female: "мой контент для женщин",
+      fallback: "мой контент, когда пол не указан", // Необязательно
+    }),
+  },
+} satisfies Dictionary;
+
+export default myGenderContent;
+```
+
+```javascript fileName="**/*.content.mjs" contentDeclarationFormat="esm"
+import { gender } from "intlayer";
+
+/** @type {import('intlayer').Dictionary} */
+const myGenderContent = {
+  key: "my_key",
+  content: {
+    myGender: gender({
+      male: "мой контент для мужчин",
+      female: "мой контент для женщин",
+      fallback: "мой контент, когда пол не указан", // Необязательно
+    }),
+  },
+};
+
+export default myGenderContent;
+```
+
+```javascript fileName="**/*.content.cjs" contentDeclarationFormat="commonjs"
+const { gender } = require("intlayer");
+
+/** @type {import('intlayer').Dictionary} */
+const myGenderContent = {
+  key: "my_key",
+  content: {
+    myGender: gender({
+      male: "мой контент для мужчин",
+      female: "мой контент для женщин",
+      fallback: "мой контент, когда пол не указан", // Необязательно
+    }),
+  },
+};
+
+module.exports = myGenderContent;
+```
+
+```json5 fileName="**/*.content.json" contentDeclarationFormat="json"
+{
+  "$schema": "https://intlayer.org/schema.json",
+  "key": "my_key",
+  "content": {
+    "myGender": {
+      "nodeType": "gender",
+      "gender": {
+        "male": "мой контент для мужчин",
+        "female": "мой контент для женщин",
+        "fallback": "мой контент, когда пол не указан", // Необязательно
+      },
+    },
+  },
+}
+```
+
+> Если не указан fallback, в качестве fallback будет взят последний объявленный ключ, если пол не указан или не соответствует ни одному из определённых полов.
+
+## Использование контента на основе пола с React Intlayer
+
+Чтобы использовать контент, зависящий от пола, внутри React-компонента, импортируйте и используйте хук `useIntlayer` из пакета `react-intlayer`. Этот хук получает контент по указанному ключу и позволяет передать пол для выбора соответствующего варианта вывода.
+
+```tsx fileName="**/*.tsx" codeFormat="typescript"
+import type { FC } from "react";
+import { useIntlayer } from "react-intlayer";
+
+const GenderComponent: FC = () => {
+  const { myGender } = useIntlayer("my_key");
+
+  return (
+    <div>
+      <p>
+        {
+          /* Вывод: мой контент для мужчин */
+          myGender("male")
+        }
+      </p>
+      <p>
+        {
+          /* Вывод: мой контент для женщин */
+          myGender("female")
+        }
+      </p>
+      <p>
+        {
+          /* Вывод: мой контент для мужчин */
+          myGender("m")
+        }
+      </p>
+      <p>
+        {
+          /* Вывод: мой контент для женщин */
+          myGender("f")
+        }
+      </p>
+      <p>
+        {
+          /* Вывод: мой контент, когда пол не указан */
+          myGender("")
+        }
+      </p>
+      <p>
+        {
+          /* Вывод: мой контент, когда пол не указан */
+          myGender(undefined)
+        }
+      </p>
+    </div>
+  );
+};
+
+export default GenderComponent;
+```
+
+```javascript fileName="**/*.mjx" codeFormat="esm"
+import { useIntlayer } from "react-intlayer";
+
+const GenderComponent = () => {
+  const { myGender } = useIntlayer("my_key");
+
+  return (
+    <div>
+      <p>
+        {
+          /* Вывод: мой контент для мужчин */
+          myGender("male")
+        }
+      </p>
+      <p>
+        {
+          /* Вывод: мой контент для женщин */
+          myGender("female")
+        }
+      </p>
+      <p>
+        {
+          /* Вывод: мой контент для мужчин */
+          myGender("m")
+        }
+      </p>
+      <p>
+        {
+          /* Вывод: мой контент для женщин */
+          myGender("f")
+        }
+      </p>
+      <p>
+        {
+          /* Вывод: мой контент, когда пол не указан */
+          myGender("")
+        }
+      </p>
+      <p>
+        {
+          /* Вывод: мой контент, когда пол не указан */
+          myGender(undefined)
+        }
+      </p>
+    </div>
+  );
+};
+
+export default GenderComponent;
+```
+
+```javascript fileName="**/*.cjs" codeFormat="commonjs"
+const { useIntlayer } = require("react-intlayer");
+
+const GenderComponent = () => {
+  const { myGender } = useIntlayer("my_key");
+
+  return (
+    <div>
+      <p>
+        {
+          /* Вывод: мой контент для мужчин */
+          myGender("male")
+        }
+      </p>
+      <p>
+        {
+          /* Вывод: мой контент для женщин */
+          myGender("female")
+        }
+      </p>
+      <p>
+        {
+          /* Вывод: мой контент для мужчин */
+          myGender("m")
+        }
+      </p>
+      <p>
+        {
+          /* Вывод: мой контент для женщин */
+          myGender("f")
+        }
+      </p>
+      <p>
+        {
+          /* Вывод: мой контент, когда пол не указан */
+          myGender("")
+        }
+      </p>
+      <p>
+        {
+          /* Вывод: мой контент, когда пол не указан */
+          myGender(undefined)
+        }
+      </p>
+    </div>
+  );
+};
+
+module.exports = GenderComponent;
+```
+
+## Дополнительные ресурсы
+
+Для получения более подробной информации о настройке и использовании обратитесь к следующим ресурсам:
+
+- [Документация Intlayer CLI](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ru/intlayer_cli.md)
+- [Документация React Intlayer](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ru/intlayer_with_create_react_app.md)
+- [Документация Next Intlayer](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ru/intlayer_with_nextjs_15.md)
+
+Эти ресурсы предлагают дополнительные сведения о настройке и использовании Intlayer в различных средах и фреймворках.
+
+## История документации
+
+| Версия | Дата       | Изменения                              |
+| ------ | ---------- | -------------------------------------- |
+| 5.7.2  | 2025-07-27 | Введение контента, основанного на поле |

package/docs/ru/how_works_intlayer.md

@@ -93,7 +93,7 @@ Intlayer также предоставляет визуальный редакт
 
 - Сервер — это простое приложение на Express, которое прослушивает запросы от клиента и получает контент вашего приложения, такой как `dictionaries` и конфигурация, чтобы сделать его доступным на стороне клиента.
 - С другой стороны, клиент — это приложение на React, которое используется для взаимодействия с вашим контентом через визуальный интерфейс.
-  Когда вы вызываете ваш контент с помощью `useIntlayer` и редактор включен, строки автоматически оборачиваются в объект Proxy с именем `IntlayerNode`. Этот узел использует `window.sendMessage` для связи с обернутым iframe, содержащим интерфейс визуального редактора.  
+  Когда вы вызываете ваш контент с помощью `useIntlayer` и редактор включен, строки автоматически оборачиваются в объект Proxy с именем `IntlayerNode`. Этот узел использует `window.postMessage` для связи с обернутым iframe, содержащим интерфейс визуального редактора.  
   Со стороны редактора, редактор прослушивает эти сообщения и имитирует реальное взаимодействие с вашим контентом, позволяя редактировать текст напрямую в контексте вашего приложения.
 
 ## Оптимизация сборки приложения

package/docs/ru/locale_mapper.md

@@ -0,0 +1,244 @@
+---
+createdAt: 2025-07-27
+updatedAt: 2025-07-27
+title: Отображатель локалей
+description: Узнайте, как работает Отображатель локалей. Посмотрите шаги, которые использует Отображатель локалей в вашем приложении. Узнайте, что делают разные пакеты.
+keywords:
+  - Отображатель локалей
+  - Начало работы
+  - Intlayer
+  - Приложение
+  - Пакеты
+slugs:
+  - doc
+  - locale-mapper
+---
+
+# Отображатель локалей
+
+Отображатель локалей — это мощный инструмент, который помогает работать с данными интернационализации в вашем приложении Intlayer. Он предоставляет три основные функции для преобразования и организации данных, специфичных для локали: `localeMap`, `localeFlatMap` и `localeRecord`.
+
+## Как работает Отображатель локалей
+
+Отображатель локалей работает с объектом `LocaleData`, который содержит всю необходимую информацию о локали:
+
+```typescript
+type LocaleData = {
+  locale: LocalesValues; // Текущий код локали (например, 'en', 'fr')
+  defaultLocale: LocalesValues; // Код локали по умолчанию
+  isDefault: boolean; // Является ли эта локаль локалью по умолчанию
+  locales: LocalesValues[]; // Массив всех доступных локалей
+  urlPrefix: string; // Префикс URL для этой локали (например, '/fr' или '')
+};
+```
+
+Функции отображателя автоматически генерируют эти данные для каждой локали в вашей конфигурации, учитывая:
+
+- Ваш список настроенных локалей
+- Настройку локали по умолчанию
+- Нужно ли добавлять префикс для локали по умолчанию в URL
+
+## Основные функции
+
+### `localeMap`
+
+Преобразует каждую локаль в один объект с помощью функции отображения.
+
+```typescript
+localeMap<T>(
+  mapper: (locale: LocaleData) => T,
+  locales?: LocalesValues[],
+  defaultLocale?: LocalesValues,
+  prefixDefault?: boolean
+): T[]
+```
+
+**Пример: Создание объектов маршрутов**
+
+```typescript
+import { localeMap } from "intlayer";
+
+const routes = localeMap((localizedData) => ({
+  path: localizedData.urlPrefix,
+  name: localizedData.locale,
+  isDefault: localizedData.isDefault,
+  locales: localizedData.locales,
+  defaultLocale: localizedData.defaultLocale,
+}));
+
+// Результат:
+// [
+//   { path: '/', name: 'en', isDefault: true, locales: ['en', 'fr', 'es'], defaultLocale: 'en' },
+//   { path: '/fr', name: 'fr', isDefault: false, locales: ['en', 'fr', 'es'], defaultLocale: 'en' },
+//   { path: '/es', name: 'es', isDefault: false, locales: ['en', 'fr', 'es'], defaultLocale: 'en' }
+// ]
+```
+
+### `localeFlatMap`
+
+Похож на `localeMap`, но функция преобразования возвращает массив объектов, который затем объединяется в один плоский массив.
+
+```typescript
+localeFlatMap<T>(
+  mapper: (locale: LocaleData) => T[],
+  locales?: LocalesValues[],
+  defaultLocale?: LocalesValues,
+  prefixDefault?: boolean
+): T[]
+```
+
+**Пример: Создание нескольких маршрутов для каждой локали**
+
+```typescript
+import { localeFlatMap } from "intlayer";
+
+const routes = localeFlatMap((localizedData) => [
+  {
+    path: localizedData.urlPrefix,
+    name: localizedData.locale,
+    isDefault: localizedData.isDefault,
+  },
+  {
+    path: `${localizedData.urlPrefix}/about`,
+    name: `${localizedData.locale}-about`,
+    isDefault: localizedData.isDefault,
+  },
+]);
+
+// Результат:
+// [
+//   { path: '/', name: 'en', isDefault: true },
+//   { path: '/about', name: 'en-about', isDefault: true },
+//   { path: '/fr', name: 'fr', isDefault: false },
+//   { path: '/fr/about', name: 'fr-about', isDefault: false },
+//   { path: '/es', name: 'es', isDefault: false },
+//   { path: '/es/about', name: 'es-about', isDefault: false }
+// ]
+```
+
+### `localeRecord`
+
+Создаёт объект-запись, где каждая локаль является ключом, отображающимся на значение, преобразованное функцией mapper.
+
+```typescript
+localeRecord<T>(
+  mapper: (locale: LocaleData) => T,
+  locales?: Locales[],
+  defaultLocale?: Locales,
+  prefixDefault?: boolean
+): Record<Locales, T>
+```
+
+**Пример: Загрузка файлов переводов**
+
+```typescript
+import { localeRecord } from "intlayer";
+
+const translations = localeRecord(({ locale }) =>
+  require(`./translations/${locale}.json`)
+);
+
+// Результат:
+// {
+//   en: { welcome: 'Welcome', hello: 'Hello' },
+//   fr: { welcome: 'Bienvenue', hello: 'Bonjour' },
+//   es: { welcome: 'Bienvenido', hello: 'Hola' }
+// }
+```
+
+## Настройка Locale Mapper
+
+Locale Mapper автоматически использует вашу конфигурацию Intlayer, но вы можете переопределить значения по умолчанию, передав параметры:
+
+### Использование конфигурации по умолчанию
+
+```typescript
+import { localeMap } from "intlayer";
+
+// Использует конфигурацию из intlayer.config.ts
+const routes = localeMap((data) => ({
+  path: data.urlPrefix,
+  locale: data.locale,
+}));
+```
+
+### Переопределение конфигурации
+
+```typescript
+import { localeMap } from "intlayer";
+
+// Переопределение локалей и локали по умолчанию
+const customRoutes = localeMap(
+  (data) => ({ path: data.urlPrefix, locale: data.locale }),
+  //  ["en", "fr", "de"], // Пользовательские локали
+  "en", // Пользовательская локаль по умолчанию
+  true // Добавлять префикс локали по умолчанию в URL
+);
+```
+
+## Расширенные примеры использования
+
+### Создание навигационных меню
+
+```typescript
+import { localeMap } from "intlayer";
+
+const navigationItems = localeMap((data) => ({
+  label: data.locale.toUpperCase(),
+  href: data.urlPrefix || "/",
+  isActive: data.isDefault,
+  flag: `/flags/${data.locale}.svg`, // путь к изображению флага
+}));
+```
+
+### Генерация данных для Sitemap
+
+```typescript
+import { localeFlatMap } from "intlayer";
+
+const sitemapUrls = localeFlatMap((data) => [
+  {
+    url: `${data.urlPrefix}/`,
+    lastmod: new Date().toISOString(),
+    changefreq: "daily",
+    priority: data.isDefault ? 1.0 : 0.8,
+  },
+  {
+    url: `${data.urlPrefix}/about`,
+    lastmod: new Date().toISOString(),
+    changefreq: "monthly",
+    priority: data.isDefault ? 0.8 : 0.6,
+  },
+]);
+```
+
+### Динамическая загрузка переводов
+
+```typescript
+import { localeRecord } from "intlayer";
+
+const translationModules = localeRecord(({ locale }) => ({
+  messages: import(`./locales/${locale}/messages.json`), // импорт сообщений перевода
+  validation: import(`./locales/${locale}/validation.json`), // импорт правил валидации
+  metadata: {
+    locale,
+    direction: ["ar", "he", "fa"].includes(locale) ? "rtl" : "ltr", // направление текста: справа налево для арабского, иврита, фарси
+  },
+}));
+```
+
+## Интеграция с конфигурацией
+
+Locale Mapper бесшовно интегрируется с вашей конфигурацией Intlayer:
+
+- **Локали**: Автоматически использует `configuration.internationalization.locales`
+- **Локаль по умолчанию**: Использует `configuration.internationalization.defaultLocale`
+- **Префикс URL**: Учитывает `configuration.middleware.prefixDefault`
+
+Это обеспечивает согласованность во всем вашем приложении и уменьшает дублирование конфигурации.
+
+## История документации
+
+| Версия | Дата       | Изменения                               |
+| ------ | ---------- | --------------------------------------- |
+| 5.7.2  | 2025-07-27 | Добавлена документация по locale mapper |