@intlayer/docs 5.5.9 → 5.5.11

package/blog/ru/intlayer_with_react-i18next.md

@@ -0,0 +1,346 @@
+---
+createdAt: 2025-01-02
+updatedAt: 2025-06-29
+title: Intlayer и react-i18next
+description: Сравнить Intlayer с react-i18next для приложения React
+keywords:
+  - react-i18next
+  - i18next
+  - Intlayer
+  - Интернационализация
+  - Документация
+  - Next.js
+  - JavaScript
+  - React
+slugs:
+  - blog
+  - intlayer-with-react-i18next
+---
+
+# React Internationalization (i18n) с react-i18next и Intlayer
+
+## Обзор
+
+- **Intlayer** помогает вам управлять переводами с помощью файлов декларации контента на **уровне компонентов**.
+- **react-i18next** - популярная интеграция React для **i18next**, которая предоставляет хуки, такие как `useTranslation`, для получения локализованных строк в ваших компонентах.
+
+Когда они объединены, Intlayer может **экспортировать** словари в **i18next-совместимый JSON**, чтобы react-i18next мог **потреблять** их во время выполнения.
+
+## Зачем использовать Intlayer с react-i18next?
+
+Файлы декларации контента **Intlayer** предлагают лучший опыт разработчика, потому что они:
+
+1. **Гибкие в размещении файлов**  
+   Поместите каждый файл декларации контента прямо рядом с компонентом, которому он нужен. Эта структура позволяет вам сохранять переводы в одном месте, предотвращая оставшихся от orphaned переводов, когда компоненты перемещаются или удаляются.
+
+   ```bash codeFormat="typescript"
+   .
+   └── src
+       └── components
+           └── MyComponent
+               ├── index.content.ts # Файл декларации контента
+               └── index.tsx
+   ```
+
+   ```bash codeFormat="esm"
+   .
+   └── src
+       └── components
+           └── MyComponent
+               ├── index.content.mjs # Файл декларации контента
+               └── index.mjx
+   ```
+
+   ```bash codeFormat="cjs"
+   .
+   └── src
+       └── components
+           └── MyComponent
+               ├── index.content.cjs # Файл декларации контента
+               └── index.cjx
+   ```
+
+   ```bash codeFormat="json"
+   .
+   └── src
+       └── components
+           └── MyComponent
+               ├── index.content.json # Файл декларации контента
+               └── index.jsx
+   ```
+
+2. **Централизованные переводы**  
+   Один файл декларации контента собирает все необходимые переводы для компонента, облегчая обнаружение недостающих переводов.  
+   С TypeScript вы даже получите ошибки во время компиляции, если переводы отсутствуют.
+
+## Установка
+
+В проекте Create React App установите эти зависимости:
+
+```bash
+# С npm
+npm install intlayer react-i18next i18next i18next-resources-to-backend
+```
+
+```bash
+# С yarn
+yarn add intlayer react-i18next i18next i18next-resources-to-backend
+```
+
+```bash
+# С pnpm
+pnpm add intlayer react-i18next i18next i18next-resources-to-backend
+```
+
+### Что это за пакеты?
+
+- **intlayer** – CLI и основная библиотека для управления конфигурациями i18n, декларациями контента и построением выходных словарей.
+- **react-intlayer** – Специфическая для React интеграция для Intlayer, предоставляющая скрипты для автоматизации создания словарей.
+- **react-i18next** – Специфическая для React библиотека интеграции для i18next, включая хук `useTranslation`.
+- **i18next** – Основная платформа для обработки переводов.
+- **i18next-resources-to-backend** – Бэкенд i18next, который динамически импортирует ресурсы JSON.
+
+## Настройка Intlayer для экспорта словарей i18next
+
+Создайте (или обновите) ваш `intlayer.config.ts` в корне вашего проекта:
+
+```typescript title="intlayer.config.ts"
+import { Locales, type IntlayerConfig } from "intlayer";
+
+const config: IntlayerConfig = {
+  internationalization: {
+    // Добавьте столько локалей, сколько вам нужно
+    locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
+    defaultLocale: Locales.ENGLISH,
+  },
+  content: {
+    // Укажите Intlayer создавать i18next-совместимый JSON
+    dictionaryOutput: ["i18next"],
+
+    // Выберите выходной каталог для созданных ресурсов
+    // Эта папка будет создана, если еще не существует.
+    i18nextResourcesDir: "./i18next/resources",
+  },
+};
+
+export default config;
+```
+
+> **Примечание**: Если вы не используете TypeScript, вы можете создать этот файл конфигурации как `.cjs`, `.mjs` или `.js` (см. [документацию Intlayer](https://intlayer.org/ru/doc/concept/configuration) для получения подробной информации).
+
+## Создание ресурсов i18next
+
+После того как ваши декларации контента будут на месте (в следующем разделе), выполните **команду сборки Intlayer**:
+
+```bash
+# С npm
+npx run intlayer build
+```
+
+```bash
+# С yarn
+yarn intlayer build
+```
+
+```bash
+# С pnpm
+pnpm intlayer build
+```
+
+> Это сгенерирует ваши ресурсы i18next внутри директории `./i18next/resources` по умолчанию.
+
+Типичный вывод может выглядеть так:
+
+```bash
+.
+└── i18next
+    └── resources
+       ├── en
+       │   └── my-content.json
+       ├── fr
+       │   └── my-content.json
+       └── es
+           └── my-content.json
+```
+
+Где каждый ключ декларации **Intlayer** используется как **i18next пространство имен** (например, `my-content.json`).
+
+## Импорт словарей в вашу конфигурацию react-i18next
+
+Чтобы динамически загружать эти ресурсы во время выполнения, используйте [`i18next-resources-to-backend`](https://www.npmjs.com/package/i18next-resources-to-backend). Например, создайте файл `i18n.ts` (или `.js`) в вашем проекте:
+
+```typescript title="i18n.ts"
+import i18next from "i18next";
+import { initReactI18next } from "react-i18next";
+import resourcesToBackend from "i18next-resources-to-backend";
+
+i18next
+  // плагин react-i18next
+  .use(initReactI18next)
+  // динамическая загрузка ресурсов
+  .use(
+    resourcesToBackend((language: string, namespace: string) => {
+      // Настройте путь импорта к вашему каталогу ресурсов
+      return import(`../i18next/resources/${language}/${namespace}.json`);
+    })
+  )
+  // Инициализация i18next
+  .init({
+    // Альтернативная локаль
+    fallbackLng: "en",
+
+    // Вы можете добавить другие параметры конфигурации i18next здесь, смотрите:
+    // https://www.i18next.com/overview/configuration-options
+  });
+
+export default i18next;
+```
+
+```javascript title="i18n.js"
+import i18next from "i18next";
+import { initReactI18next } from "react-i18next";
+import resourcesToBackend from "i18next-resources-to-backend";
+
+i18next
+  .use(initReactI18next)
+  .use(
+    resourcesToBackend(
+      (language, namespace) =>
+        import(`../i18next/resources/${language}/${namespace}.json`)
+    )
+  )
+  .init({
+    fallbackLng: "en",
+  });
+
+export default i18next;
+```
+
+Затем, в вашем **корневом** или **индексном** файле (например, `src/index.tsx`), импортируйте эту настройку `i18n` **до** рендеринга `App`:
+
+```typescript
+import React from "react";
+import ReactDOM from "react-dom/client";
+// Инициализация i18n перед чем-либо еще
+import "./i18n";
+import App from "./App";
+
+ReactDOM.createRoot(document.getElementById("root") as HTMLElement).render(
+  <React.StrictMode>
+    <App />
+  </React.StrictMode>
+);
+```
+
+## Создание и управление вашими декларациями контента
+
+Intlayer извлекает переводы из “файлов декларации контента”, находящихся где угодно под `./src` (по умолчанию).  
+Вот минимальный пример на TypeScript:
+
+```typescript title="src/components/MyComponent/MyComponent.content.ts"
+import { t, type Dictionary } from "intlayer";
+
+const content = {
+  // "key" будет вашим пространством имен i18next (например, "my-component")
+  key: "my-component",
+  content: {
+    // Каждый вызов "t" - это отдельный узел перевода
+    heading: t({
+      en: "Hello World",
+      fr: "Bonjour le monde",
+      es: "Hola Mundo",
+    }),
+    description: t({
+      en: "My i18n description text...",
+      fr: "Ma description en i18n...",
+      es: "Mi descripción en i18n...",
+    }),
+  },
+} satisfies Dictionary;
+
+export default content;
+```
+
+Если вы предпочитаете JSON, `.cjs` или `.mjs`, обратитесь к [документации Intlayer](https://intlayer.org/ru/doc/concept/content).
+
+> По умолчанию действительные декларации контента соответствуют шаблону расширения файла:
+
+> `*.content.{ts,tsx,js,jsx,mjs,mjx,cjs,cjx,json}`
+
+## Использование переводов в React-компонентах
+
+После того как вы **собрали** свои ресурсы Intlayer и настроили react-i18next, вы можете напрямую использовать хук `useTranslation` из **react-i18next**.  
+Например:
+
+```tsx title="src/components/MyComponent/MyComponent.tsx"
+import type { FC } from "react";
+import { useTranslation } from "react-i18next";
+
+/**
+ * Пространство имен i18next - это ключ Intlayer из "MyComponent.content.ts",
+ * поэтому мы передадим "my-component" в useTranslation().
+ */
+const MyComponent: FC = () => {
+  const { t } = useTranslation("my-component");
+
+  return (
+    <div>
+      <h1>{t("heading")}</h1>
+      <p>{t("description")}</p>
+    </div>
+  );
+};
+
+export default MyComponent;
+```
+
+> Обратите внимание, что функция `t` ссылается на **ключи** внутри вашего сгенерированного JSON. Для записи контента Intlayer с именем `heading`, вы будете использовать `t("heading")`.
+
+## Дополнительно: Интеграция с Create React App Scripts (CRACO)
+
+**react-intlayer** предлагает подход на основе CRACO для пользовательских сборок и конфигурации сервера разработки. Если вы хотите seamlessly интегрировать шаг сборки Intlayer, вы можете:
+
+1. **Установить react-intlayer** (если вы этого еще не сделали):
+   ```bash
+   npm install react-intlayer --save-dev
+   ```
+2. **Настройте ваши скрипты `package.json`** для использования скриптов `react-intlayer`:
+
+   ```jsonc
+   "scripts": {
+     "start": "react-intlayer start",
+     "build": "react-intlayer build",
+     "transpile": "intlayer build"
+   }
+   ```
+
+   > Скрипты `react-intlayer` основаны на [CRACO](https://craco.js.org/). Вы также можете реализовать свою собственную настройку на основе плагина intlayer craco. [Смотрите пример здесь](https://github.com/aymericzip/intlayer/blob/main/examples/react-app/craco.config.js).
+
+Теперь выполнение `npm run build`, `yarn build` или `pnpm build` запускает как сборку Intlayer, так и CRA.
+
+## Конфигурация TypeScript
+
+**Intlayer** предоставляет **автоматически сгенерированные определения типов** для вашего контента. Чтобы гарантировать, что TypeScript их подберет, добавьте **`types`** (или `types`, если вы настроили иначе) в массив **include** вашего `tsconfig.json`:
+
+```json5 title="tsconfig.json"
+{
+  "compilerOptions": {
+    // ...
+  },
+  "include": ["src", "types"],
+}
+```
+
+> Это позволит TypeScript выводить тип ваших переводов для лучшей автозавершения и обнаружения ошибок.
+
+## Конфигурация Git
+
+Рекомендуется **игнорировать** автоматически сгенерированные файлы и папки от Intlayer. Добавьте эту строку в ваш `.gitignore`:
+
+```plaintext
+# Игнорировать файлы, сгенерированные Intlayer
+.intlayer
+i18next
+```
+
+Вы обычно **не** коммитите эти ресурсы или внутренние артефакты сборки `.intlayer`, так как их можно сгенерировать при каждой сборке.

package/blog/ru/intlayer_with_react-intl.md

@@ -0,0 +1,325 @@
+---
+createdAt: 2025-01-02
+updatedAt: 2025-06-29
+title: Intlayer и react-intl
+description: Интегрируйте Intlayer с react-intl для React-приложения
+keywords:
+  - react-intl
+  - Intlayer
+  - Интернационализация
+  - Документация
+  - Next.js
+  - JavaScript
+  - React
+slugs:
+  - blog
+  - intlayer-with-react-intl
+---
+
+# React Internationalization (i18n) с **react-intl** и Intlayer
+
+Этот гид показывает, как интегрировать **Intlayer** с **react-intl** для управления переводами в приложении React. Вы будете объявлять ваши переводимые данные с помощью Intlayer, а затем использовать эти сообщения с **react-intl**, популярной библиотекой из экосистемы [FormatJS](https://formatjs.io/docs/react-intl).
+
+## Обзор
+
+- **Intlayer** позволяет хранить переводы в **файлах декларации контента** уровня компонента (JSON, JS, TS и т.д.) внутри вашего проекта.
+- **react-intl** предоставляет компоненты React и хуки (такие как `<FormattedMessage>` и `useIntl()`) для отображения локализованных строк.
+
+Настраивая Intlayer на **экспорт** переводов в **формат, совместимый с react-intl**, вы можете автоматически **генерировать** и **обновлять** файлы сообщений, которые требуется `<IntlProvider>` (из react-intl).
+
+---
+
+## Почему использовать Intlayer с react-intl?
+
+1. **Декларации контента на уровне компонента**  
+   Файлы декларации контента Intlayer могут находиться рядом с вашими компонентами React, предотвращая «сиротские» переводы, если компоненты перемещаются или удаляются. Например:
+
+   ```bash
+   .
+   └── src
+       └── components
+           └── MyComponent
+               ├── index.content.ts   # Декларация контента Intlayer
+               └── index.tsx          # Компонент React
+   ```
+
+2. **Централизованные переводы**  
+   Каждый файл декларации контента собирает все переводы, необходимые для компонента. Это особенно полезно в проектах TypeScript: отсутствующие переводы можно выявить во время **компиляции**.
+
+3. **Автоматическая сборка и регенерация**  
+   Каждый раз, когда вы добавляете или обновляете переводы, Intlayer регенерирует файлы сообщений JSON. Затем вы можете передать их в `<IntlProvider>` от react-intl.
+
+---
+
+## Установка
+
+В типичном проекте React установите следующее:
+
+```bash
+# с npm
+npm install intlayer react-intl
+
+# с yarn
+yarn add intlayer react-intl
+
+# с pnpm
+pnpm add intlayer react-intl
+```
+
+### Почему эти пакеты?
+
+- **intlayer**: Основная CLI и библиотека, которая сканирует декларации контента, объединяет их и создает выходные словари.
+- **react-intl**: Основная библиотека от FormatJS, которая предоставляет `<IntlProvider>`, `<FormattedMessage>`, `useIntl()` и другие примитивы интернационализации.
+
+> Если у вас еще не установлен React, вам тоже нужно это сделать (`react` и `react-dom`).
+
+## Настройка Intlayer для экспорта сообщений react-intl
+
+В корне вашего проекта создайте **`intlayer.config.ts`** (или `.js`, `.mjs`, `.cjs`) следующим образом:
+
+```typescript title="intlayer.config.ts"
+import { Locales, type IntlayerConfig } from "intlayer";
+
+const config: IntlayerConfig = {
+  internationalization: {
+    // Добавьте столько локалей, сколько хотите
+    locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
+    defaultLocale: Locales.ENGLISH,
+  },
+  content: {
+    // Указывает Intlayer на генерацию файлов сообщений для react-intl
+    dictionaryOutput: ["react-intl"],
+
+    // Директория, в которую Intlayer будет записывать ваши файлы JSON сообщений
+    reactIntlMessagesDir: "./react-intl/messages",
+  },
+};
+
+export default config;
+```
+
+> **Примечание**: Для других расширений файлов (`.mjs`, `.cjs`, `.js`) смотрите [документацию Intlayer](https://intlayer.org/ru/doc/concept/configuration) для получения деталей использования.
+
+---
+
+## Создание деклараций контента Intlayer
+
+Intlayer сканирует вашу кодовую базу (по умолчанию, в `./src`) на наличие файлов, соответствующих `*.content.{ts,tsx,js,jsx,mjs,mjx,cjs,cjx,json}`.  
+Вот пример на **TypeScript**:
+
+```typescript title="src/components/MyComponent/index.content.ts"
+import { t, type Dictionary } from "intlayer";
+
+const content = {
+  // "key" становится ключом верхнего уровня сообщения в вашем файле JSON react-intl
+  key: "my-component",
+
+  content: {
+    // Каждый вызов t() объявляет переводимое поле
+    helloWorld: t({
+      en: "Hello World",
+      fr: "Bonjour le monde",
+      es: "Hola Mundo",
+    }),
+    description: t({
+      en: "This is a description",
+      fr: "Ceci est une description",
+      es: "Esta es una descripción",
+    }),
+  },
+} satisfies Dictionary;
+
+export default content;
+```
+
+Если вы предпочитаете JSON или разные варианты JS (`.cjs`, `.mjs`), структура в значительной степени такая же , смотрите [документацию Intlayer по декларациям контента](https://intlayer.org/ru/doc/concept/content).
+
+---
+
+## Сборка сообщений для react-intl
+
+Чтобы сгенерировать фактические файлы JSON сообщений для **react-intl**, выполните:
+
+```bash
+# с npm
+npx intlayer dictionaries build
+
+# с yarn
+yarn intlayer build
+
+# с pnpm
+pnpm intlayer build
+```
+
+Это сканирует все файлы `*.content.*`, компилирует их и записывает результаты в директорию, указанную в вашем **`intlayer.config.ts`** , в этом примере, `./react-intl/messages`.  
+Типичный вывод может выглядеть так:
+
+```bash
+.
+└── react-intl
+    └── messages
+        ├── en.json
+        ├── fr.json
+        └── es.json
+```
+
+Каждый файл является объектом JSON, верхние ключи которого соответствуют каждому **`content.key`** из ваших деклараций. Подключи (например, `helloWorld`) отражают переводы, объявленные в этом элементе контента.
+
+Например, **en.json** может выглядеть так:
+
+```json fileName="react-intl/messages/en/my-component.json"
+{
+  "helloWorld": "Hello World",
+  "description": "This is a description"
+}
+```
+
+---
+
+## Инициализация react-intl в вашем приложении React
+
+### 1. Загрузка сгенерированных сообщений
+
+Где вы настраиваете корневой компонент вашего приложения (например, `src/main.tsx` или `src/index.tsx`), вам нужно:
+
+1. **Импортировать** сгенерированные файлы сообщений (статически или динамически).
+2. **Передать** их в `<IntlProvider>` от `react-intl`.
+
+Простой подход , импортировать их **статически**:
+
+```typescript title="src/index.tsx"
+import React from "react";
+import ReactDOM from "react-dom/client";
+import { IntlProvider } from "react-intl";
+import App from "./App";
+
+// Импортировать JSON файлы из выходных данных сборки.
+// Альтернатива: вы можете импортировать динамически в зависимости от выбранной локали пользователем.
+import en from "../react-intl/messages/en.json";
+import fr from "../react-intl/messages/fr.json";
+import es from "../react-intl/messages/es.json";
+
+// Если у вас есть механизм для определения языка пользователя, установите его здесь.
+// Для простоты давайте выберем английский.
+const locale = "en";
+
+// Соберите сообщения в объекте (или выберите их динамически)
+const messagesRecord: Record<string, Record<string, any>> = {
+  en,
+  fr,
+  es,
+};
+
+ReactDOM.createRoot(document.getElementById("root") as HTMLElement).render(
+  <React.StrictMode>
+    <IntlProvider locale={locale} messages={messagesRecord[locale]}>
+      <App />
+    </IntlProvider>
+  </React.StrictMode>
+);
+```
+
+> **Совет**: Для реальных проектов вы можете:
+>
+> - Динамически загружать сообщения JSON во время выполнения.
+> - Использовать основанную на окружении, браузере или учетной записи пользователя детекцию локали.
+
+### 2. Используйте `<FormattedMessage>` или `useIntl()`
+
+Как только ваши сообщения загружены в `<IntlProvider>`, любой дочерний компонент может использовать react-intl для доступа к локализованным строкам. Есть два основных подхода:
+
+- **`<FormattedMessage>`** компонент
+- **`useIntl()`** хук
+
+---
+
+## Использование переводов в компонентах React
+
+### Подход A: `<FormattedMessage>`
+
+Для быстрого использования в пределах строки:
+
+```tsx title="src/components/MyComponent/index.tsx"
+import React from "react";
+import { FormattedMessage } from "react-intl";
+
+export default function MyComponent() {
+  return (
+    <div>
+      <h1>
+        {/* “my-component.helloWorld” ссылается на ключ из en.json, fr.json и т.д. */}
+        <FormattedMessage id="my-component.helloWorld" />
+      </h1>
+
+      <p>
+        <FormattedMessage id="my-component.description" />
+      </p>
+    </div>
+  );
+}
+```
+
+> Проп в **`id`** в `<FormattedMessage>` должен соответствовать **ключу верхнего уровня** (`my-component`) плюс любым под-ключам (`helloWorld`).
+
+### Подход B: `useIntl()`
+
+Для более динамичного использования:
+
+```tsx title="src/components/MyComponent/index.tsx"
+import React from "react";
+import { useIntl } from "react-intl";
+
+export default function MyComponent() {
+  const intl = useIntl();
+
+  return (
+    <div>
+      <h1>{intl.formatMessage({ id: "my-component.helloWorld" })}</h1>
+      <p>{intl.formatMessage({ id: "my-component.description" })}</p>
+    </div>
+  );
+}
+```
+
+Оба подхода допустимы , выбирайте тот стиль, который лучше подходит вашему приложению.
+
+---
+
+## Обновление или добавление новых переводов
+
+1. **Добавьте или измените** контент в любом файле `*.content.*`.
+2. Повторно выполните `intlayer build`, чтобы регенерировать файлы JSON в `./react-intl/messages`.
+3. React (и react-intl) будут подбирать обновления в следующий раз, когда вы пересоберете или перезагрузите ваше приложение.
+
+---
+
+## Интеграция TypeScript (по желанию)
+
+Если вы используете TypeScript, Intlayer может **генерировать определения типов** для ваших переводов.
+
+- Убедитесь, что `tsconfig.json` включает вашу папку `types` (или любую другую выходную папку, которую генерирует Intlayer) в массиве `"include"`.
+
+```json5
+{
+  "compilerOptions": {
+    // ...
+  },
+  "include": ["src", "types"],
+}
+```
+
+Сгенерированные типы могут помочь выявлять отсутствующие переводы или недействительные ключи в ваших компонентах React на этапе компиляции.
+
+---
+
+## Конфигурация Git
+
+Обычно **исключаются** внутренние артефакты сборки Intlayer из контроля версий. В вашем `.gitignore` добавьте:
+
+```plaintext
+# Игнорировать артефакты сборки intlayer
+.intlayer
+react-intl
+```
+
+В зависимости от вашего рабочего процесса, вы также можете захотеть игнорировать или коммитить окончательные словари в `./react-intl/messages`. Если ваш CI/CDipeline регенерирует их, их можно безопасно игнорировать; в противном случае коммитите их, если они вам нужны для оберток в производства.