@intlayer/docs 5.5.8

package/ru/packages/react-intlayer/useIntlayer.md

@@ -0,0 +1,225 @@
+# React Интеграция: Документация по хуку `useIntlayer`
+
+Этот раздел предоставляет подробное руководство по использованию хука `useIntlayer` в React-приложениях, позволяя эффективно локализовать контент.
+
+## Импортирование `useIntlayer` в React
+
+Хук `useIntlayer` можно интегрировать в React-приложения, импортируя его в зависимости от контекста:
+
+- **Клиентский компонент:**
+
+  ```typescript codeFormat="typescript"
+  import { useIntlayer } from "react-intlayer"; // Используется в клиентских React-компонентах
+  ```
+
+  ```javascript codeFormat="esm"
+  import { useIntlayer } from "react-intlayer"; // Используется в клиентских React-компонентах
+  ```
+
+  ```javascript codeFormat="commonjs"
+  const { useIntlayer } = require("react-intlayer"); // Используется в клиентских React-компонентах
+  ```
+
+- **Серверный компонент:**
+
+  ```typescript codeFormat="commonjs"
+  import { useIntlayer } from "react-intlayer/server"; // Используется в серверных React-компонентах
+  ```
+
+  ```javascript codeFormat="esm"
+  import { useIntlayer } from "react-intlayer/server"; // Используется в серверных React-компонентах
+  ```
+
+  ```javascript codeFormat="commonjs"
+  const { useIntlayer } = require("react-intlayer/server"); // Используется в серверных React-компонентах
+  ```
+
+## Параметры
+
+Хук принимает два параметра:
+
+1. **`key`**: Ключ словаря для получения локализованного контента.
+2. **`locale`** (необязательно): Желаемая локаль. По умолчанию используется локаль из контекста, если не указано.
+
+## Словарь
+
+Все ключи словаря должны быть объявлены в файлах декларации контента для повышения безопасности типов и предотвращения ошибок. Инструкции по настройке можно найти [здесь](https://github.com/aymericzip/intlayer/blob/main/docs/ru/dictionary/get_started.md).
+
+## Пример использования в React
+
+Демонстрация использования хука `useIntlayer` в React-компоненте:
+
+```tsx fileName="src/app.tsx" codeFormat="typescript"
+import type { FC } from "react";
+import { ClientComponentExample, ServerComponentExample } from "@components";
+import { IntlayerProvider } from "react-intlayer";
+import { useIntlayer, IntlayerServerProvider } from "react-intlayer/server";
+import { Locales } from "intlayer";
+
+const App: FC<{ locale: Locales }> = ({ locale }) => {
+  const content = useIntlayer("homepage", locale);
+
+  return (
+    <>
+      <p>{content.introduction}</p>
+      <IntlayerProvider locale={locale}>
+        <ClientComponentExample />
+      </IntlayerProvider>
+      <IntlayerServerProvider locale={locale}>
+        <ServerComponentExample />
+      </IntlayerServerProvider>
+    </>
+  );
+};
+```
+
+```jsx fileName="src/app.mjx" codeFormat="esm"
+import { ClientComponentExample, ServerComponentExample } from "@components";
+import { IntlayerProvider } from "react-intlayer";
+import { IntlayerServerProvider, useIntlayer } from "react-intlayer/server";
+
+const App = ({ locale }) => {
+  const content = useIntlayer("homepage", locale);
+
+  return (
+    <>
+      <p>{content.introduction}</p>
+      <IntlayerProvider locale={locale}>
+        <ClientComponentExample />
+      </IntlayerProvider>
+      <IntlayerServerProvider locale={locale}>
+        <ServerComponentExample />
+      </IntlayerServerProvider>
+    </>
+  );
+};
+```
+
+```jsx fileName="src/app.csx" codeFormat="commonjs"
+const { IntlayerProvider } = require("react-intlayer");
+const {
+  IntlayerServerProvider,
+  useIntlayer,
+} = require("react-intlayer/server");
+
+const App = ({ locale }) => {
+  const content = useIntlayer("homepage", locale);
+
+  return (
+    <>
+      <p>{content.introduction}</p>
+      <IntlayerProvider locale={locale}>
+        <ClientComponentExample />
+      </IntlayerProvider>
+      <IntlayerServerProvider locale={locale}>
+        <ServerComponentExample />
+      </IntlayerServerProvider>
+    </>
+  );
+};
+```
+
+```tsx fileName="src/components/ComponentExample.tsx" codeFormat="typescript"
+import type { FC } from "react";
+import { useIntlayer } from "react-intlayer";
+
+const ComponentExample: FC = () => {
+  const content = useIntlayer("component-example");
+
+  return (
+    <div>
+      <h1>{content.title}</h1>
+      <p>{content.description}</p>
+    </div>
+  );
+};
+```
+
+```jsx fileName="src/components/ComponentExample.mjx" codeFormat="esm"
+import { useIntlayer } from "react-intlayer";
+
+const ComponentExample = () => {
+  const content = useIntlayer("component-example");
+
+  return (
+    <div>
+      <h1>{content.title}</h1>
+      <p>{content.description}</p>
+    </div>
+  );
+};
+```
+
+```jsx fileName="src/components/ComponentExample.csx" codeFormat="commonjs"
+const { useIntlayer } = require("react-intlayer");
+
+const ComponentExample = () => {
+  const content = useIntlayer("component-example");
+
+  return (
+    <div>
+      <h1>{content.title}</h1>
+      <p>{content.description}</p>
+    </div>
+  );
+};
+```
+
+```tsx fileName="src/components/ServerComponentExample.tsx" codeFormat="typescript"
+import { useIntlayer } from "react-intlayer/server";
+
+const ServerComponentExample = () => {
+  const content = useIntlayer("server-component");
+
+  return (
+    <div>
+      <h1>{content.title}</h1>
+      <p>{content.description}</p>
+    </div>
+  );
+};
+```
+
+```jsx fileName="src/components/ServerComponentExample.mjx" codeFormat="esm"
+import { useIntlayer } from "react-intlayer/server";
+
+const ServerComponentExample = () => {
+  const content = useIntlayer("server-component");
+
+  return (
+    <div>
+      <h1>{content.title}</h1>
+      <p>{content.description}</p>
+    </div>
+  );
+};
+```
+
+```jsx fileName="src/components/ServerComponentExample.csx" codeFormat="commonjs"
+const { useIntlayer } = require("react-intlayer/server");
+
+const ServerComponentExample = () => {
+  const content = useIntlayer("server-component");
+
+  return (
+    <div>
+      <h1>{content.title}</h1>
+      <p>{content.description}</p>
+    </div>
+  );
+};
+```
+
+## Работа с атрибутами
+
+При локализации атрибутов корректно обращайтесь к значениям контента:
+
+```jsx
+<button title={content.buttonTitle.value}>{content.buttonText}</button>
+```
+
+## Дополнительные ресурсы
+
+- **Визуальный редактор Intlayer**: Для более интуитивного управления контентом обратитесь к документации по визуальному редактору [здесь](https://github.com/aymericzip/intlayer/blob/main/docs/ru/intlayer_visual_editor.md).
+
+Этот раздел специально ориентирован на интеграцию хука `useIntlayer` в React-приложениях, упрощая процесс локализации и обеспечивая согласованность контента для разных локалей.

package/ru/packages/react-intlayer/useIntlayerAsync.md

@@ -0,0 +1,226 @@
+# React Интеграция: Документация хука `useIntlayerAsync`
+
+Хук `useIntlayerAsync` расширяет функциональность `useIntlayer`, возвращая не только предварительно отрендеренные словари, но и асинхронно загружая обновления, что делает его идеальным для приложений, которые часто обновляют локализованный контент после первоначального рендера.
+
+## Обзор
+
+- **Асинхронная загрузка словарей:**  
+  При первом монтировании `useIntlayerAsync` сначала возвращает предварительно загруженный или статически встроенный словарь локали (как это делает `useIntlayer`), а затем асинхронно загружает и объединяет любые новые доступные удаленные словари.
+- **Управление состоянием загрузки:**  
+  Хук также предоставляет состояние `isLoading`, указывающее, когда загружается удаленный словарь. Это позволяет разработчикам отображать индикаторы загрузки или скелетон-элементы для более плавного пользовательского опыта.
+
+## Настройка окружения
+
+Intlayer предоставляет безголовую систему управления источниками контента (CSM), которая позволяет пользователям без навыков программирования управлять и обновлять контент приложения. Используя интуитивно понятную панель управления Intlayer, ваша команда может редактировать локализованный текст, изображения и другие ресурсы без прямого изменения кода. Это упрощает процесс управления контентом, способствует сотрудничеству и обеспечивает быстрые и легкие обновления.
+
+Чтобы начать работу с Intlayer:
+
+1. **Зарегистрируйтесь и получите токен доступа** на [https://intlayer.org/dashboard](https://intlayer.org/dashboard).
+2. **Добавьте учетные данные в файл конфигурации:**  
+   В вашем React-проекте настройте клиент Intlayer с вашими учетными данными:
+
+   ```typescript fileName="intlayer.config.ts" codeFormat="typescript"
+   import type { IntlayerConfig } from "intlayer";
+
+   export default {
+     // ...
+     editor: {
+       clientId: process.env.INTLAYER_CLIENT_ID,
+       clientSecret: process.env.INTLAYER_CLIENT_SECRET,
+     },
+   } satisfies IntlayerConfig;
+   ```
+
+   ```javascript fileName="intlayer.config.mjs" codeFormat="esm"
+   import { type IntlayerConfig } from "intlayer";
+
+   /** @type {import('intlayer').IntlayerConfig} */
+   const config = {
+     // ...
+     editor: {
+       clientId: process.env.INTLAYER_CLIENT_ID,
+       clientSecret: process.env.INTLAYER_CLIENT_SECRET,
+     },
+   };
+
+   export default config;
+   ```
+
+   ```javascript fileName="intlayer.config.cjs" codeFormat="commonjs"
+   /** @type {import('intlayer').IntlayerConfig} */
+   const config = {
+     // ...
+     editor: {
+       clientId: process.env.INTLAYER_CLIENT_ID,
+       clientSecret: process.env.INTLAYER_CLIENT_SECRET,
+     },
+   };
+
+   module.exports = config;
+   ```
+
+3. **Загрузите новый словарь локали в Intlayer:**
+
+   ```bash
+   npx intlayer dictionary push -d my-first-dictionary-key
+   ```
+
+   Эта команда загружает ваши начальные словари контента, делая их доступными для асинхронной загрузки и редактирования через платформу Intlayer.
+
+## Импорт `useIntlayerAsync` в React
+
+В ваших React-компонентах импортируйте `useIntlayerAsync`:
+
+```ts codeFormat="typescript"
+import { useIntlayerAsync } from "react-intlayer";
+```
+
+```js codeFormat="esm"
+import { useIntlayerAsync } from "react-intlayer";
+```
+
+```js codeFormat="commonjs"
+const { useIntlayerAsync } = require("react-intlayer");
+```
+
+## Параметры
+
+1. **`key`**:  
+   **Тип**: `DictionaryKeys`  
+   Ключ словаря, используемый для идентификации блока локализованного контента. Этот ключ должен быть определен в ваших файлах декларации контента.
+
+2. **`locale`** (опционально):  
+   **Тип**: `Locales`  
+   Конкретная локаль, которую вы хотите использовать. Если параметр не указан, хук использует локаль из текущего контекста Intlayer.
+
+3. **`isRenderEditor`** (опционально, по умолчанию `true`):  
+   **Тип**: `boolean`  
+   Определяет, должен ли контент быть готовым для рендера с наложением редактора Intlayer. Если установлено в `false`, возвращаемые данные словаря будут исключать функции, специфичные для редактора.
+
+## Возвращаемое значение
+
+Хук возвращает объект словаря, содержащий локализованный контент, связанный с `key` и `locale`. Также он включает булево значение `isLoading`, указывающее, загружается ли в данный момент удаленный словарь.
+
+## Пример использования в React-компоненте
+
+```tsx fileName="src/components/ComponentExample.tsx" codeFormat="typescript"
+import { useEffect, type FC } from "react";
+import { useIntlayerAsync } from "react-intlayer";
+
+export const ComponentExample: FC = () => {
+  const { title, description, isLoading } = useIntlayerAsync("async-component");
+
+  useEffect(() => {
+    if (isLoading) {
+      console.log("Контент загружается...");
+    }
+  }, [isLoading]);
+
+  return (
+    <div>
+      {isLoading ? (
+        <div>
+          <h1>Загрузка…</h1>
+          <p>Пожалуйста, подождите, пока контент обновляется.</p>
+        </div>
+      ) : (
+        <div>
+          <h1>{title.value}</h1>
+          <p>{description.value}</p>
+        </div>
+      )}
+    </div>
+  );
+};
+```
+
+```jsx fileName="src/components/ComponentExample.mjx" codeFormat="esm"
+import { useEffect } from "react";
+import { useIntlayerAsync } from "react-intlayer";
+
+const ComponentExample = () => {
+  const { title, description, isLoading } = useIntlayerAsync("async-component");
+
+  useEffect(() => {
+    if (isLoading) {
+      console.log("Контент загружается...");
+    }
+  }, [isLoading]);
+
+  return (
+    <div>
+      {isLoading ? (
+        <div>
+          <h1>Загрузка…</h1>
+          <p>Пожалуйста, подождите, пока контент обновляется.</p>
+        </div>
+      ) : (
+        <div>
+          <h1>{title.value}</h1>
+          <p>{description.value}</p>
+        </div>
+      )}
+    </div>
+  );
+};
+```
+
+```jsx fileName="src/components/ComponentExample.csx" codeFormat="commonjs"
+const { useEffect } = require("react");
+const { useIntlayerAsync } = require("react-intlayer");
+
+const ComponentExample = () => {
+  const { title, description, isLoading } = useIntlayerAsync("async-component");
+
+  useEffect(() => {
+    if (isLoading) {
+      console.log("Контент загружается...");
+    }
+  }, [isLoading]);
+
+  return (
+    <div>
+      {isLoading ? (
+        <div>
+          <h1>Загрузка…</h1>
+          <p>Пожалуйста, подождите, пока контент обновляется.</p>
+        </div>
+      ) : (
+        <div>
+          <h1>{title.value}</h1>
+          <p>{description.value}</p>
+        </div>
+      )}
+    </div>
+  );
+};
+```
+
+**Ключевые моменты:**
+
+- При первоначальном рендере `title` и `description` берутся из предварительно загруженного или статически встроенного словаря локали.
+- Пока `isLoading` равно `true`, в фоновом режиме выполняется запрос на получение обновленного словаря.
+- После завершения загрузки `title` и `description` обновляются с учетом нового контента, а `isLoading` возвращается в `false`.
+
+## Работа с локализацией атрибутов
+
+Вы также можете получить локализованные значения атрибутов для различных HTML-свойств (например, `alt`, `title`, `aria-label`):
+
+```jsx
+<img src={title.image.src.value} alt={title.image.alt.value} />
+```
+
+## Файлы словарей
+
+Все ключи контента должны быть определены в ваших файлах декларации контента для обеспечения безопасности типов и предотвращения ошибок во время выполнения. Эти файлы позволяют использовать проверку TypeScript, гарантируя, что вы всегда ссылаетесь на существующие ключи и локали.
+
+Инструкции по настройке файлов декларации контента доступны [здесь](https://github.com/aymericzip/intlayer/blob/main/docs/ru/dictionary/get_started.md).
+
+## Дополнительная информация
+
+- **Визуальный редактор Intlayer:**  
+  Интеграция с визуальным редактором Intlayer для управления и редактирования контента напрямую из пользовательского интерфейса. Подробнее [здесь](https://github.com/aymericzip/intlayer/blob/main/docs/ru/intlayer_visual_editor.md).
+
+---
+
+**В заключение**, `useIntlayerAsync` , это мощный хук React, предназначенный для улучшения пользовательского опыта и поддержания актуальности контента путем объединения предварительно отрендеренных или предварительно загруженных словарей с асинхронными обновлениями словарей. Используя `isLoading` и декларации контента на основе TypeScript, вы можете легко интегрировать динамический локализованный контент в свои React-приложения.

package/ru/packages/react-intlayer/useLocale.md

@@ -0,0 +1,184 @@
+# React Интеграция: Документация по хуку `useLocale`
+
+Этот раздел предоставляет подробную информацию о хуке `useLocale` из библиотеки `react-intlayer`, предназначенном для управления локалями в React-приложениях.
+
+## Импортирование `useLocale` в React
+
+Чтобы интегрировать хук `useLocale` в ваше React-приложение, импортируйте его из соответствующего пакета:
+
+```typescript codeFormat="typescript"
+import { useLocale } from "react-intlayer"; // Используется в React-компонентах для управления локалями
+```
+
+```javascript codeFormat="esm"
+import { useLocale } from "react-intlayer"; // Используется в React-компонентах для управления локалями
+```
+
+```javascript codeFormat="commonjs"
+const { useLocale } = require("react-intlayer"); // Используется в React-компонентах для управления локалями
+```
+
+## Обзор
+
+Хук `useLocale` предлагает простой способ доступа и управления настройками локали внутри React-компонентов. Он предоставляет доступ к текущей локали, локали по умолчанию, всем доступным локалям и функциям для обновления настроек локали.
+
+## Использование
+
+Вот как можно использовать хук `useLocale` внутри React-компонента:
+
+```tsx fileName="src/components/LocaleSwitcher.tsx" codeFormat="typescript"
+import type { FC } from "react";
+import { useLocale } from "react-intlayer";
+
+const LocaleSwitcher: FC = () => {
+  const { locale, defaultLocale, availableLocales, setLocale } = useLocale();
+
+  return (
+    <div>
+      <h1>Текущая локаль: {locale}</h1>
+      <p>Локаль по умолчанию: {defaultLocale}</p>
+      <select value={locale} onChange={(e) => setLocale(e.target.value)}>
+        {availableLocales.map((loc) => (
+          <option key={loc} value={loc}>
+            {loc}
+          </option>
+        ))}
+      </select>
+    </div>
+  );
+};
+
+export default LocaleSwitcher;
+```
+
+```jsx fileName="src/components/LocaleSwitcher.mjx" codeFormat="esm"
+import { useLocale } from "react-intlayer";
+
+const LocaleSwitcher = () => {
+  const { locale, defaultLocale, availableLocales, setLocale } = useLocale();
+
+  return (
+    <div>
+      <h1>Текущая локаль: {locale}</h1>
+      <p>Локаль по умолчанию: {defaultLocale}</p>
+      <select value={locale} onChange={(e) => setLocale(e.target.value)}>
+        {availableLocales.map((loc) => (
+          <option key={loc} value={loc}>
+            {loc}
+          </option>
+        ))}
+      </select>
+    </div>
+  );
+};
+
+export default LocaleSwitcher;
+```
+
+```jsx fileName="src/components/LocaleSwitcher.csx" codeFormat="commonjs"
+const { useLocale } = require("react-intlayer");
+
+const LocaleSwitcher = () => {
+  const { locale, defaultLocale, availableLocales, setLocale } = useLocale();
+
+  return (
+    <div>
+      <h1>Текущая локаль: {locale}</h1>
+      <p>Локаль по умолчанию: {defaultLocale}</p>
+      <select value={locale} onChange={(e) => setLocale(e.target.value)}>
+        {availableLocales.map((loc) => (
+          <option key={loc} value={loc}>
+            {loc}
+          </option>
+        ))}
+      </select>
+    </div>
+  );
+};
+
+export default LocaleSwitcher;
+```
+
+## Параметры и возвращаемые значения
+
+Когда вы вызываете хук `useLocale`, он возвращает объект, содержащий следующие свойства:
+
+- **`locale`**: Текущая локаль, установленная в контексте React.
+- **`defaultLocale`**: Основная локаль, определенная в конфигурации.
+- **`availableLocales`**: Список всех доступных локалей, определенных в конфигурации.
+- **`setLocale`**: Функция для обновления текущей локали в контексте приложения.
+
+## Пример
+
+Этот пример показывает компонент, который использует хук `useLocale` для отображения переключателя локалей, позволяя пользователям динамически изменять локаль приложения:
+
+```tsx fileName="src/components/LocaleSelector.tsx" codeFormat="typescript"
+import type { FC } from "react";
+import { useLocale } from "react-intlayer";
+
+const LocaleSelector: FC = () => {
+  const { locale, setLocale, availableLocales } = useLocale();
+
+  const handleLocaleChange = (newLocale) => {
+    setLocale(newLocale);
+  };
+
+  return (
+    <select value={locale} onChange={(e) => handleLocaleChange(e.target.value)}>
+      {availableLocales.map((locale) => (
+        <option key={locale} value={locale}>
+          {locale}
+        </option>
+      ))}
+    </select>
+  );
+};
+```
+
+```jsx fileName="src/components/LocaleSelector.mjx" codeFormat="esm"
+import { useLocale } from "react-intlayer";
+
+const LocaleSelector = () => {
+  const { locale, setLocale, availableLocales } = useLocale();
+
+  const handleLocaleChange = (newLocale) => {
+    setLocale(newLocale);
+  };
+
+  return (
+    <select value={locale} onChange={(e) => handleLocaleChange(e.target.value)}>
+      {availableLocales.map((locale) => (
+        <option key={locale} value={locale}>
+          {locale}
+        </option>
+      ))}
+    </select>
+  );
+};
+```
+
+```jsx fileName="src/components/LocaleSelector.csx" codeFormat="commonjs"
+const { useLocale } = require("react-intlayer");
+
+const LocaleSelector = () => {
+  const { locale, setLocale, availableLocales } = useLocale();
+
+  const handleLocaleChange = (newLocale) => {
+    setLocale(newLocale);
+  };
+
+  return (
+    <select value={locale} onChange={(e) => handleLocaleChange(e.target.value)}>
+      {availableLocales.map((locale) => (
+        <option key={locale} value={locale}>
+          {locale}
+        </option>
+      ))}
+    </select>
+  );
+};
+```
+
+## Заключение
+
+Хук `useLocale` из `react-intlayer` является важным инструментом для управления локалями в ваших React-приложениях, предоставляя функциональность, необходимую для эффективной адаптации вашего приложения к различным международным аудиториям.