audit: 2026-05-30 full-codebase audit — report, issues, docs, runbooks
Full-codebase-audit 2026-05-30 outputs: - Audit report: 09 - Audits/Full Codebase Audit - 2026-05-30.md - 81 issue files ISSUE-055..135 (decisions + 1 skipped no-brainer). - Scanner docs from scratch (was zero): architecture, data model, API ref, payment flow, operations runbook + repo README. - Doc-sync updates across API reference, data models, flows, design system. - Secret Rotation Runbook (08 - Operations) for the exposed credentials. - Reusable workflow guide (07 - Development) + .claude/workflows/full-codebase-audit.js. Issues remain status:open intentionally — the code fixes are uncommitted-then-committed working-tree changes per repo and aren't "resolved" until merged/deployed. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
Siavash Sameni
172
PRD - Telegram Mini App Bilingual (EN + FA).md
Normal file
172
PRD - Telegram Mini App Bilingual (EN + FA).md
Normal file
@@ -0,0 +1,172 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user