# PRD — Telegram Mini App: Bilingual (EN + FA)

**Status:** Ready to implement  
**Scope:** `src/sections/telegram/telegram-mini-app-shell.tsx` only  
**Depends on:** Telegram Mini App redesign (done — commit `integrate-main-into-development`)  
**Estimated effort:** 1 day

---

## 1. Goal

The Telegram Mini App currently renders English only. Persian (Farsi) users — the primary audience — see the app in a language they don't use day-to-day in Telegram. This PRD specifies full EN ↔ FA bilingual support with automatic language detection and a manual toggle.

---

## 2. Language Detection (priority order)

1. **Telegram's `language_code`** — `shellContext.initDataUnsafe?.user?.language_code` — if `"fa"` or `"fa-IR"`, default to Persian
2. **localStorage key** `amn_tg_lang` — user's last manual selection, persists across sessions
3. **Fallback** — English

Detection runs once on mount. Manual toggle overwrites and persists to localStorage.

---

## 3. String Inventory (all strings to translate)

### Loading state
| Key | EN | FA |
|---|---|---|
| `loading.session` | Loading session… | در حال بارگذاری… |
| `loading.signin` | Signing in… | در حال ورود… |

### Unsupported state
| Key | EN | FA |
|---|---|---|
| `unsupported.badge` | MINI APP ONLY | فقط مینی‌اپ |
| `unsupported.title` | Open in Telegram | در تلگرام باز کنید |
| `unsupported.body` | This view is designed for the Telegram Mini App. Use the web dashboard from a browser. | این صفحه برای مینی‌اپ تلگرام طراحی شده است. از مرورگر به داشبورد وب دسترسی داشته باشید. |
| `unsupported.cta_web` | Open Web Dashboard | باز کردن داشبورد وب |
| `unsupported.cta_signin` | Sign In | ورود |

### Unlinked / sign-in state
| Key | EN | FA |
|---|---|---|
| `unlinked.badge` | ESCROW · HELD IN TRUST | امانت · در امانت نگه‌داشته |
| `unlinked.body` | Link your Telegram session to access escrow requests, payments, and secure messaging. | حساب تلگرام خود را متصل کنید تا به درخواست‌های امانت، پرداخت‌ها و پیام‌رسانی امن دسترسی داشته باشید. |
| `unlinked.cta_telegram` | Continue with Telegram | ادامه با تلگرام |
| `unlinked.cta_signing_in` | Signing in… | در حال ورود… |
| `unlinked.cta_email` | Sign in with email | ورود با ایمیل |
| `unlinked.cta_create` | Create an account | ساخت حساب |

### Header
| Key | EN | FA |
|---|---|---|
| `header.subtitle` | MINI APP | مینی‌اپ |

### Home content
| Key | EN | FA |
|---|---|---|
| `home.banner.badge` | ESCROW ACCOUNT | حساب امانت |
| `home.banner.welcome` | Welcome back, {name} | خوش آمدید، {name} |
| `home.banner.cta` | New Escrow Request | درخواست امانت جدید |
| `home.actions.requests.label` | Open Requests | درخواست‌های باز |
| `home.actions.requests.desc` | Browse and negotiate active escrow requests | مرور و مذاکره درخواست‌های امانت فعال |
| `home.actions.payments.label` | Payments & Escrow | پرداخت‌ها و امانت |
| `home.actions.payments.desc` | Track payments, release funds, view history | پیگیری پرداخت‌ها، آزادسازی وجه، مشاهده تاریخچه |
| `home.actions.chat.label` | Request Chat | گفتگوی درخواست |
| `home.actions.chat.desc` | Continue conversations on active requests | ادامه مکالمات روی درخواست‌های فعال |
| `home.chips.badge` | ESCROW STATES | وضعیت‌های امانت |

### Status chips (bilingual labels)
| State | EN | FA |
|---|---|---|
| Held | Held | نگهداری شده |
| Shipping | Shipping | در حال ارسال |
| Released | Released | آزاد شد |
| Pending | Pending | در انتظار |
| Disputed | Disputed | اختلاف |
| Cancelled | Cancelled | لغو شد |

### Tab bar
| Key | EN | FA |
|---|---|---|
| `tabs.home` | Home | خانه |
| `tabs.requests` | Requests | درخواست‌ها |
| `tabs.chat` | Chat | گفتگو |
| `tabs.account` | Account | حساب |

### MainButton (Telegram native)
| Key | EN | FA |
|---|---|---|
| `main.new_request` | New Request | درخواست جدید |
| `main.sign_in` | Sign In | ورود |

### Onboarding sheet
| Key | EN | FA |
|---|---|---|
| `onboarding.title` | Account linked | حساب متصل شد |
| `onboarding.subtitle` | Your Telegram session is ready | حساب تلگرام شما آماده است |
| `onboarding.body` | Add your wallet, notification preferences, and payment details any time from Account Settings. | تنظیمات کیف پول، اعلان‌ها و جزئیات پرداخت را هر زمان از تنظیمات حساب اضافه کنید. |
| `onboarding.cta_settings` | Account Settings | تنظیمات حساب |
| `onboarding.cta_later` | Later | بعداً |

---

## 4. Layout Changes for RTL (Persian)

| Element | LTR | RTL |
|---|---|---|
| Root `dir` attribute | `ltr` | `rtl` |
| Font family | `var(--sans)` = IBM Plex Sans | `var(--sans-fa)` = Vazirmatn |
| Arrow icon in action list | `→` (arrowRight) | `←` (arrowLeft) |
| Tab bar order | Home · Requests · Chat · Account | خانه · درخواست‌ها · گفتگو · حساب (same order, text RTL) |
| Banner welcome text | left-aligned | right-aligned (inherits from dir=rtl) |
| Chip list | left-to-right wrap | right-to-left wrap (inherits) |

**Font size bumps for Persian:** Body text 13px → 14px, labels 10px → 11px (Vazirmatn renders slightly smaller at the same size).

---

## 5. Language Toggle UI

A small toggle in the header, right side:

```
[ EN | فا ]
```

- Two buttons side by side, mono font
- Active language: ink-900 background, cream text
- Inactive: transparent, ink-600 text
- Width: auto (narrow) — doesn't displace the logo
- On tap: haptic light + switch language + persist to localStorage

---

## 6. Translations Object Structure

```ts
const TR = {
  en: { loading: {...}, unsupported: {...}, unlinked: {...}, header: {...}, home: {...}, tabs: {...}, onboarding: {...}, main: {...} },
  fa: { /* same keys */ },
};
```

All access via `t.home.banner.cta` pattern — no template literals in JSX, only in the translations object.

---

## 7. Files Changed

| File | Change |
|---|---|
| `src/sections/telegram/telegram-mini-app-shell.tsx` | All string extraction + RTL layout + lang detection + toggle |

No new files required. No routing changes. No backend changes.

---

## 8. Definition of Done

- [ ] Language auto-detected from `initDataUnsafe.user.language_code` on mount
- [ ] Manual toggle persists to `localStorage` key `amn_tg_lang`
- [ ] All 40+ strings translated (see table above)
- [ ] `dir="rtl"` applied to root `.tg-shell` when lang is `fa`
- [ ] Vazirmatn font active for Persian (already loaded via Google Fonts in `SHELL_CSS`)
- [ ] Arrow icons flip direction in RTL
- [ ] Tab labels translate correctly
- [ ] Telegram `MainButton` text updates when lang switches
- [ ] No TypeScript errors
- [ ] Tested in browser at `/telegram` with `?lang=fa` param override for dev preview