@intlayer/docs 5.5.8

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

@@ -0,0 +1,267 @@
+# next-intlayer: Пакет NPM для интернационализации (i18n) приложения Next.js
+
+**Intlayer** , это набор пакетов, специально разработанных для разработчиков на JavaScript. Он совместим с такими фреймворками, как React, Next.js и Express.js.
+
+**Пакет `next-intlayer`** позволяет интернационализировать ваше приложение Next.js. Он предоставляет провайдеры контекста и хуки для интернационализации Next.js. Кроме того, он включает плагин Next.js для интеграции Intlayer с [Webpack](https://webpack.js.org/) или [Turbopack](https://nextjs.org/docs/app/api-reference/turbopack), а также middleware для определения предпочтительного языка пользователя, управления cookies и обработки перенаправления URL.
+
+## Зачем интернационализировать ваше приложение Next.js?
+
+Интернационализация вашего приложения Next.js необходима для эффективного обслуживания глобальной аудитории. Это позволяет вашему приложению предоставлять контент и сообщения на предпочтительном языке каждого пользователя. Эта возможность улучшает пользовательский опыт и расширяет охват вашего приложения, делая его более доступным и актуальным для людей с разным языковым фоном.
+
+## Почему стоит интегрировать Intlayer?
+
+- **Управление контентом на JavaScript**: Используйте гибкость JavaScript для эффективного определения и управления вашим контентом.
+- **Безопасная типизация**: Используйте TypeScript, чтобы все определения вашего контента были точными и безошибочными.
+- **Интеграция файлов контента**: Держите переводы рядом с их соответствующими компонентами, улучшая удобство поддержки и ясность.
+
+## Установка
+
+Установите необходимый пакет с помощью предпочитаемого менеджера пакетов:
+
+```bash packageManager="npm"
+npm install next-intlayer
+```
+
+```bash packageManager="yarn"
+yarn add next-intlayer
+```
+
+```bash packageManager="pnpm"
+pnpm add next-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
+        ├── ClientComponent
+        │   ├── index.content.ts
+        │   └── index.tsx
+        └── ServerComponent
+            ├── index.content.ts
+            └── index.tsx
+```
+
+```bash codeFormat="esm"
+.
+├── intlayer.config.mjs
+└── src
+    └── components
+        ├── ClientComponent
+        │   ├── index.content.mjs
+        │   └── index.mjx
+        └── ServerComponent
+            ├── index.content.mjs
+            └── index.mjx
+```
+
+```bash codeFormat="commonjs"
+.
+├── intlayer.config.cjs
+└── src
+    └── components
+        ├── ClientComponent
+        │   ├── index.content.cjs
+        │   └── index.cjx
+        └── ServerComponent
+            ├── index.content.cjs
+            └── index.cjx
+```
+
+### Объявление контента
+
+`next-intlayer` создан для работы с пакетом [`intlayer`](https://github.com/aymericzip/intlayer/blob/main/docs/ru/packages/intlayer/index.md). `intlayer` , это пакет, который позволяет объявлять ваш контент в любом месте вашего кода. Он преобразует многоязычные объявления контента в структурированные словари, которые легко интегрируются в ваше приложение.
+
+Пример объявления контента:
+
+```tsx fileName="src/ClientComponent/index.content.ts" codeFormat="typescript"
+import { t, type Dictionary } from "intlayer";
+
+const clientComponentContent = {
+  key: "client-component",
+  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 clientComponentContent;
+```
+
+```jsx fileName="src/ClientComponent/index.content.mjs" contentDeclarationFormat="esm"
+import { t } from "intlayer";
+
+/** @type {import('intlayer').Dictionary} */
+const clientComponentContent = {
+  key: "client-component",
+  content: {
+    myTranslatedContent: t({
+      en: "Hello World",
+      fr: "Bonjour le monde",
+      es: "Hola Mundo",
+      ru: "Привет, мир",
+    }),
+    numberOfCar: enu({
+      "<-1": "Меньше минус одной машины",
+      "-1": "Минус одна машина",
+      "0": "Нет машин",
+      "1": "Одна машина",
+      ">5": "Несколько машин",
+      ">19": "Много машин",
+    }),
+  },
+};
+
+export default clientComponentContent;
+```
+
+```jsx fileName="src/ClientComponent/index.content.cjs" contentDeclarationFormat="commonjs"
+const { t } = require("intlayer");
+
+/** @type {import('intlayer').Dictionary} */
+const clientComponentContent = {
+  key: "client-component",
+  content: {
+    myTranslatedContent: t({
+      en: "Hello World",
+      fr: "Bonjour le monde",
+      es: "Hola Mundo",
+      ru: "Привет, мир",
+    }),
+    numberOfCar: enu({
+      "<-1": "Меньше минус одной машины",
+      "-1": "Минус одна машина",
+      "0": "Нет машин",
+      "1": "Одна машина",
+      ">5": "Несколько машин",
+      ">19": "Много машин",
+    }),
+  },
+};
+
+module.exports = clientComponentContent;
+```
+
+```json fileName="src/ClientComponent/index.content.json" codeFormat="json"
+{
+  "key": "client-component",
+  "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/ClientComponentExample.tsx" codeFormat="typescript"
+"use client";
+
+import type { FC } from "react";
+import { useIntlayer } from "next-intlayer";
+
+export const ClientComponentExample: FC = () => {
+  const { myTranslatedContent } = useIntlayer("client-component"); // Создание связанного объявления контента
+
+  return (
+    <div>
+      <p>{myTranslatedContent}</p>
+    </div>
+  );
+};
+```
+
+```jsx {3,6} fileName="src/components/ClientComponentExample.mjx" codeFormat="esm"
+"use client";
+
+import { useIntlayer } from "next-intlayer";
+
+const ClientComponentExample = () => {
+  const { myTranslatedContent } = useIntlayer("client-component"); // Создание связанного объявления контента
+
+  return (
+    <div>
+      <p>{myTranslatedContent}</p>
+    </div>
+  );
+};
+```
+
+```jsx {3,6} fileName="src/components/ClientComponentExample.csx" codeFormat="commonjs"
+"use client";
+
+const { useIntlayer } = require("next-intlayer");
+
+const ClientComponentExample = () => {
+  const { myTranslatedContent } = useIntlayer("client-component"); // Создание связанного объявления контента
+
+  return (
+    <div>
+      <p>{myTranslatedContent}</p>
+    </div>
+  );
+};
+```
+
+## Освоение интернационализации вашего приложения Next.js
+
+Intlayer предоставляет множество функций для помощи в интернационализации вашего приложения Next.js. Вот некоторые из ключевых функций:
+
+- **Интернационализация серверных компонентов**: Intlayer позволяет интернационализировать серверные компоненты так же, как и клиентские. Это означает, что вы можете использовать одни и те же объявления контента для клиентских и серверных компонентов.
+- **Middleware для определения языка**: Intlayer предоставляет middleware для определения предпочтительного языка пользователя. Этот middleware используется для определения предпочтительного языка пользователя и перенаправления их на соответствующий URL, указанный в [конфигурации](https://github.com/aymericzip/intlayer/blob/main/docs/ru/configuration.md).
+- **Интернационализация метаданных**: Intlayer предоставляет способ интернационализировать ваши метаданные, такие как заголовок страницы, с использованием функции `generateMetadata`, предоставляемой Next.js. Вы можете использовать функцию `getTranslation` для перевода ваших метаданных.
+- **Интернационализация sitemap.xml и robots.txt**: Intlayer позволяет интернационализировать ваши файлы sitemap.xml и robots.txt. Вы можете использовать функцию `getMultilingualUrls` для генерации многоязычных URL для вашего sitemap.
+- **Интернационализация URL**: Intlayer позволяет интернационализировать ваши URL, используя функцию `getMultilingualUrls`. Эта функция генерирует многоязычные URL для вашего sitemap.
+
+**Чтобы узнать больше об этих функциях, обратитесь к руководству [Интернационализация (i18n) Next.js с Intlayer и маршрутизатором App Next.js 15](https://github.com/aymericzip/intlayer/blob/main/docs/ru/intlayer_with_nextjs_15.md).**
+
+## Функции, предоставляемые пакетом `next-intlayer`
+
+Пакет `next-intlayer` также предоставляет несколько функций для помощи в интернационализации вашего приложения.
+
+- [`t()`](https://github.com/aymericzip/intlayer/blob/main/docs/ru/packages/next-intlayer/t.md)
+- [`useIntlayer()`](https://github.com/aymericzip/intlayer/blob/main/docs/ru/packages/next-intlayer/useIntlayer.md)
+- [`useDictionary()`](https://github.com/aymericzip/intlayer/blob/main/docs/ru/packages/next-intlayer/useDictionary.md)
+- [`useLocale()`](https://github.com/aymericzip/intlayer/blob/main/docs/ru/packages/next-intlayer/useLocale.md)
+- [`useIntlayerAsync()`](https://github.com/aymericzip/intlayer/blob/main/docs/ru/packages/next-intlayer/useIntlayerAsync.md)

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

@@ -0,0 +1,340 @@
+# Документация: Функция `t` в `next-intlayer`
+
+Функция `t` в пакете `next-intlayer` является основным инструментом для встроенной интернационализации в вашем приложении Next.js. Она позволяет определять переводы непосредственно в компонентах, упрощая отображение локализованного контента в зависимости от текущей локали.
+
+---
+
+## Обзор
+
+Функция `t` используется для предоставления переводов для различных локалей прямо в компонентах. Передавая объект, содержащий переводы для каждой поддерживаемой локали, `t` возвращает соответствующий перевод на основе текущего контекста локали в вашем приложении Next.js.
+
+---
+
+## Основные возможности
+
+- **Встроенные переводы**: Идеально подходит для быстрого, встроенного текста, который не требует отдельного объявления контента.
+- **Автоматический выбор локали**: Автоматически возвращает перевод, соответствующий текущей локали.
+- **Поддержка TypeScript**: Обеспечивает безопасность типов и автозаполнение при использовании с TypeScript.
+- **Простая интеграция**: Бесшовно работает как в клиентских, так и в серверных компонентах Next.js.
+
+---
+
+## Сигнатура функции
+
+```typescript
+t<T extends string>(content: Record<LocalesValues, T>, locale?: Locales): string
+```
+
+### Параметры
+
+- `translations`: Объект, где ключи , это коды локалей (например, `en`, `fr`, `es`), а значения , соответствующие переведенные строки.
+
+### Возвращает
+
+- Строку, представляющую переведенный контент для текущей локали.
+
+---
+
+## Примеры использования
+
+### Использование `t` в клиентском компоненте
+
+Убедитесь, что вы включили директиву `'use client';` в начале файла компонента при использовании `t` в клиентском компоненте.
+
+```tsx codeFormat="typescript"
+"use client";
+
+import type { FC } from "react";
+import { t } from "next-intlayer";
+
+export const ClientComponentExample: FC = () => (
+  <p>
+    {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 d un ejemplo de componente cliente",
+      ru: "Это содержимое примера клиентского компонента",
+    })}
+  </p>
+);
+```
+
+```javascript codeFormat="esm"
+import { t } from "next-intlayer";
+
+const ClientComponentExample = () => (
+  <p>
+    {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 d un ejemplo de componente cliente",
+      ru: "Это содержимое примера клиентского компонента",
+    })}
+  </p>
+);
+```
+
+```javascript codeFormat="commonjs"
+const { t } = require("next-intlayer");
+
+const ClientComponentExample = () => (
+  <p>
+    {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 le contenido d un ejemplo de componente cliente",
+      ru: "Это содержимое примера клиентского компонента",
+    })}
+  </p>
+);
+```
+
+### Использование `t` в серверном компоненте
+
+```tsx codeFormat="typescript"
+import type { FC } from "react";
+import { t } from "next-intlayer/server";
+
+export const ServerComponentExample: FC = () => (
+  <p>
+    {t({
+      en: "This is the content of a server component example",
+      fr: "Ceci est le contenu d'un exemple de composant serveur",
+      es: "Este es el contenido de un ejemplo de componente servidor",
+      ru: "Это содержимое примера серверного компонента",
+    })}
+  </p>
+);
+```
+
+```javascript codeFormat="esm"
+import { t } from "next-intlayer/server";
+
+const ServerComponentExample = () => (
+  <p>
+    {t({
+      en: "This is the content of a server component example",
+      fr: "Ceci est le contenu d'un exemple de composant serveur",
+      es: "Este es el contenido de un ejemplo de componente сервер",
+      ru: "Это содержимое примера серверного компонента",
+    })}
+  </p>
+);
+```
+
+```javascript codeFormat="commonjs"
+const { t } = require("next-intlayer/server");
+
+const ServerComponentExample = () => (
+  <p>
+    {t({
+      en: "This is the content of a server component example",
+      fr: "Ceci est le contenu d'un exemple de composant serveur",
+      es: "Este es el contenido de un ejemplo de componente сервер",
+      ru: "Это содержимое примера серверного компонента",
+    })}
+  </p>
+);
+```
+
+### Встроенные переводы в атрибутах
+
+Функция `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 type { IConfigLocales } from "intlayer";
+import { t } from "next-intlayer";
+
+const translations: IConfigLocales<string> = {
+  en: "Welcome",
+  fr: "Bienvenue",
+  es: "Bienvenido",
+  ru: "Добро пожаловать",
+};
+
+const greeting = t(translations);
+```
+
+```javascript codeFormat="esm"
+import type { IConfigLocales } from "intlayer";
+import { t } from "next-intlayer";
+
+/** @type {import('next-intlayer').IConfigLocales<string>} */
+const translations = {
+  en: "Welcome",
+  fr: "Bienvenue",
+  es: "Bienvenido",
+  ru: "Добро пожаловать",
+};
+
+const greeting = t(translations);
+```
+
+```javascript codeFormat="commonjs"
+const { t } = require("next-intlayer");
+
+/** @type {import('next-intlayer').IConfigLocales<string>} */
+const translations = {
+  en: "Welcome",
+  fr: "Bienvenue",
+  es: "Bienvenido",
+  ru: "Добро пожаловать",
+};
+
+const greeting = t(translations);
+```
+
+### Обнаружение локали и контекст
+
+В `next-intlayer` текущая локаль управляется через провайдеры контекста: `IntlayerClientProvider` и `IntlayerServerProvider`. Убедитесь, что эти провайдеры оборачивают ваши компоненты, и свойство `locale` передается правильно.
+
+#### Пример:
+
+```tsx codeFormat="typescript"
+import type { FC } from "react";
+import type { Locales } from "intlayer";
+import { IntlayerClientProvider } from "next-intlayer";
+import { IntlayerServerProvider } from "next-intlayer/server";
+
+const Page: FC<{ locale: Locales }> = ({ locale }) => (
+  <IntlayerServerProvider locale={locale}>
+    <IntlayerClientProvider locale={locale}>
+      {/* Ваши компоненты здесь */}
+    </IntlayerClientProvider>
+  </IntlayerServerProvider>
+);
+```
+
+```javascript codeFormat="esm"
+import { IntlayerClientProvider } from "next-intlayer";
+import { IntlayerServerProvider } from "next-intlayer/server";
+
+const Page = ({ locale }) => (
+  <IntlayerServerProvider locale={locale}>
+    <IntlayerClientProvider locale={locale}>
+      {/* Ваши компоненты здесь */}
+    </IntlayerClientProvider>
+  </IntlayerServerProvider>
+);
+```
+
+```javascript codeFormat="commonjs"
+const { IntlayerClientProvider } = require("next-intlayer");
+const { IntlayerServerProvider } = require("next-intlayer/server");
+
+const Page = ({ locale }) => (
+  <IntlayerServerProvider locale={locale}>
+    <IntlayerClientProvider locale={locale}>
+      {/* Ваши компоненты здесь */}
+    </IntlayerClientProvider>
+  </IntlayerServerProvider>
+);
+```
+
+---
+
+## Частые ошибки и их устранение
+
+### `t` возвращает undefined или неправильный перевод
+
+- **Причина**: Текущая локаль не установлена должным образом или перевод для текущей локали отсутствует.
+- **Решение**:
+  - Убедитесь, что `IntlayerClientProvider` или `IntlayerServerProvider` настроены правильно с соответствующей локалью.
+  - Убедитесь, что ваш объект переводов включает все необходимые локали.
+
+### Отсутствие переводов в TypeScript
+
+- **Причина**: Объект переводов не удовлетворяет требованиям локалей, что приводит к ошибкам TypeScript.
+- **Решение**: Используйте тип `IConfigLocales`, чтобы обеспечить полноту переводов.
+
+```typescript codeFormat="typescript"
+const translations: IConfigLocales<string> = {
+  en: "Text",
+  fr: "Texte",
+  // es: 'Texto', // Отсутствие 'es' вызовет ошибку TypeScript [!code error]
+  ru: "Текст",
+};
+
+const text = t(translations);
+```
+
+```javascript codeFormat="esm"
+const translations = {
+  en: "Text",
+  fr: "Texte",
+  // es: 'Texto', // Отсутствие 'es' вызовет ошибку TypeScript [!code error]
+  ru: "Текст",
+};
+
+const text = t(translations);
+```
+
+```javascript codeFormat="commonjs"
+const { t } = require("next-intlayer");
+
+/** @type {import('next-intlayer').IConfigLocales<string>} */
+const translations = {
+  en: "Text",
+  fr: "Texte",
+  // es: 'Texto', // Отсутствие 'es' вызовет ошибку TypeScript [!code error]
+  ru: "Текст",
+};
+
+const text = t(translations);
+```
+
+---
+
+## Советы по эффективному использованию
+
+1. **Используйте `t` для простых встроенных переводов**: Идеально подходит для перевода небольших текстов прямо в компонентах.
+2. **Предпочитайте `useIntlayer` для структурированного контента**: Для более сложных переводов и повторного использования контента определяйте контент в файлах деклараций и используйте `useIntlayer`.
+3. **Последовательное предоставление локали**: Убедитесь, что локаль последовательно предоставляется через соответствующие провайдеры.
+4. **Используйте TypeScript**: Используйте типы TypeScript, чтобы выявлять отсутствующие переводы и обеспечивать безопасность типов.
+
+---
+
+## Заключение
+
+Функция `t` в `next-intlayer` , это мощный и удобный инструмент для управления встроенными переводами в ваших приложениях Next.js. Эффективно интегрируя её, вы улучшаете возможности интернационализации вашего приложения, обеспечивая лучший опыт для пользователей по всему миру.
+
+Для более детального использования и продвинутых функций обратитесь к [документации next-intlayer](https://github.com/aymericzip/intlayer/blob/main/docs/ru/intlayer_visual_editor.md).
+
+---
+
+**Примечание**: Не забудьте правильно настроить ваши `IntlayerClientProvider` и `IntlayerServerProvider`, чтобы текущая локаль корректно передавалась вашим компонентам. Это важно для того, чтобы функция `t` возвращала правильные переводы.