> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mastermindcms.com/llms.txt
> Use this file to discover all available pages before exploring further.

# TranslationManager

> Хелперы переводов, которые экспортирует msm-components

`TranslationManager` оборачивает i18next и добавляет хелперы для получения переводов из MastermindCMS.

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

Перед использованием `translate()` один раз задайте путь к JSON с локалями:

```js theme={null}
setLocalesPath("/path/to/locales/{{lng}}.json");
```

В реальном приложении путь указывает на публичные JSON-файлы локализации, например:

```js theme={null}
import { setLocalesPath } from "msm-components/dist/services.js";

setLocalesPath("/admin/assets/locales/{{lng}}.json");
```

Шаблон `{{lng}}` заменяется текущим кодом языка. Инициализацию достаточно выполнить один раз при старте приложения.

## Экспорты

Через `msm-components` можно использовать:

* `setLocalesPath(loadPath)`
* `translate(...args)`
* `translations` (proxy для ленивого доступа к переводам)
* `tr(key, repository?)` (загружает/возвращает один перевод)
* `loadTranslation(key, repository?)`
* `loadManyTranslations(...keys)`
* `loadByLangCodeForEntity(entityId, lang, repository?)`
* `loadByLangCode(key, lang)`
* `loadTranslationById(id)`
* `clearTranslationsCache()`
* `getLanguages()`
* `getAlphabetForActiveLanguage()`

## Примеры использования

`translate` работает асинхронно и совместим с ключами и опциями i18next:

```js theme={null}
import {
  setLocalesPath,
  translate,
} from "msm-components/dist/services.js";

setLocalesPath("/assets/locales/{{lng}}.json");

const title = await translate("DashboardTitle");
const greeting = await translate("Greeting", { name: "Alex" });
```

Для нескольких ключей используйте один вызов `loadManyTranslations`:

```js theme={null}
import { loadManyTranslations } from "msm-components/dist/services.js";

const texts = await loadManyTranslations(
  "UserConfirmationDialogTitle",
  "UserConfirmationButtonOk",
  "AbortButton"
);

console.log(texts.UserConfirmationButtonOk);
```

`tr` и `translations` предназначены для ленивой загрузки переводов из репозитория:

```js theme={null}
import { tr, translations } from "msm-components/dist/services.js";

const label = await tr("SaveButton");
const cancelLabel = await translations.CancelButton;
```

Для перевода конкретной сущности с явным языком используйте `loadByLangCodeForEntity`:

```js theme={null}
import { loadByLangCodeForEntity } from "msm-components/dist/services.js";

const text = await loadByLangCodeForEntity(entityId, "de");
```

## Примечания

* Если `setLocalesPath()` не был вызван, функции переводов выбросят ошибку, чтобы проблема конфигурации была сразу заметна.
* Внутри используется универсальный механизм сервисных вызовов (service/repository), поэтому это опирается на инстанс встроенного клиента, который предоставляет `msm-components`.
* Кэш переводов можно сбросить через `clearTranslationsCache()`, например после смены набора локалей.