@intlayer/docs 5.7.7 → 5.8.0-canary.0

package/docs/ru/CI_CD.md

@@ -1,8 +1,8 @@
 ---
 createdAt: 2025-05-20
-updatedAt: 2025-06-29
+updatedAt: 2025-08-13
 title: Интеграция CI/CD
-description: Узнайте, как интегрировать Intlayer в ваш CI/CD процесс для автоматизированного управления контентом и развертывания.
+description: Узнайте, как интегрировать Intlayer в ваш CI/CD конвейер для автоматизированного управления контентом и развертывания.
 keywords:
   - CI/CD
   - Непрерывная интеграция
@@ -17,13 +17,13 @@ slugs:
   - ci-cd
 ---
 
-# Автоматическая генерация переводов в CI/CD процессе
+# Автоматическая генерация переводов в CI/CD конвейере
 
 Intlayer позволяет автоматически генерировать переводы для ваших файлов декларации контента. Существует несколько способов достичь этого в зависимости от вашего рабочего процесса.
 
 ## Использование CMS
 
-С Intlayer вы можете использовать рабочий процесс, при котором локально объявляется только один язык, а все переводы управляются удаленно через CMS. Это позволяет полностью отделить контент и переводы от кодовой базы, обеспечивая большую гибкость для редакторов контента и позволяя горячую перезагрузку контента (нет необходимости пересобирать приложение для применения изменений).
+С Intlayer вы можете использовать рабочий процесс, при котором локально объявляется только одна локаль, а все переводы управляются удаленно через CMS. Это позволяет полностью отделить контент и переводы от кодовой базы, обеспечивая большую гибкость для редакторов контента и позволяя горячую перезагрузку контента (нет необходимости пересобирать приложение для применения изменений).
 
 ### Пример конфигурации
 
@@ -33,7 +33,7 @@ import { Locales, type IntlayerConfig } from "intlayer";
 const config: IntlayerConfig = {
   internationalization: {
     locales: [Locales.ENGLISH, Locales.SPANISH, Locales.FRENCH],
-    requiredLocales: [Locales.ENGLISH], // Необязательные языки будут управляться удаленно
+    requiredLocales: [Locales.ENGLISH], // Необязательные локали будут управляться удаленно
     defaultLocale: Locales.ENGLISH,
   },
   editor: {
@@ -45,7 +45,7 @@ const config: IntlayerConfig = {
     clientSecret: process.env.INTLAYER_CLIENT_SECRET,
   },
   ai: {
-    applicationContext: "Это тестовое приложение", // Помогает обеспечить согласованность генерации перевода
+    applicationContext: "This is a test application", // Помогает обеспечить согласованное создание переводов
   },
 };
 
@@ -66,7 +66,7 @@ import { Locales, type IntlayerConfig } from "intlayer";
 const config: IntlayerConfig = {
   internationalization: {
     locales: [Locales.ENGLISH, Locales.SPANISH, Locales.FRENCH],
-    requiredLocales: [Locales.ENGLISH], // Необязательные локали обрабатываются удаленно
+    requiredLocales: [Locales.ENGLISH], // Необязательные локали обрабатываются удалённо
     defaultLocale: Locales.ENGLISH,
   },
   editor: {
@@ -75,9 +75,9 @@ const config: IntlayerConfig = {
   },
   ai: {
     provider: "openai",
-    apiKey: process.env.OPENAI_API_KEY, // Используйте свой собственный API ключ
+    apiKey: process.env.OPENAI_API_KEY, // Используйте свой собственный API-ключ
 
-    applicationContext: "Это тестовое приложение", // Помогает обеспечить согласованность генерации перевода
+    applicationContext: "This is a test application", // Помогает обеспечить согласованное создание переводов
   },
 };
 
@@ -85,11 +85,11 @@ export default config;
 ```
 
 ```bash fileName=".husky/pre-push"
-npx intlayer build                          # Чтобы убедиться, что словари обновлены
+npx intlayer build                          # Чтобы словари были актуальными
 npx intlayer fill --unpushed --mode fill    # Заполняет только отсутствующий контент, не обновляет существующий
 ```
 
-> Для получения дополнительной информации о командах Intlayer CLI и их использовании, обратитесь к [документации CLI](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ru/intlayer_cli.md).
+> Для получения дополнительной информации о командах Intlayer CLI и их использовании обратитесь к [документации CLI](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ru/intlayer_cli.md).
 
 > Если у вас несколько приложений в репозитории, использующих отдельные экземпляры intlayer, вы можете использовать аргумент `--base-dir` следующим образом:
 
@@ -108,65 +108,91 @@ npx intlayer fill --base-dir ./app2 --unpushed --mode fill
 Intlayer предоставляет команду CLI для автоматического заполнения и проверки содержимого словаря. Это можно интегрировать в ваш CI/CD процесс с использованием GitHub Actions.
 
 ```yaml fileName=".github/workflows/intlayer-translate.yml"
-name: Intlayer Auto-Fill
+name: Intlayer Автозаполнение
+# Условия запуска этого workflow
 on:
-  push:
-    branches: [ main ]
-    paths:
-      - 'src/**'
   pull_request:
-    branches: [ main ]
-    paths:
-      - 'src/**'
-  workflow_dispatch: {}
+    branches:
+      - "main"
+
+permissions:
+  contents: write
+  pull-requests: write
 
 concurrency:
-  group: 'autofill-${{ github.ref }}'
+  group: "autofill-${{ github.ref }}"
   cancel-in-progress: true
 
 jobs:
   autofill:
     runs-on: ubuntu-latest
     env:
-      INTLAYER_CLIENT_ID: ${{ secrets.INTLAYER_CLIENT_ID }}
-      INTLAYER_CLIENT_SECRET: ${{ secrets.INTLAYER_CLIENT_SECRET }}
-      OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
+      # OpenAI
+      AI_MODEL: openai
+      AI_PROVIDER: gpt-5-mini
+      AI_API_KEY: ${{ secrets.AI_API_KEY }}
 
     steps:
-      - name: ⬇️ Клонировать репозиторий
-        uses: actions/checkout@v3
+      # Шаг 1: Получить последний код из репозитория
+      - name: ⬇️ Проверка репозитория
+        uses: actions/checkout@v4
         with:
-          persist-credentials: true
+          persist-credentials: true # Сохранять учетные данные для создания PR
+          fetch-depth: 0 # Получить полную историю git для анализа изменений
 
-      - name: 🟢 Установить Node.js
-        uses: actions/setup-node@v3
+      # Шаг 2: Настроить окружение Node.js
+      - name: 🟢 Настроить Node.js
+        uses: actions/setup-node@v4
         with:
-          node-version: 20
+          node-version: 20 # Использовать Node.js 20 LTS для стабильности
 
+      # Шаг 3: Установить зависимости проекта
       - name: 📦 Установить зависимости
-        run: npm ci
+        run: npm install
+
+      # Шаг 4: Глобально установить Intlayer CLI для управления переводами
+      - name: 📦 Установить Intlayer
+        run: npm install -g intlayer-cli
 
+      # Шаг 5: Собрать проект Intlayer для генерации файлов перевода
       - name: ⚙️ Собрать проект Intlayer
         run: npx intlayer build
 
-      - name: 🤖 Автоматически заполнить отсутствующие переводы
-        run: npx intlayer fill --git-diff --mode fill
-
-      - name: 📤 Создать или обновить PR с переводами
-        uses: peter-evans/create-pull-request@v4
-        with:
-          commit-message: chore: авто-заполнение отсутствующих переводов [skip ci]
-          branch: auto-translations
-          title: chore: обновить отсутствующие переводы
-          labels: translation, automated
+      # Шаг 6: Использовать ИИ для автоматического заполнения отсутствующих переводов
+      - name: 🤖 Автоматическое заполнение отсутствующих переводов
+        run: npx intlayer fill --git-diff --mode fill --provider $AI_PROVIDER --model $AI_MODEL --api-key $AI_API_KEY
+
+      # Шаг 7: Проверить наличие изменений и зафиксировать их
+      - name: � Проверить изменения
+        id: check-changes
+        run: |
+          if [ -n "$(git status --porcelain)" ]; then
+            echo "has-changes=true" >> $GITHUB_OUTPUT
+          else
+            echo "has-changes=false" >> $GITHUB_OUTPUT
+          fi
+
+      # Шаг 8: Зафиксировать и отправить изменения, если они есть
+      - name: 📤 Зафиксировать и отправить изменения
+        if: steps.check-changes.outputs.has-changes == 'true'
+        run: |
+          git config --local user.email "action@github.com"
+          git config --local user.name "GitHub Action"
+          git add .
+          git commit -m "chore: автоматическое заполнение отсутствующих переводов [skip ci]"
+          git push origin HEAD:${{ github.head_ref }}
 ```
 
+Чтобы настроить переменные окружения, перейдите в GitHub → Settings → Secrets and variables → Actions и добавьте секрет .
+
 > Аналогично Husky, в случае монорепозитория вы можете использовать аргумент `--base-dir` для последовательной обработки каждого приложения.
 
-> По умолчанию аргумент `--git-diff` фильтрует словари, которые включают изменения от базы (по умолчанию `origin/main`) до текущей ветки (по умолчанию: `HEAD`).
+> По умолчанию аргумент `--git-diff` фильтрует словари, которые содержат изменения от базы (по умолчанию `origin/main`) до текущей ветки (по умолчанию: `HEAD`).
 
 > Для получения дополнительной информации о командах Intlayer CLI и их использовании обратитесь к [документации CLI](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ru/intlayer_cli.md).
 
-## История документа
+## История документации
 
-- 5.5.10 - 2025-06-29: Инициализация истории
+| Версия | Дата       | Изменения             |
+| ------ | ---------- | --------------------- |
+| 5.5.10 | 2025-06-29 | Инициализация истории |

package/docs/ru/formatters.md

@@ -0,0 +1,239 @@
+---
+createdAt: 2024-08-13
+updatedAt: 2025-08-20
+title: Форматтеры
+description: Утилиты для форматирования с учетом локали на основе Intl для чисел, процентов, валюты, дат, относительного времени, единиц измерения и компактной записи. Включает кешированный помощник Intl.
+keywords:
+  - Форматтеры
+  - Intl
+  - Число
+  - Валюта
+  - Процент
+  - Дата
+  - Относительное время
+  - Единицы измерения
+  - Компактный формат
+  - Интернационализация
+slugs:
+  - doc
+  - formatters
+---
+
+# Форматтеры Intlayer
+
+## Обзор
+
+Intlayer предоставляет набор легковесных помощников, построенных поверх нативных API `Intl`, а также кешированный обертку `Intl`, чтобы избежать повторного создания тяжелых форматтеров. Эти утилиты полностью учитывают локаль и могут использоваться из основного пакета `intlayer`.
+
+### Импорт
+
+```ts
+import {
+  Intl,
+  number,
+  percentage,
+  currency,
+  date,
+  relativeTime,
+  units,
+  compact,
+} from "intlayer";
+```
+
+Если вы используете React, хуки также доступны; смотрите `react-intlayer/format`.
+
+## Кешированный Intl
+
+Экспортируемый `Intl` — это тонкая кешированная обертка вокруг глобального `Intl`. Она мемоизирует экземпляры `NumberFormat`, `DateTimeFormat`, `RelativeTimeFormat`, что позволяет избежать повторного создания одного и того же форматтера.
+
+Поскольку создание форматтера относительно дорогостоящее, такое кеширование улучшает производительность без изменения поведения. Обертка предоставляет тот же API, что и нативный `Intl`, поэтому использование идентично.
+
+- Кеширование происходит на уровне процесса и прозрачно для вызывающих.
+
+> Если `Intl.DisplayNames` недоступен в среде, выводится одно предупреждение только для разработчиков (рекомендуется использовать полифилл).
+
+Пример:
+
+```ts
+import { Intl } from "intlayer";
+
+const numberFormat = new Intl.NumberFormat("en-GB", {
+  style: "currency",
+  currency: "GBP",
+});
+numberFormat.format(1234.5); // "£1,234.50"
+```
+
+## Форматтеры
+
+Все приведённые ниже помощники экспортируются из `intlayer`.
+
+### `number(value, options?)`
+
+Форматирует числовое значение с учётом локальных правил группировки и десятичных знаков.
+
+- **value**: `number | string`
+- **options**: `Intl.NumberFormatOptions & { locale?: LocalesValues }`
+
+Примеры:
+
+```ts
+import { number } from "intlayer";
+
+number(123456.789); // "123,456.789" (в en-US)
+number("1000000", { locale: "fr" }); // "1 000 000"
+number(1234.5, { minimumFractionDigits: 2 }); // "1,234.50"
+```
+
+### `percentage(value, options?)`
+
+Форматирует число в строку с процентами.
+
+Поведение: значения больше 1 интерпретируются как целые проценты и нормализуются (например, `25` → `25%`, `0.25` → `25%`).
+
+- **value**: `number | string`
+- **options**: `Intl.NumberFormatOptions & { locale?: LocalesValues }`
+
+Примеры:
+
+```ts
+import { percentage } from "intlayer";
+
+percentage(0.25); // "25%"
+percentage(25); // "25%"
+percentage(0.237, { minimumFractionDigits: 1 }); // "23.7%"
+```
+
+### `currency(value, options?)`
+
+Форматирует значение как локализованную валюту. По умолчанию используется `USD` с двумя десятичными знаками.
+
+- **value**: `number | string`
+- **options**: `Intl.NumberFormatOptions & { locale?: LocalesValues }`
+  - Общие поля: `currency` (например, `"EUR"`), `currencyDisplay` (`"symbol" | "code" | "name"`)
+
+Примеры:
+
+```ts
+import { currency } from "intlayer";
+
+currency(1234.5, { currency: "EUR" }); // "€1,234.50"
+currency("5000", { locale: "fr", currency: "CAD", currencyDisplay: "code" }); // "5 000,00 CAD"
+```
+
+### `date(date, optionsOrPreset?)`
+
+Форматирует значение даты/времени с помощью `Intl.DateTimeFormat`.
+
+- **date**: `Date | string | number`
+- **optionsOrPreset**: `Intl.DateTimeFormatOptions & { locale?: LocalesValues }` или один из предустановленных вариантов:
+  - Предустановки: `"short" | "long" | "dateOnly" | "timeOnly" | "full"`
+
+Примеры:
+
+```ts
+import { date } from "intlayer";
+
+date(new Date(), "short"); // например, "08/02/25, 14:30"
+date("2025-08-02T14:30:00Z", { locale: "fr", month: "long", day: "numeric" }); // "2 août"
+```
+
+### `relativeTime(from, to = new Date(), options?)`
+
+Форматирует относительное время между двумя моментами с помощью `Intl.RelativeTimeFormat`.
+
+- Передайте "now" в качестве первого аргумента, а целевое время — вторым, чтобы получить естественную формулировку.
+- **from**: `Date | string | number`
+- **to**: `Date | string | number` (по умолчанию `new Date()`)
+- **options**: `{ locale?: LocalesValues; unit?: Intl.RelativeTimeFormatUnit; numeric?: Intl.RelativeTimeFormatNumeric; style?: Intl.RelativeTimeFormatStyle }`
+  - По умолчанию `unit` — `"second"`.
+
+Примеры:
+
+```ts
+import { relativeTime } from "intlayer";
+
+const now = new Date();
+const in3Days = new Date(now.getTime() + 3 * 864e5);
+relativeTime(now, in3Days, { unit: "day" }); // "через 3 дня"
+
+const twoHoursAgo = new Date(now.getTime() - 2 * 3600e3);
+relativeTime(now, twoHoursAgo, { unit: "hour", numeric: "auto" }); // "2 часа назад"
+```
+
+### `units(value, options?)`
+
+Форматирует числовое значение как локализованную строку с единицей измерения, используя `Intl.NumberFormat` с `style: 'unit'`.
+
+- **value**: `number | string`
+- **options**: `Intl.NumberFormatOptions & { locale?: LocalesValues }`
+  - Общие поля: `unit` (например, `"kilometer"`, `"byte"`), `unitDisplay` (`"short" | "narrow" | "long"`)
+  - Значения по умолчанию: `unit: 'day'`, `unitDisplay: 'short'`, `useGrouping: false`
+
+Примеры:
+
+```ts
+import { units } from "intlayer";
+
+units(5, { unit: "kilometer", unitDisplay: "long", locale: "en-GB" }); // "5 kilometers"
+units(1024, { unit: "byte", unitDisplay: "narrow" }); // "1,024B" (зависит от локали)
+```
+
+### `compact(value, options?)`
+
+Форматирует число, используя компактную нотацию (например, `1.2K`, `1M`).
+
+- **value**: `number | string`
+- **options**: `Intl.NumberFormatOptions & { locale?: LocalesValues }` (использует `notation: 'compact'` под капотом)
+
+Примеры:
+
+```ts
+import { compact } from "intlayer";
+
+compact(1200); // "1.2K"
+compact("1000000", { locale: "fr", compactDisplay: "long" }); // "1 миллион"
+```
+
+## Примечания
+
+- Все вспомогательные функции принимают входные данные в виде `string`; они внутренне приводятся к числам или датам.
+- Локаль по умолчанию берется из вашей настройки `internationalization.defaultLocale`, если не указана явно.
+- Эти утилиты являются тонкими обертками; для расширенного форматирования используйте стандартные опции `Intl`.
+
+## Точки входа и реэкспорты (`@index.ts`)
+
+Форматтеры находятся в основном пакете и реэкспортируются из пакетов более высокого уровня для удобства импорта в разных средах выполнения:
+
+Примеры:
+
+```ts
+// Код приложения (рекомендуется)
+import { number, currency, date, Intl } from "intlayer";
+```
+
+### React
+
+Клиентские компоненты:
+
+```ts
+import { useNumber, useCurrency, useDate } from "react-intlayer/format";
+// или в приложениях Next.js
+import { useNumber, useCurrency, useDate } from "next-intlayer/client/format";
+```
+
+Серверные компоненты (или React Server runtime):
+
+```ts
+import { useNumber, useCurrency, useDate } from "intlayer/server/format";
+// или в приложениях Next.js
+import { useNumber, useCurrency, useDate } from "next-intlayer/server/format";
+```
+
+> Эти хуки будут учитывать локаль из `IntlayerProvider` или `IntlayerServerProvider`
+
+## История документации
+
+| Версия | Дата       | Изменения                             |
+| ------ | ---------- | ------------------------------------- |
+| 5.8.0  | 2025-08-18 | Добавлена документация по форматтерам |