Files

Siavash Sameni dceaf82934 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>

2026-05-30 18:48:04 +04:00

7.1 KiB

Raw Blame History

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)

Telegram's language_code — shellContext.initDataUnsafe?.user?.language_code — if "fa" or "fa-IR", default to Persian
localStorage key amn_tg_lang — user's last manual selection, persists across sessions
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	ورود

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

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

7.1 KiB Raw Blame History