@intlayer/docs 5.5.8

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

@@ -0,0 +1,289 @@
+# Документация: Функция `t` в `react-intlayer`
+
+Функция `t` в пакете `react-intlayer` является основным инструментом для встроенной интернационализации в вашем React-приложении. Она позволяет определять переводы непосредственно в компонентах, что упрощает отображение локализованного контента в зависимости от текущей локали.
+
+---
+
+## Обзор
+
+Функция `t` используется для предоставления переводов для различных локалей непосредственно в компонентах. Передавая объект, содержащий переводы для каждой поддерживаемой локали, `t` возвращает соответствующий перевод на основе текущего контекста локали в вашем React-приложении.
+
+---
+
+## Основные особенности
+
+- **Встроенные переводы**: Идеально подходит для быстрого перевода текста, который не требует отдельного объявления контента.
+- **Автоматический выбор локали**: Автоматически возвращает перевод, соответствующий текущей локали.
+- **Поддержка TypeScript**: Обеспечивает безопасность типов и автозаполнение при использовании с TypeScript.
+- **Простая интеграция**: Легко интегрируется в компоненты React.
+
+---
+
+## Сигнатура функции
+
+```typescript
+t<T extends string>(content: Record<LocalesValues, T>, locale?: Locales): string
+```
+
+### Параметры
+
+- `translations`: Объект, где ключи , это коды локалей (например, `en`, `fr`, `es`), а значения , соответствующие переведенные строки.
+
+### Возвращаемое значение
+
+- Строка, представляющая переведенный контент для текущей локали.
+
+---
+
+## Примеры использования
+
+### Базовое использование `t` в компоненте
+
+```tsx fileName="src/components/ComponentExample.tsx" codeFormat="typescript"
+import type { FC } from "react";
+import { t } from "react-intlayer";
+
+export const ComponentExample: FC = () => {
+  return (
+    <div>
+      <p>
+        {t({
+          en: "This is an example of a component",
+          fr: "Ceci est un exemple de composant",
+          es: "Este es un ejemplo de componente",
+          ru: "Это пример компонента",
+        })}
+      </p>
+    </div>
+  );
+};
+```
+
+```jsx fileName="src/components/ComponentExample.mjx" codeFormat="esm"
+import { t } from "react-intlayer";
+
+const ComponentExample = () => {
+  return (
+    <div>
+      <p>
+        {t({
+          en: "This is an example of a component",
+          fr: "Ceci est un exemple de composant",
+          es: "Este es un ejemplo de componente",
+          ru: "Это пример компонента",
+        })}
+      </p>
+    </div>
+  );
+};
+```
+
+```jsx fileName="src/components/ComponentExample.csx" codeFormat="commonjs"
+const { t } = require("react-intlayer");
+
+const ComponentExample = () => {
+  return (
+    <div>
+      <p>
+        {t({
+          en: "This is an example of a component",
+          fr: "Ceci est un exemple de composant",
+          es: "Este es un ejemplo de componente",
+          ru: "Это пример компонента",
+        })}
+      </p>
+    </div>
+  );
+};
+```
+
+### Встроенные переводы в атрибутах
+
+Функция `t` особенно полезна для встроенных переводов в атрибутах JSX. При локализации атрибутов, таких как `alt`, `title`, `href` или `aria-label`, вы можете использовать `t` непосредственно в атрибуте.
+
+```jsx
+<button
+  aria-label={t({
+    en: "Submit",
+    fr: "Soumettre",
+    es: "Enviar",
+    ru: "Отправить",
+  })}
+>
+  {t({
+    en: "Submit",
+    fr: "Soumettre",
+    es: "Enviar",
+    ru: "Отправить",
+  })}
+  <img
+    src="/path/to/image"
+    alt={t({
+      en: "A beautiful scenery",
+      fr: "Un beau paysage",
+      es: "Un hermoso paisaje",
+      ru: "Красивый пейзаж",
+    })}
+  />
+</button>
+```
+
+---
+
+## Продвинутые темы
+
+### Интеграция с TypeScript
+
+Функция `t` безопасна для типов при использовании с TypeScript, что гарантирует предоставление всех необходимых локалей.
+
+```typescript codeFormat="typescript"
+import { t, type IConfigLocales } from "react-intlayer";
+
+const translations: IConfigLocales<string> = {
+  en: "Welcome",
+  fr: "Bienvenue",
+  es: "Bienvenido",
+  ru: "Добро пожаловать",
+};
+
+const greeting = t(translations);
+```
+
+```javascript codeFormat="esm"
+import { t, type IConfigLocales } from "react-intlayer";
+
+/** @type {import('react-intlayer').IConfigLocales<string>} */
+const translations = {
+  en: "Welcome",
+  fr: "Bienvenue",
+  es: "Bienvenido",
+  ru: "Добро пожаловать",
+};
+
+const greeting = t(translations);
+```
+
+```javascript codeFormat="commonjs"
+const { t, type IConfigLocales } = require("react-intlayer");
+
+/** @type {import('react-intlayer').IConfigLocales<string>} */
+const translations = {
+  en: "Welcome",
+  fr: "Bienvenue",
+  es: "Bienvenido",
+  ru: "Добро пожаловать",
+};
+
+const greeting = t(translations);
+```
+
+### Определение локали и контекста
+
+В `react-intlayer` текущая локаль управляется через `IntlayerProvider`. Убедитесь, что этот провайдер оборачивает ваши компоненты, и проп `locale` передается правильно.
+
+#### Пример:
+
+```tsx fileName="src/app.tsx" codeFormat="typescript"
+import type { FC } from "react";
+import type { Locales } from "intlayer";
+import { IntlayerProvider } from "react-intlayer";
+
+const App: FC<{ locale: Locales }> = ({ locale }) => (
+  <IntlayerProvider locale={locale}>
+    {/* Ваши компоненты здесь */}
+  </IntlayerProvider>
+);
+```
+
+```jsx fileName="src/app.mjx" codeFormat="esm"
+import { IntlayerProvider } from "react-intlayer";
+
+const App = ({ locale }) => (
+  <IntlayerProvider locale={locale}>
+    {/* Ваши компоненты здесь */}
+  </IntlayerProvider>
+);
+```
+
+```jsx fileName="src/app.csx" codeFormat="commonjs"
+const { IntlayerProvider } = require("react-intlayer");
+
+const App = ({ locale }) => (
+  <IntlayerProvider locale={locale}>
+    {/* Ваши компоненты здесь */}
+  </IntlayerProvider>
+);
+```
+
+---
+
+## Частые ошибки и их устранение
+
+### `t` возвращает undefined или неправильный перевод
+
+- **Причина**: Текущая локаль не установлена правильно, или перевод для текущей локали отсутствует.
+- **Решение**:
+  - Убедитесь, что `IntlayerProvider` настроен правильно с соответствующей локалью.
+  - Убедитесь, что ваш объект переводов включает все необходимые локали.
+
+### Отсутствие переводов в TypeScript
+
+- **Причина**: Объект переводов не удовлетворяет требованиям всех локалей, что приводит к ошибкам TypeScript.
+- **Решение**: Используйте тип `IConfigLocales`, чтобы обеспечить полноту переводов.
+
+```typescript codeFormat="typescript"
+const translations: IConfigLocales<string> = {
+  en: "Text",
+  fr: "Texte",
+  es: "Texto",
+  ru: "Текст",
+};
+
+const text = t(translations);
+```
+
+```javascript codeFormat="esm"
+const translations = {
+  en: "Text",
+  fr: "Texte",
+  es: "Texto",
+  ru: "Текст",
+};
+
+const text = t(translations);
+```
+
+```javascript codeFormat="commonjs"
+const { t, type IConfigLocales } = require("react-intlayer");
+
+/** @type {import('react-intlayer').IConfigLocales<string>} */
+const translations = {
+  en: "Text",
+  fr: "Texte",
+  es: "Texto",
+  ru: "Текст",
+};
+
+const text = t(translations);
+```
+
+---
+
+## Советы по эффективному использованию
+
+1. **Используйте `t` для простых встроенных переводов**: Идеально подходит для перевода небольших текстов непосредственно в компонентах.
+2. **Предпочитайте `useIntlayer` для структурированного контента**: Для более сложных переводов и повторного использования контента определяйте контент в файлах деклараций и используйте `useIntlayer`.
+3. **Обеспечьте согласованное предоставление локали**: Убедитесь, что локаль последовательно передается через `IntlayerProvider`.
+4. **Используйте TypeScript**: Используйте типы TypeScript, чтобы выявлять отсутствующие переводы и обеспечивать безопасность типов.
+
+---
+
+## Заключение
+
+Функция `t` в `react-intlayer` , это мощный и удобный инструмент для управления встроенными переводами в ваших React-приложениях. Эффективная интеграция этой функции улучшает возможности интернационализации вашего приложения, предоставляя лучший опыт для пользователей по всему миру.
+
+Для более детального использования и продвинутых функций обратитесь к [документации react-intlayer](https://github.com/aymericzip/intlayer/blob/main/docs/ru/intlayer_visual_editor.md).
+
+---
+
+**Примечание**: Не забудьте правильно настроить ваш `IntlayerProvider`, чтобы текущая локаль корректно передавалась вашим компонентам. Это важно для того, чтобы функция `t` возвращала правильные переводы.

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

@@ -0,0 +1,268 @@
+# Интеграция React: Документация по хуку `useDictionary`
+
+Этот раздел предоставляет подробное руководство по использованию хука `useDictionary` в приложениях React, позволяя эффективно управлять локализованным контентом без визуального редактора.
+
+## Импорт `useDictionary` в React
+
+Хук `useDictionary` может быть интегрирован в приложения React путем импорта в зависимости от контекста:
+
+- **Клиентский компонент:**
+
+  ```typescript codeFormat="typescript"
+  import { useDictionary } from "react-intlayer"; // Используется в клиентских компонентах React
+  ```
+
+  ```javascript codeFormat="esm"
+  import { useDictionary } from "react-intlayer"; // Используется в клиентских компонентах React
+  ```
+
+  ```javascript codeFormat="commonjs"
+  const { useDictionary } = require("react-intlayer"); // Используется в клиентских компонентах React
+  ```
+
+- **Серверный компонент:**
+
+  ```typescript codeFormat="typescript"
+  import { useDictionary } from "react-intlayer/server"; // Используется в серверных компонентах React
+  ```
+
+  ```javascript codeFormat="esm"
+  import { useDictionary } from "react-intlayer/server"; // Используется в серверных компонентах React
+  ```
+
+  ```javascript codeFormat="commonjs"
+  const { useDictionary } = require("react-intlayer/server"); // Используется в серверных компонентах React
+  ```
+
+## Параметры
+
+Хук принимает два параметра:
+
+1. **`dictionary`**: Объявленный объект словаря, содержащий локализованный контент для определенных ключей.
+2. **`locale`** (необязательно): Желаемая локаль. По умолчанию используется локаль текущего контекста, если не указано.
+
+## Словарь
+
+Все объекты словаря должны быть объявлены в структурированных файлах контента для обеспечения безопасности типов и предотвращения ошибок во время выполнения. Инструкции по настройке можно найти [здесь](https://github.com/aymericzip/intlayer/blob/main/docs/ru/dictionary/get_started.md). Вот пример объявления контента:
+
+```typescript fileName="./component.content.ts" contentDeclarationFormat="typescript"
+import { t, type Dictionary } from "intlayer";
+
+const componentContent = {
+  key: "component-example",
+  content: {
+    title: t({
+      en: "Client Component Example",
+      fr: "Exemple de composant client",
+      es: "Ejemplo de componente cliente",
+      ru: "Пример клиентского компонента",
+    }),
+    content: t({
+      en: "This is the content of a client component example",
+      fr: "Ceci est le contenu d'un exemple de composant client",
+      es: "Este es el contenido de un ejemplo de componente cliente",
+      ru: "Это содержимое примера клиентского компонента",
+    }),
+  },
+} satisfies Dictionary;
+
+export default componentContent;
+```
+
+```javascript fileName="./component.content.mjs" contentDeclarationFormat="esm"
+import { t } from "intlayer";
+
+/** @type {import('intlayer').Dictionary} */
+const componentContent = {
+  key: "component-example",
+  content: {
+    title: t({
+      en: "Client Component Example",
+      fr: "Exemple de composant client",
+      es: "Ejemplo de componente cliente",
+      ru: "Пример клиентского компонента",
+    }),
+    content: t({
+      en: "This is the content of a client component example",
+      fr: "Ceci est le contenu d'un exemple de composant client",
+      es: "Este es el contenido de un ejemplo de componente cliente",
+      ru: "Это содержимое примера клиентского компонента",
+    }),
+  },
+};
+
+export default componentContent;
+```
+
+```javascript fileName="./component.content.cjs" contentDeclarationFormat="commonjs"
+const { t } = require("intlayer");
+
+/** @type {import('intlayer').Dictionary} */
+const componentContent = {
+  key: "component-example",
+  content: {
+    title: t({
+      en: "Client Component Example",
+      fr: "Exemple de composant client",
+      es: "Ejemplo de componente cliente",
+      ru: "Пример клиентского компонента",
+    }),
+    content: t({
+      en: "This is the content of a client component example",
+      fr: "Ceci est le contenu d'un exemple de composant client",
+      es: "Este es el contenido de un ejemplo de componente cliente",
+      ru: "Это содержимое примера клиентского компонента",
+    }),
+  },
+};
+
+module.exports = componentContent;
+```
+
+```json fileName="./component.content.json" contentDeclarationFormat="json"
+{
+  "$schema": "https://intlayer.org/schema.json",
+  "key": "component-example",
+  "content": {
+    "title": {
+      "nodeType": "translation",
+      "translation": {
+        "en": "Client Component Example",
+        "fr": "Exemple de composant client",
+        "es": "Ejemplo de componente cliente",
+        "ru": "Пример клиентского компонента"
+      }
+    },
+    "content": {
+      "nodeType": "translation",
+      "translation": {
+        "en": "This is the content of a client component example",
+        "fr": "Ceci est le contenu d'un exemple de composant client",
+        "es": "Este es el contenido de un ejemplo de componente cliente",
+        "ru": "Это содержимое примера клиентского компонента"
+      }
+    }
+  }
+}
+```
+
+## Пример использования в React
+
+Ниже приведен пример использования хука `useDictionary` в компоненте React:
+
+```tsx fileName="./ComponentExample.tsx" codeFormat="typescript"
+import type { FC } from "react";
+import { useDictionary } from "react-intlayer";
+import componentContent from "./component.content";
+
+const ComponentExample: FC = () => {
+  const { title, content } = useDictionary(componentContent);
+
+  return (
+    <div>
+      <h1>{title}</h1>
+      <p>{content}</p>
+    </div>
+  );
+};
+```
+
+```jsx fileName="./ComponentExample.mjx" codeFormat="esm"
+import { useDictionary } from "react-intlayer";
+import componentContent from "./component.content";
+
+const ComponentExample = () => {
+  const { title, content } = useDictionary(componentContent);
+
+  return (
+    <div>
+      <h1>{title}</h1>
+      <p>{content}</p>
+    </div>
+  );
+};
+```
+
+```jsx fileName="./ComponentExample.csx" codeFormat="commonjs"
+const { useDictionary } = require("react-intlayer");
+const componentContent = require("./component.content");
+
+const ComponentExample = () => {
+  const { title, content } = useDictionary(componentContent);
+
+  return (
+    <div>
+      <h1>{title}</h1>
+      <p>{content}</p>
+    </div>
+  );
+};
+```
+
+## Интеграция на сервере
+
+Если вы используете хук `useDictionary` вне `IntlayerProvider`, локаль должна быть явно указана в качестве параметра при рендеринге компонента:
+
+```tsx fileName="./ServerComponentExample.tsx" codeFormat="typescript"
+import type { FC } from "react";
+import { useDictionary } from "react-intlayer/server";
+import clientComponentExampleContent from "./component.content";
+
+const ServerComponentExample: FC<{ locale: string }> = ({ locale }) => {
+  const { content } = useDictionary(clientComponentExampleContent, locale);
+
+  return (
+    <div>
+      <h1>{content.title}</h1>
+      <p>{content.content}</p>
+    </div>
+  );
+};
+```
+
+```jsx fileName="./ServerComponentExample.mjx" codeFormat="esm"
+import { useDictionary } from "react-intlayer/server";
+import componentContent from "./component.content";
+
+const ServerComponentExample = ({ locale }) => {
+  const { content } = useDictionary(componentContent, locale);
+
+  return (
+    <div>
+      <h1>{content.title}</h1>
+      <p>{content.content}</p>
+    </div>
+  );
+};
+```
+
+```jsx fileName="./ServerComponentExample.csx" codeFormat="commonjs"
+const { useDictionary } = require("react-intlayer/server");
+const componentContent = require("./component.content");
+
+const ServerComponentExample = ({ locale }) => {
+  const { content } = useDictionary(componentContent, locale);
+
+  return (
+    <div>
+      <h1>{content.title}</h1>
+      <p>{content.content}</p>
+    </div>
+  );
+};
+```
+
+## Заметки по атрибутам
+
+В отличие от интеграций с использованием визуальных редакторов, такие атрибуты, как `buttonTitle.value`, здесь не применяются. Вместо этого напрямую используйте локализованные строки, как они объявлены в вашем контенте.
+
+```jsx
+<button title={content.title}>{content.content}</button>
+```
+
+## Дополнительные советы
+
+- **Безопасность типов**: Всегда используйте `Dictionary` для определения ваших словарей, чтобы обеспечить безопасность типов.
+- **Обновления локализации**: При обновлении контента убедитесь, что все локали согласованы, чтобы избежать отсутствия переводов.
+
+Эта документация сосредоточена на интеграции хука `useDictionary`, предоставляя упрощенный подход к управлению локализованным контентом без использования функционала визуального редактора.