Repository navigation
User Interface
The interface is 100% right-to-left Persian, with Persian numerals throughout. This is not a localisation pass over an English layout — the RTL direction is structural, and the geometry of every screen is asserted by the test suite.
| Element | Behaviour |
|---|---|
| File name label | Shows the opened book, or "هیچ فایلی انتخاب نشده است". |
| ⚙️ تنظیمات | Opens the settings dialog. |
| 📂 انتخاب کتاب (PDF / EPUB) | Opens the file dialog. |
| Element | Behaviour |
|---|---|
| ◀ صفحه بعد | Next page. Disabled when there is no document or the last page is reached. |
صفحه: ۰ / ۰ |
The page counter, in Persian digits. |
| صفحه قبل ▶ | Previous page. Disabled on the first page. |
| 📋 کپی | Copies the current page's translation. Blue when the page has a translation, grey when it does not — the state is visible without reading the tooltip. |
| 💾 ذخیره | Opens the three-item export menu. |
| 🚀 ترجمهٔ این صفحه | Translates the current page. |
| 📚 ترجمهٔ کل کتاب | Opens the batch dialog. |
The page-navigation buttons carry the RTL arrow convention: "next" points left
(◀) and "previous" points right(▶), because in a right-to-left layout that is
the direction of travel.
Two combo boxes — 🌐 زبان مبدأ and زبان مقصد — with a double lock: changing either one automatically sets the other, so the two can never become the same language. The hint under them reads:
تعویض هر کدام، دیگری را خودکار تنظیم می‌کند و در همهٔ کتاب‌ها می‌ماند.
The chosen direction is stored in the configuration, so it survives restarts and applies to every book.
| Element | Behaviour |
|---|---|
| 📝 نمایش متن مبدأ | Toggles the source panel between the rendered page image and the extracted text. The button's own label swaps accordingly. |
| ✓ بازبینی شد (تأیید انسانی) | Marks the current page as human-approved. The tooltip explains that the mark is counted in the statistics and the final output. |
| Statistics label | Live counts of translated vs. reviewed pages for the current book. |
| Element | Behaviour |
|---|---|
| ⏸ توقف | Pauses the running translation. Enabled only while something is running. |
| ■ لغو | Cancels safely. Every finished page stays saved. |
| Status label | Progress messages such as "صفحهٔ ۱۲ — تکهٔ ۲ از ۴". |
| Progress bar | Indeterminate (setRange(0, 0)) — its internal text was removed because Qt drew it on the left, which is wrong in RTL. |
| Percentage label |
۰٪ … ۱۰۰٪, in Persian digits, right-aligned, with a minimum width of 48 px so the number does not jitter as it changes. |
Two side-by-side panels:
- Right — the source: the rendered page image, or the extracted text when toggled.
- Left — the translation, in a scroll area.
The comment in the source explains the ordering: in an RTL layout, the first item in a horizontal layout is placed on the right, so the source panel is added first and lands on the right — the position a Persian reader expects the original text to occupy.
This is the feature that makes a long batch run bearable.
When a batch starts, the app sets _following_batch = True and displays the page
currently being translated — the image or the extracted text — as the worker
progresses through the book.
The critical detail: page navigation stays fully unlocked during a batch. You can browse to any page, read an earlier translation, or look at a chapter you have not reached yet, while the batch keeps running.
The moment you navigate, the app sets _following_batch = False and stops moving
the view for you. The batch does not stop — only the auto-follow does. The source
states the rule plainly:
اگر کاربر خودش جابجا شده باشد (_following_batch=False) دیگر مزاحم نمی‌شویم.
So the app never yanks the view back to the page it is translating while you are reading something else. The follow resumes only when a new batch starts.
"📚 ترجمهٔ خودکار کل کتاب" — minimum width 560, organised in numbered sections.
- کل کتاب (N صفحه) — the whole book, selected by default.
-
محدودهٔ خاصی از صفحات — a specific range, with two spin boxes
(از صفحهٔ / تا صفحهٔ) whose values are right-aligned by a dedicated
_SpinAlignFilter, re-applied onShow,StyleChange,Polish,FontChange, andApplicationPaletteChangeevents — because Qt re-lays-out spin boxes on theme changes and loses the alignment.
When the job already has saved pages, the dialog shows the count in cyan and offers the two radio buttons described in Job Store and Resume. "ادامه از اولین صفحهٔ ناتمام" is pre-selected.
| Option | Default | Notes |
|---|---|---|
| تحلیل ساختار کتاب و Template اختصاصی آن (محلی و رایگان) | On | Local, free structure detection. |
| بازبینی و اصلاح خودکار ترجمه (QC loop) — پیشنهادی؛ هزینهٔ API دو برابر | On | The dialog states the doubled cost in the label itself. |
| تاخیر بین درخواست‌ها | 0 s | 0–30 seconds, for rate-limited providers. |
A live estimate line updates whenever the range or the restart choice changes, and the button row is weighted by visual importance: the start button is filled and prominent, the cancel button is neutral.
"⚙️ تنظیمات" — see Settings Reference for every field.
Two things are worth calling out here:
- The data folder path is displayed in monospace, selectable with the mouse, next to an "📂 باز کردن پوشه" button. Where the user's translations and their encrypted key live is never hidden.
- A dedicated "🧪 تست اتصال" button runs a real request through
ApiTestWorkerand reports the outcome — so a wrong model name or a bad key is discovered before a 300-page run starts, not 40 pages in.
System / Dark / Light, selected in the settings. The theme is applied across the whole application, and the dark theme is the reason the app's default text colours are the slate/blue palette rather than pure black and white.
These are not stylistic preferences — the test suite asserts them:
| Convention | Implementation |
|---|---|
| Persian numerals |
fa_number(value) translates ASCII digits to ۰۱۲۳۴۵۶۷۸۹ via a translation table. |
| Spin-box alignment |
align_spin_value_right plus _SpinAlignFilter to survive re-styling. |
| Progress direction | The percentage label is right-aligned; the progress bar's internal text is hidden. |
| Arrow direction | "Next" points left, "previous" points right. |
| Panel order | The source panel is added first, so in RTL it lands on the right. |
| Status colours | Cyan for progress, green for the percentage, with per-state button styling. |
- Settings Reference — every setting and its default.
- Job Store and Resume — the review marks and the statistics.
- Exports and Output — the save menu.