@intlayer/docs 5.5.8

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

@@ -0,0 +1,211 @@
+# Next.js Интеграция: Документация по хуку `useIntlayerAsync`
+
+Хук `useIntlayerAsync` расширяет функциональность `useIntlayer`, возвращая не только предварительно отрендеренные словари, но и асинхронно загружая обновления, что делает его идеальным для приложений, которые часто обновляют локализованный контент после начального рендера.
+
+## Обзор
+
+- **Асинхронная загрузка словарей:**  
+  На стороне клиента `useIntlayerAsync` сначала возвращает предварительно отрендеренный словарь локали (так же, как `useIntlayer`), а затем асинхронно загружает и объединяет любые новые удаленные словари.
+- **Управление состоянием прогресса:**  
+  Хук также предоставляет состояние `isLoading`, указывающее, когда загружается удаленный словарь. Это позволяет разработчикам отображать индикаторы загрузки или скелетон-элементы для более плавного пользовательского опыта.
+
+## Настройка окружения
+
+Intlayer предоставляет безголовую систему управления источниками контента (CSM), которая позволяет пользователям без технических навыков управлять и обновлять контент приложения. Используя интуитивно понятную панель управления Intlayer, ваша команда может редактировать локализованный текст, изображения и другие ресурсы без прямого изменения кода. Это упрощает процесс управления контентом, способствует сотрудничеству и обеспечивает возможность быстрого и легкого внесения изменений.
+
+Чтобы начать работу с Intlayer, сначала зарегистрируйтесь и получите токен доступа на [https://intlayer.org/dashboard](https://intlayer.org/dashboard). После получения учетных данных добавьте их в файл конфигурации, как показано ниже:
+
+```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;
+```
+
+После настройки учетных данных вы можете загрузить новый словарь локали в Intlayer, выполнив:
+
+```bash
+npx intlayer dictionary push -d my-first-dictionary-key
+```
+
+Эта команда загружает ваши начальные словари контента, делая их доступными для асинхронной загрузки и редактирования через платформу Intlayer.
+
+## Импорт `useIntlayerAsync` в Next.js
+
+Поскольку `useIntlayerAsync` предназначен для **клиентских** компонентов, импортируйте его из той же точки входа клиента, что и `useIntlayer`:
+
+```tsx codeFormat="typescript"
+"use client";
+
+import { useIntlayerAsync } from "next-intlayer";
+```
+
+```javascript codeFormat="esm"
+"use client";
+
+import { useIntlayerAsync } from "next-intlayer";
+```
+
+```javascript codeFormat="commonjs"
+"use client";
+
+const { useIntlayerAsync } = require("next-intlayer");
+```
+
+Убедитесь, что файл, в который вы импортируете, аннотирован `"use client"` в начале, если вы используете App Router Next.js с разделением серверных и клиентских компонентов.
+
+## Параметры
+
+1. **`key`**:  
+   **Тип**: `DictionaryKeys`  
+   Ключ словаря, используемый для идентификации блока локализованного контента. Этот ключ должен быть определен в ваших файлах декларации контента.
+
+2. **`locale`** (опционально):  
+   **Тип**: `Locales`  
+   Конкретная локаль, которую вы хотите использовать. Если параметр не указан, хук использует локаль из клиентского контекста.
+
+3. **`isRenderEditor`** (опционально, по умолчанию `true`):  
+   **Тип**: `boolean`  
+   Определяет, должен ли контент быть готовым для рендеринга с наложением редактора Intlayer. Если установлено в `false`, возвращаемые данные словаря будут исключать функции, специфичные для редактора.
+
+## Возвращаемое значение
+
+Хук возвращает объект словаря, содержащий локализованный контент, связанный с `key` и `locale`. Также он включает булево значение `isLoading`, указывающее, загружается ли в данный момент удаленный словарь.
+
+## Пример использования в Next.js
+
+### Пример клиентского компонента
+
+```tsx fileName="src/components/AsyncClientComponentExample.tsx" codeFormat="typescript"
+"use client";
+
+import { useEffect, type FC } from "react";
+import { useIntlayerAsync } from "next-intlayer";
+
+export const AsyncClientComponentExample: FC = () => {
+  const { title, description, isLoading } = useIntlayerAsync("async-component");
+
+  useEffect(() => {
+    if (isLoading) {
+      console.log("Контент загружается...");
+    }
+  }, [isLoading]);
+
+  return (
+    <div>
+      <h1>{title.value}</h1>
+      <p>{description.value}</p>
+    </div>
+  );
+};
+```
+
+```jsx fileName="src/components/AsyncClientComponentExample.mjx" codeFormat="esm"
+"use client";
+
+import { useEffect } from "react";
+import { useIntlayerAsync } from "next-intlayer";
+
+const AsyncClientComponentExample = () => {
+  const { title, description, isLoading } = useIntlayerAsync("async-component");
+
+  useEffect(() => {
+    if (isLoading) {
+      console.log("Контент загружается...");
+    }
+  }, [isLoading]);
+
+  return (
+    <div>
+      <h1>{title.value}</h1>
+      <p>{description.value}</p>
+    </div>
+  );
+};
+```
+
+```jsx fileName="src/components/AsyncClientComponentExample.csx" codeFormat="commonjs"
+"use client";
+
+const { useEffect } = require("react");
+const { useIntlayerAsync } = require("next-intlayer");
+
+const AsyncClientComponentExample = () => {
+  const { title, description, isLoading } = useIntlayerAsync("async-component");
+
+  useEffect(() => {
+    if (isLoading) {
+      console.log("Контент загружается...");
+    }
+  }, [isLoading]);
+
+  return (
+    <div>
+      <h1>{title.value}</h1>
+      <p>{description.value}</p>
+    </div>
+  );
+};
+```
+
+**Ключевые моменты:**
+
+- При первом рендере `title` и `description` берутся из предварительно отрендеренного словаря локали.
+- Пока `isLoading` равно `true`, в фоновом режиме выполняется удаленный запрос для загрузки обновленного словаря.
+- После завершения загрузки `title` и `description` обновляются с учетом нового контента, а `isLoading` возвращается в `false`.
+
+## Локализация атрибутов
+
+Как и с `useIntlayer`, вы можете получить локализованные значения атрибутов для различных HTML-свойств (например, `alt`, `title`, `aria-label`):
+
+```tsx
+<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` , это мощный клиентский хук, предназначенный для улучшения пользовательского опыта и поддержания актуальности контента, объединяя предварительно отрендеренные словари с асинхронными обновлениями. Используя `isLoading` и декларации контента на основе TypeScript, вы можете легко интегрировать динамический, локализованный контент в свои приложения Next.js.

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

@@ -0,0 +1,105 @@
+# Интеграция Next.js: Документация по хуку `useLocale` для `next-intlayer`
+
+Этот раздел предлагает подробную документацию по хуку `useLocale`, адаптированному для приложений Next.js в рамках библиотеки `next-intlayer`. Он предназначен для эффективного управления изменениями локали и маршрутизацией.
+
+## Импортирование `useLocale` в Next.js
+
+Чтобы использовать хук `useLocale` в вашем приложении Next.js, импортируйте его следующим образом:
+
+```javascript
+import { useLocale } from "next-intlayer"; // Используется для управления локалями и маршрутизацией в Next.js
+```
+
+## Использование
+
+Вот как можно реализовать хук `useLocale` в компоненте Next.js:
+
+```tsx fileName="src/components/LocaleSwitcher.tsx" codeFormat="typescript"
+"use client";
+
+import type { FC } from "react";
+import { Locales } from "intlayer";
+import { useLocale } from "next-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>
+  );
+};
+```
+
+```jsx fileName="src/components/LocaleSwitcher.mjx" codeFormat="esm"
+"use client";
+
+import { Locales } from "intlayer";
+import { useLocale } from "next-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>
+  );
+};
+```
+
+```jsx fileName="src/components/LocaleSwitcher.csx" codeFormat="commonjs"
+"use client";
+
+const { Locales } = require("intlayer");
+const { useLocale } = require("next-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>
+  );
+};
+```
+
+## Параметры и возвращаемые значения
+
+При вызове хука `useLocale` он возвращает объект, содержащий следующие свойства:
+
+- **`locale`**: Текущая локаль, установленная в контексте React.
+- **`defaultLocale`**: Основная локаль, определенная в конфигурации.
+- **`availableLocales`**: Список всех доступных локалей, определенных в конфигурации.
+- **`setLocale`**: Функция для изменения локали приложения и обновления URL-адреса соответствующим образом. Она учитывает правила префикса, добавлять локаль в путь или нет, в зависимости от конфигурации. Использует `useRouter` из `next/navigation` для навигационных функций, таких как `push` и `refresh`.
+- **`pathWithoutLocale`**: Вычисляемое свойство, которое возвращает путь без локали. Это полезно для сравнения URL-адресов. Например, если текущая локаль , `fr`, а URL , `fr/my_path`, путь без локали будет `/my_path`. Использует `usePathname` из `next/navigation` для получения текущего пути.
+
+## Заключение
+
+Хук `useLocale` из `next-intlayer` является важным инструментом для управления локалями в приложениях Next.js. Он предлагает интегрированный подход к адаптации вашего приложения для нескольких локалей, обеспечивая управление хранилищем локалей, состоянием и модификацией URL-адресов без проблем.

package/ru/packages/preact-intlayer/index.md

@@ -0,0 +1,3 @@
+this doc will be automatically generated translated from the english doc
+
+see /docs/en/packages/preact-intlayer/index.md

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

@@ -0,0 +1,261 @@
+# react-intlayer: Пакет NPM для интернационализации (i18n) React-приложения
+
+**Intlayer** , это набор пакетов, разработанных специально для JavaScript-разработчиков. Он совместим с такими фреймворками, как React, React и Express.js.
+
+**Пакет `react-intlayer`** позволяет интернационализировать ваше React-приложение. Он предоставляет провайдеры контекста и хуки для интернационализации в React.
+
+## Почему важно интернационализировать ваше React-приложение?
+
+Интернационализация вашего React-приложения необходима для эффективного обслуживания глобальной аудитории. Это позволяет вашему приложению предоставлять контент и сообщения на предпочтительном языке каждого пользователя. Эта возможность улучшает пользовательский опыт и расширяет охват вашего приложения, делая его более доступным и актуальным для людей из разных языковых сообществ.
+
+## Почему стоит интегрировать Intlayer?
+
+- **Управление контентом на основе JavaScript**: Используйте гибкость JavaScript для эффективного определения и управления вашим контентом.
+- **Безопасная типизация**: Используйте TypeScript, чтобы гарантировать точность и отсутствие ошибок в определении контента.
+- **Интегрированные файлы контента**: Держите переводы рядом с соответствующими компонентами, улучшая их поддержку и ясность.
+
+## Установка
+
+Установите необходимый пакет, используя предпочитаемый менеджер пакетов:
+
+```bash packageManager="npm"
+npm install react-intlayer
+```
+
+```bash packageManager="yarn"
+yarn add react-intlayer
+```
+
+```bash packageManager="pnpm"
+pnpm add react-intlayer
+```
+
+## Пример использования
+
+С помощью Intlayer вы можете объявлять ваш контент структурированным образом в любом месте вашего кода.
+
+По умолчанию Intlayer сканирует файлы с расширением `.content.{json,ts,tsx,js,jsx,mjs,mjx,cjs,cjx}`.
+
+> Вы можете изменить расширение по умолчанию, установив свойство `contentDir` в [файле конфигурации](https://github.com/aymericzip/intlayer/blob/main/docs/ru/configuration.md).
+
+```bash codeFormat="typescript"
+.
+├── intlayer.config.ts
+└── src
+    └── components
+        ├── Component1
+        │   ├── index.content.ts
+        │   └── index.tsx
+        └── Component2
+            ├── index.content.ts
+            └── index.tsx
+```
+
+```bash codeFormat="esm"
+.
+├── intlayer.config.mjs
+└── src
+    └── components
+        ├── Component1
+        │   ├── index.content.mjs
+        │   └── index.mjx
+        └── Component2
+            ├── index.content.mjs
+            └── index.mjx
+```
+
+```bash codeFormat="commonjs"
+.
+├── intlayer.config.cjs
+└── src
+    └── components
+        ├── Component1
+        │   ├── index.content.cjs
+        │   └── index.cjx
+        └── Component2
+            ├── index.content.cjs
+            └── index.cjx
+```
+
+### Объявление контента
+
+`react-intlayer` предназначен для работы с пакетом [`intlayer`](https://github.com/aymericzip/intlayer/blob/main/docs/ru/packages/intlayer/index.md). `intlayer` , это пакет, который позволяет вам объявлять контент в любом месте вашего кода. Он преобразует многоязычные объявления контента в структурированные словари, которые легко интегрируются в ваше приложение.
+
+Вот пример объявления контента:
+
+```tsx fileName="src/Component1/index.content.ts" codeFormat="typescript"
+import { t, type Dictionary } from "intlayer";
+
+const component1Content = {
+  key: "component-1",
+  content: {
+    myTranslatedContent: t({
+      en: "Hello World",
+      fr: "Bonjour le monde",
+      es: "Hola Mundo",
+      ru: "Привет, мир",
+    }),
+    numberOfCar: enu({
+      "<-1": "Меньше минус одной машины",
+      "-1": "Минус одна машина",
+      "0": "Нет машин",
+      "1": "Одна машина",
+      ">5": "Несколько машин",
+      ">19": "Много машин",
+    }),
+  },
+} satisfies Dictionary;
+
+export default component1Content;
+```
+
+```jsx fileName="src/Component1/index.content.mjs" contentDeclarationFormat="esm"
+import { t } from "intlayer";
+
+/** @type {import('intlayer').Dictionary} */
+const component1Content = {
+  key: "component-1",
+  content: {
+    myTranslatedContent: t({
+      en: "Hello World",
+      fr: "Bonjour le monde",
+      es: "Hola Mundo",
+      ru: "Привет, мир",
+    }),
+    numberOfCar: enu({
+      "<-1": "Меньше минус одной машины",
+      "-1": "Минус одна машина",
+      "0": "Нет машин",
+      "1": "Одна машина",
+      ">5": "Несколько машин",
+      ">19": "Много машин",
+    }),
+  },
+};
+
+export default component1Content;
+```
+
+```jsx fileName="src/Component1/index.content.cjs" contentDeclarationFormat="commonjs"
+const { t } = require("intlayer");
+
+/** @type {import('intlayer').Dictionary} */
+const component1Content = {
+  key: "component-1",
+  content: {
+    myTranslatedContent: t({
+      en: "Hello World",
+      fr: "Bonjour le monde",
+      es: "Hola Mundo",
+      ru: "Привет, мир",
+    }),
+    numberOfCar: enu({
+      "<-1": "Меньше минус одной машины",
+      "-1": "Минус одна машина",
+      "0": "Нет машин",
+      "1": "Одна машина",
+      ">5": "Несколько машин",
+      ">19": "Много машин",
+    }),
+  },
+};
+
+module.exports = component1Content;
+```
+
+```json fileName="src/Component1/index.content.json" codeFormat="json"
+{
+  "key": "component-1",
+  "content": {
+    "myTranslatedContent": {
+      "nodeType": "translation",
+      "translation": {
+        "en": "Hello World",
+        "fr": "Bonjour le monde",
+        "es": "Hola Mundo",
+        "ru": "Привет, мир"
+      }
+    },
+    "numberOfCar": {
+      "nodeType": "enumeration",
+      "enumeration": {
+        "<-1": "Меньше минус одной машины",
+        "-1": "Минус одна машина",
+        "0": "Нет машин",
+        "1": "Одна машина",
+        ">5": "Несколько машин",
+        ">19": "Много машин"
+      }
+    }
+  }
+}
+```
+
+### Использование контента в коде
+
+После объявления контента вы можете использовать его в вашем коде. Вот пример использования контента в React-компоненте:
+
+```tsx {4,7} fileName="src/components/Component1Example.tsx" codeFormat="typescript"
+"use client";
+
+import type { FC } from "react";
+import { useIntlayer } from "react-intlayer";
+
+export const Component1Example: FC = () => {
+  const { myTranslatedContent } = useIntlayer("component-1"); // Создание связанного объявления контента
+
+  return (
+    <div>
+      <p>{myTranslatedContent}</p>
+    </div>
+  );
+};
+```
+
+```jsx {3,6} fileName="src/components/Component1Example.mjx" codeFormat="esm"
+"use client";
+
+import { useIntlayer } from "react-intlayer";
+
+const Component1Example = () => {
+  const { myTranslatedContent } = useIntlayer("component-1"); // Создание связанного объявления контента
+
+  return (
+    <div>
+      <p>{myTranslatedContent}</p>
+    </div>
+  );
+};
+```
+
+```jsx {3,6} fileName="src/components/Component1Example.csx" codeFormat="commonjs"
+"use client";
+
+const { useIntlayer } = require("react-intlayer");
+
+const Component1Example = () => {
+  const { myTranslatedContent } = useIntlayer("component-1"); // Создание связанного объявления контента
+
+  return (
+    <div>
+      <p>{myTranslatedContent}</p>
+    </div>
+  );
+};
+```
+
+## Освоение интернационализации вашего React-приложения
+
+Intlayer предоставляет множество функций, чтобы помочь вам интернационализировать ваше React-приложение.
+
+**Чтобы узнать больше об этих функциях, обратитесь к [руководству по интернационализации React (i18n) с Intlayer и Vite и React](https://github.com/aymericzip/intlayer/blob/main/docs/ru/intlayer_with_vite+react.md) для приложений на Vite и React или к [руководству по интернационализации React (i18n) с Intlayer и React (CRA)](https://github.com/aymericzip/intlayer/blob/main/docs/ru/intlayer_with_create_react_app.md) для приложений на Create React App.**
+
+## Функции, предоставляемые пакетом `react-intlayer`
+
+Пакет `react-intlayer` также предоставляет несколько функций, чтобы помочь вам интернационализировать ваше приложение.
+
+- [`t()`](https://github.com/aymericzip/intlayer/blob/main/docs/ru/packages/react-intlayer/t.md)
+- [`useIntlayer()`](https://github.com/aymericzip/intlayer/blob/main/docs/ru/packages/react-intlayer/useIntlayer.md)
+- [`useDictionary()`](https://github.com/aymericzip/intlayer/blob/main/docs/ru/packages/react-intlayer/useDictionary.md)
+- [`useLocale()`](https://github.com/aymericzip/intlayer/blob/main/docs/ru/packages/react-intlayer/useLocale.md)
+- [`useIntlayerAsync()`](https://github.com/aymericzip/intlayer/blob/main/docs/ru/packages/react-intlayer/useIntlayerAsync.md)