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

# Ассеты

> Настройка баннеров, переводов и логотипа QR-кода Remnashop

## Баннеры

Бот поддерживает кастомные баннеры для каждой страницы и локали. Поддерживаемые названия страниц: `menu`, `dashboard`, `subscription`, `promocode`, `referral`, `default`.

Поддерживаемые форматы: `jpg`, `jpeg`, `png`, `gif`, `webp`.

Баннеры загружаются из двух источников с разным приоритетом:

1. **Ваши баннеры** — `/opt/remnashop/assets/banners/` (высший приоритет)
2. **Встроенные баннеры бота** — `assets.default/banners/` внутри Docker-образа (запасной вариант)

Чтобы **использовать свой баннер**, поместите файл в `assets/banners/` — он автоматически получит приоритет над встроенным. Чтобы **использовать встроенный баннер**, просто не размещайте файл.

### Порядок поиска баннера

При загрузке баннера система ищет файл в следующем порядке.

**Пользовательский том (`assets/banners/`):**

1. `banners/{locale_пользователя}/{страница}` — страничный баннер для локали пользователя
2. `banners/{locale_пользователя}/default` — дефолтный баннер для локали пользователя
3. `banners/{locale_по_умолчанию}/{страница}` — страничный баннер для локали по умолчанию
4. `banners/{locale_по_умолчанию}/default` — дефолтный баннер для локали по умолчанию
5. `banners/default` — глобальный запасной баннер пользователя

**Встроенные баннеры (`assets.default/banners/`, внутри образа):**

6. `banners/{locale_пользователя}/{страница}` — встроенный страничный баннер
7. `banners/default` — встроенный глобальный баннер (последний запасной вариант)

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

* **Одно изображение для всего** — разместите единственный файл `banners/default.jpg`
* **Своё изображение для каждой локали** — разместите `banners/{locale}/default.jpg` для каждой локали
* **Изображения для каждой страницы** — разместите `banners/{locale}/{страница}.jpg` для каждой страницы и локали

### Пример структуры файлов

```
banners/
├── default.jpg             ← глобальный запасной баннер для всех страниц и локалей
├── ru/
│   ├── default.jpg         ← дефолтный баннер для всех страниц в локали ru
│   ├── menu.jpg
│   └── subscription.jpg
└── en/
    ├── default.jpg
    └── menu.jpg
```

> [!NOTE]
>
> Если вы не разместите ни одного баннера, бот использует встроенные баннеры из образа. Свой файл `banners/default.jpg` задаёт глобальный запасной баннер для всех страниц и локалей.

***

## Переводы

Переводы загружаются из двух источников с разным приоритетом:

1. **Ваши переопределения** — `/opt/remnashop/assets/translations/{locale}/custom.ftl` (высший приоритет)
2. **Встроенные переводы бота** — `assets.default/translations/{locale}/*.ftl` внутри Docker-образа (запасной вариант для всех остальных ключей)

Что это означает:

* Новые ключи, появившиеся в обновлении бота, доступны автоматически — никаких действий не требуется.
* Ваши переопределения в `custom.ftl` никогда не затрагиваются обновлениями.
* Чтобы переопределить любой встроенный ключ, добавьте его в `custom.ftl` со своим переводом.

> [!NOTE]
>
> Встроенные файлы (`buttons.ftl`, `messages.ftl`, `notifications.ftl`, `events.ftl`, `utils.ftl`) находятся внутри образа и всегда соответствуют версии бота. Редактировать их в пользовательском томе не нужно — достаточно `custom.ftl`.

### Файл `custom.ftl`

В каждой папке локали может быть файл `custom.ftl` (например, `translations/ru/custom.ftl`). Он используется как для **переопределения** встроенных ключей, так и для **собственных** строк — названий планов, дополнительных кнопок меню и т.п.

Добавляйте пары «ключ — значение» в синтаксисе Fluent:

```ftl theme={"dark"}
# Переопределение встроенного ключа
btn-menu-connect = 🚀 Подключиться

# Свои кнопки меню
custom-menu-link1 = 1️⃣ Первая кнопка
custom-menu-link2 = 2️⃣ Вторая кнопка

# Свои названия планов
custom-plan-name1 = 1️⃣ Базовый план
custom-plan-name2 = 2️⃣ Премиум план
```

Чтобы избежать конфликтов со встроенными ключами, собственные ключи рекомендуется начинать с префикса `custom-`.

| Контекст | Максимальная длина |
| - | - |
| Кнопки | 32 символа |
| Сообщения | 1024 символа |

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

```bash Перезапуск контейнера theme={"dark"}
cd /opt/remnashop && docker compose down && docker compose up -d
```

> [!WARNING]
>
> Переопределяя встроенный ключ в `custom.ftl`, вы фиксируете и его переменные (плейсхолдеры). Если в обновлении бота этот ключ изменится — добавится, переименуется или исчезнет переменная — ваш перевод перестанет соответствовать актуальному ключу, и при отрисовке сообщения может возникнуть ошибка.
>
> Поэтому после каждого обновления проверяйте, менялись ли переводы, и при необходимости приводите свои переопределения в `custom.ftl` в соответствие с актуальными ключами. В каждом релизе указывается, затрагивались ли переводы.
>
> Сравнить переводы между версиями можно в [истории папки переводов на GitHub](https://github.com/snoups/remnashop/commits/main/assets/translations) или через сравнение тегов, например [`v0.7.5...v0.8.0`](https://github.com/snoups/remnashop/compare/v0.7.5...v0.8.0).

***

## Логотип QR-кода

Вы можете добавить кастомный логотип в центр генерируемых QR-кодов приглашений.

* **Путь:** `assets/logo.png`
* **Формат:** PNG, желательно с прозрачным фоном

Если файл существует, он автоматически будет наложен в центр каждого сгенерированного QR-кода.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.