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

<Meta title='@dxtmisha/ru/functional-basic/Classes/TranslateFile - Управление Файлами Перевода'/>

# Класс TranslateFile

Класс для управления данными переводов из внешних файлов. Поддерживает ленивую загрузку (lazy loading) пакетов перевода, автоматическое сопоставление локалей и внутреннее кэширование для оптимизации производительности.

В отличие от статических утилит, `TranslateFile` является экземпляром класса, что позволяет создавать несколько наборов переводов с независимыми настройками локали и местоположения.

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

- **Ленивая загрузка** — поддерживает асинхронную загрузку файлов перевода только тогда, когда они необходимы для текущей локали.
- **Умное кэширование** — автоматически кэширует содержимое загруженных файлов, предотвращая повторное чтение файлов или лишние сетевые запросы.
- **Приоритизация локалей** — интеллектуально выбирает наиболее подходящий файл на основе местоположения (Местоположение > Язык > Глобальное).
- **Гибкий контекст** — поддерживает настраиваемые поставщики местоположения и языка, по умолчанию используя глобальные настройки `Geo`.

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

Для инициализации объекта вызовите конструктор `TranslateFile(data, language, location)`.

**Параметры:**
- `data?: TranslateDataFile` — начальное сопоставление локалей и загрузчиков файлов.
- `language: string | (() => string) = () => Geo.getLanguage()` — текущий язык или функция, возвращающая его.
- `location: string | (() => string) = () => Geo.getLocation()` — текущее местоположение или функция, возвращающая его.

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

// 1. Простая инициализация
const files = new TranslateFile({
  'en-US': () => import('./locales/en-US.json'),
  'en': () => import('./locales/en.json'),
  'global': () => import('./locales/global.json')
})

// 2. Использование пользовательских провайдеров контекста
const customFiles = new TranslateFile(
  {}, 
  () => 'fr', 
  () => 'fr-FR'
)
```

## Методы

### Получение данных

- `async getList(): Promise<TranslateDataFileList | undefined>` — Возвращает список переводов для текущего местоположения. Сначала проверяет внутренний кэш, затем пытается загрузить данные через зарегистрированные загрузчики.
- `isFile(): boolean` — Проверяет, есть ли зарегистрированные загрузчики файлов, применимые к текущему местоположению или языку.
- `getLocation(): string` — Возвращает текущую строку местоположения (выполняет поставщика, если это функция).
- `getLanguage(): string` — Возвращает текущую строку языка (выполняет поставщика, если это функция).

### Управление данными

- `add(data: TranslateDataFile): void` — Добавляет сопоставление локалей и соответствующих им функций-загрузчиков (функций, возвращающих Promise).

## Типы

### `TranslateDataFile`
Коллекция асинхронных функций-загрузчиков, индексированных строками локали/региона:
- **Ключ**: Код локали (например, `'en-US'`, `'ru'`, `'global'`).
- **Значение**: Функция, возвращающая `Promise` с `TranslateDataFileList`.

### `TranslateDataFileList`
Простой объект перевода (ключ-значение): `Record<string, string>`.

## Примеры

### Интеграция с TranslateInstance

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

const translationFiles = new TranslateFile({
  'en-US': () => Promise.resolve({ hello: 'Hello US' }),
  'en': () => Promise.resolve({ hello: 'Привет' })
})

const translate = new TranslateInstance(
  '/api/translate',
  'list',
  translationFiles
)

const message = await translate.get('hello')
```
