# DigiDala — Alpha 50.9 Bot Localization & Branding Audit

## 1. Baseline

Source reviewed: `bot/bot.cjs` from the Alpha 50.9 localization stage package.

Scope of this audit:

- full RU/EN localization of the Telegram bot;
- localization architecture parallel to the Mini App;
- removal of remaining user-facing PixDala branding;
- preservation of the existing Telegram bot account, username and token;
- preservation of bot/admin/Competitive/payment mechanics.

Current Telegram identity decision:

- Display name: `DigiDala` — already changed in BotFather.
- Username: `@PixDala_bot` — keep unchanged.
- Token: keep the existing token.
- Existing separate `DigiDala` bot: do not delete during this stage; it is not used by the project.

## 2. Critical defect found in Alpha 50.9

`bot/bot.cjs` currently tries to load:

```text
__dirname/apps/miniapp/i18n/locales.mjs
```

Because `__dirname` is `.../bot`, the runtime resolves this as:

```text
.../bot/apps/miniapp/i18n/locales.mjs
```

The actual file is under the release root:

```text
.../apps/miniapp/i18n/locales.mjs
```

This causes the bot to crash during startup with `ERR_MODULE_NOT_FOUND`.

The fix must not make the bot depend directly on Mini App source files.

## 3. Target localization architecture

Recommended structure:

```text
packages/i18n/
    locales.mjs              # supported locale metadata

apps/miniapp/i18n/
    index.mjs
    ru.mjs
    en.mjs

bot/i18n/
    index.mjs
    ru.mjs
    en.mjs
```

The supported-locale registry is shared; the UI dictionaries remain application-specific.

Bot locale selection:

1. saved manual preference for the Telegram user;
2. Telegram `language_code` (`ru` -> Russian);
3. English fallback.

Manual selector:

```text
/language
→ 🇬🇧 English
→ 🇷🇺 Русский
```

The preference belongs to the Telegram user and must not be stored in the bot process memory only.

## 4. Current user-facing bot surfaces

### Public entry

Current hard-coded content includes:

- welcome message;
- About message;
- main menu labels;
- Support label;
- help response;
- app/menu response;
- payment amount selection;
- payment cancellation;
- payment success/failure messages;
- `myid` response.

### Main menu

Current RU labels include:

- `🪷 Открыть DigiDala`
- `🎨 Малая мандала творчества`
- `🎨 Большая мандала творчества`
- `🏁 Мандалы состязаний`
- `✨ Особые мандалы`
- `ℹ️ О нас`
- `⭐ Поддержать проект`

These must move to the bot dictionary.

### Commands

Current command descriptions are hard-coded in Russian:

- `/start` — `Открыть DigiDala`
- `/app` — `Открыть меню DigiDala`
- `/help` — `Помощь`

They should be registered per supported locale while keeping command identifiers unchanged.

### Support/payment

Current user-facing texts include:

- `Поддержать DigiDala`
- `Выберите сумму:`
- `Поддержка отменена.`
- `Добровольная поддержка проекта на N ⭐...`
- `Поддержка проекта`
- payment verification errors
- successful payment confirmations
- delayed payment-processing confirmation.

All move to the bot i18n dictionary. Numeric values and payment data remain dynamic values.

### Admin menu

Current RU texts include:

- `🔐 Администрирование DigiDala`
- `Выберите действие:`
- `➕ Новая мандала состязаний`
- `📋 Очередь мандал`
- `✏️ Основное сообщение`
- `ℹ️ Сообщение «О нас»`
- `👥 Администраторы`
- `✖️ Закрыть`
- `Операция отменена.`
- administration error/status messages.

The admin interface must use the same locale system as the public bot surface.

### Competitive creation

Current RU flow is hard-coded across multiple steps:

1. left artwork request;
2. right artwork request;
3. size selection;
4. Pix price entry;
5. localized title entry;
6. localized description entry;
7. preview;
8. queue confirmation;
9. success/error output.

The **campaign content itself is already separated into localized records**, which is the correct foundation. The bot UI around that flow still needs localization.

### Competitive editing

Current RU flow includes:

- campaign not found;
- edit menu;
- price editing;
- locale selection;
- title editing;
- description editing;
- validation errors;
- success/error confirmations.

All must move to i18n.

### Administrator management

Current RU flow includes:

- administrator list;
- empty-list text;
- `/admin_add` syntax help;
- `/admin_remove` syntax help;
- role validation;
- add/remove success messages;
- permission/update errors.

All must move to i18n.

## 5. Existing mixed-language / architecture issues

### A. `bot.cjs` directly imports Mini App locale metadata

This is the Alpha 50.9 startup defect and must be removed.

### B. Campaign locale metadata and bot UI locale metadata are coupled

`CAMPAIGN_LOCALES` currently comes directly from the Mini App locale module.

Target: both applications read the shared supported-locale registry, while the bot remains independent of Mini App implementation files.

### C. Welcome/About are stored as one text value

Current bot settings contain `welcome_message` and `about_message` as single values.

For a fully localized bot, these should become locale-aware settings:

```text
bot_content_localizations
    key
    locale
    text
```

The existing admin editing capability must remain; only its presentation model becomes localized.

### D. `/help` is not an independent help surface

The current handler sends the welcome message and menu for `/help`.

This is a separate UX/copy issue from translation. The localization implementation should preserve existing behavior unless we explicitly approve a new Help text later.

### E. Campaign fallback must remain explicit

Legacy campaigns may have only the old `title`/`description` fields. The bot should treat those as legacy fallback data rather than silently presenting them as an actual translation.

New campaigns must continue to collect all supported campaign locales.

## 6. Branding cleanup

User-facing occurrences of `PixDala` should be audited and changed to `DigiDala` where they are product-facing.

Keep technical identifiers unchanged for now:

- `@PixDala_bot`
- `TELEGRAM_BOT_TOKEN`
- GitHub repository name
- `/opt/pixdala/...`
- `pixdala-bot.service`
- internal API/database identifiers.

The display name is already `DigiDala`, so no token/account migration is required for this branding cleanup.

## 7. Functional invariants

The bot localization/branding release must not change:

- Telegram bot account or token;
- polling;
- Mini App URL/deep links;
- payment creation, pre-checkout or completion;
- Pix amounts and accounting;
- Competitive campaign queue mechanics;
- artwork validation and storage;
- admin roles and authorization rules;
- backend API contracts;
- campaign lifecycle;
- archive behavior.

## 8. Implementation checkpoint (historical)

The implementation checkpoint proposed by this audit became `v0.4.0-alpha.50.9.1`.

```text
v0.4.0-alpha.50.9.1
```

Scope:

1. remove the broken Mini App-relative import from the bot;
2. add shared locale metadata;
3. add bot RU/EN dictionaries;
4. add automatic locale detection + persistent manual preference;
5. localize public bot UI;
6. localize admin UI;
7. localize payment/support UI;
8. localize command descriptions;
9. move bot welcome/about content to locale-aware storage;
10. finish user-facing `PixDala` -> `DigiDala` cleanup;
11. add runtime/import regression coverage so a successful syntax check cannot hide this class of startup failure.

No functional feature is to be removed or redesigned as part of this checkpoint.

## 9. Release audit findings closed

- `bot/content/set` now rejects unsupported locale codes instead of silently normalizing them to English.
- Migration 017 preserves existing administrator-edited legacy `welcome_message` and `about_message` values as Russian content while replacing untouched system defaults with the approved Alpha 50.9.1 Russian copy.
- Competitive creation confirmation resolves the displayed campaign title through the active bot locale.
- Final Alpha.50.9.1 automated verification: Structure OK, JavaScript syntax OK, Unit 42/42, Integration 49/49, API 17/17 (108/108 total).

## 9. Approved public bot copy

The public `/start` welcome text, support/payment wording, menu labels and the `/language` control were approved in RU/EN before implementation.

The final `About DigiDala` text was also approved. Its structure is:

1. why the project uses the mandala ritual as its idea;
2. the current simplified implementation;
3. the future goal of bringing the experience closer to a real mandala-making ritual;
4. DigiDala as a collaborative creativity/digital-ritual space;
5. Creative, Competitive and Special Mandalas;
6. the future visual-donation-platform direction;
7. Pix and the archive.

The approved Competitive description is:

RU: `Мандалы состязаний — соревнование двух сторон, каждая из которых постепенно открывает своё изображение клетка за клеткой.`

EN: `Competitive Mandalas — a competition between two sides, each gradually revealing its image cell by cell.`

## 10. Final release closeout

- Alpha.50.9.1 was committed as `3200550`, tagged `v0.4.0-alpha.50.9.1` and deployed successfully to `/opt/pixdala/releases/v0.4.0-alpha.50.9.1`.
- Manual Telegram QA passed for RU/EN language detection, saved language preference and localized bot content.
- The approved Russian `О нас` text was restored through the administrator content editor after legacy test-database content was observed; no code change was required for that runtime correction.
- Alpha.50.9.2 subsequently closed the two follow-up QA defects: literal `\n` sequences in system-default welcome text and the need to invoke `/start` again after changing language.