import {Meta} from '@storybook/addon-docs/blocks'

<Meta title='@dxtmisha/ru/functional-basic/Classes/Translate - Управление Переводами и Текстами'/>

# Класс Translate

Статическая обертка для стандартного экземпляра класса `TranslateInstance`. Он управляет переводами и локализованным текстом на глобальном уровне, предоставляя инструменты для получения, кэширования и отображения контента с поддержкой шаблонов и автоматическим определением локали.

## Связь с TranslateInstance

Класс `Translate` выступает в роли глобального, предварительно настроенного интерфейса для `TranslateInstance`. Все статические методы вызывают соответствующие методы внутреннего экземпляра (`Translate.getItem()`).

Хотя `Translate` подходит для большинства общесистемных нужд перевода, вы можете создавать независимые среды перевода, используя `TranslateInstance`.

## Ключевые особенности

- **Пакетная загрузка** — интеллектуально группирует запросы на перевод, отправляя их одним паком через 160 мс после постановки в очередь.
- **Гибкие шаблоны** — поддерживает замену параметров в тексте как по индексам (`[0]`), так и по именованным ключам (`{key}`).
- **Синхронный и асинхронный доступ** — методы для мгновенного получения текста из кэша (`getSync`) или гарантированной загрузки с сервера (`get`).
- **Умный кэш** — хранит переводы с учетом текущей локали и поддерживает фоллбэки (Местоположение > Язык > Глобально).

## Инициализация

Класс является статическим и не требует создания экземпляра. Конфигурация применяется к глобальному экземпляру перевода.

```javascript
import { Translate } from '@dxtmisha/functional-basic'

// Настройка URL API для глобального экземпляра
Translate.setUrl('/api/v1/translate')

// Предварительная загрузка необходимых текстов
await Translate.add(['welcome', 'auth.login'])
```

## Методы

### Конфигурация

- `setConfig(config: TranslateConfig): Translate` — Устанавливает полную конфигурацию для экземпляра перевода.
- `setUrl(url: string): Translate` — Изменяет адрес API для получения переводов.
- `setPropsName(name: string): Translate` — Изменяет имя свойства, используемое в API-запросе/ответе.
- `setReadApi(value: boolean): Translate` — Включает или отключает получение переводов из API.

### Получение переводов

- `async get(name: string, replacement?: any): Promise<string>` — Асинхронно получает текст. Если его нет в кэше и мы не на localhost, пытается загрузить его с сервера.
- `getSync(name: string, first?: boolean, replacement?: any): string` — Возвращает текст из кэша. Если `first` равен `true`, вернет пробел ` `, если текст отсутствует.
- `async getList<T>(names: T): Promise<TranslateList<T>>` — Получает группу переводов (асинхронно).
- `getListSync<T>(names: T, first?: boolean): TranslateList<T>` — Получает группу переводов из кэша (синхронно).

### Групповое обновление

- `async add(names: string | string[]): Promise<void>` — Добавляет несколько кодов в очередь для пакетной загрузки.
- `addSync(data: Record<string, string>): void` — Напрямую добавляет переводы в кэш.
- `async addNormalOrSync(data: Record<string, string>): Promise<void>` — Добавляет переводы напрямую на localhost, иначе ставит их в очередь на загрузку.
- `addSyncByLocation(data: Record<string, Record<string, string>>): void` — Добавляет переводы для определенных локаций/местоположений.
- `addSyncByFile(data: TranslateDataFile): void` — Добавляет переводы из определения файла.

### Статика vs Экземпляр

- **Использование**: Глобальный доступ к `Translate` из любой точки приложения или локализованные, независимые экземпляры `TranslateInstance`.
- **Состояние**: Состояние `Translate` разделяется между всем приложением, тогда как `TranslateInstance` обеспечивает изолированное состояние для конкретных компонентов или модулей.
- **Создание**: `Translate` не требует создания экземпляра (статическая обертка), а `TranslateInstance` создается через `new TranslateInstance()`.

## Отдельные экземпляры

Если вам нужно управлять отдельным набором переводов (например, для конкретного подприложения или специализированного виджета), используйте `TranslateInstance` вместо глобального класса `Translate`.

```javascript
import { TranslateInstance, TranslateFile } from '@dxtmisha/functional-basic'

// 1. Создаем специализированный набор файлов переводов
const widgetFiles = new TranslateFile({
  'ru-RU': () => import('./locales/widget.ru-RU.json')
})

// 2. Инициализируем отдельный экземпляр перевода
const widgetTranslate = new TranslateInstance(
  '/api/widget/translate', 
  'list', 
  widgetFiles
)

// 3. Используем независимо
const label = await widgetTranslate.get('widget.welcome')
```

## Типы

### `TranslateCode`
Строка (имя кода) или массив строк. Массивы используются для замены в шаблонах:
- `string` — например, `'welcome'`
- `string[]` — например, `['welcome', 'Гость']`

### `TranslateList`
Объект, в котором ключи — коды переводов, а значения — итоговые переведенные строки.

## Примеры

### Работа с шаблонами
```javascript
// В базе: "Привет, [0]! У вас {count} уведомлений."
const text = await Translate.get('user.notifications', ['Иван', { count: 5 }])
// Результат: "Привет, Иван! У вас 5 уведомлений."
```

### Групповое получение списка
```javascript
const labels = await Translate.getList([
  'home.title',
  ['home.welcome', 'Гость'], 
  'home.footer'
])
```