📖 knh-12 — çeviri tamamlandı

.github/workflows/qa.yml

@@ -31,12 +31,21 @@ on:
         type: boolean
         default: false
 
-# NOT: Bu, ana çeviri hattından (translate.yml/queue-worker.yml/review.yml)
-# BİLEREK ayrı ve sadece elle (workflow_dispatch) tetiklenen bir araç —
-# Gemini'nin ücretsiz katmanı Groq'a göre çok daha kısıtlı (RPM/RPD), bu
-# yüzden otomatik/periyodik bir güvenlik ağına bağlanmıyor. Ne QA raporu
-# ne de seri önerisi hiçbir çeviri dosyasını OTOMATİK değiştirmez — bkz.
-# qa_audit.py ve series_suggest.py docstring'leri.
+# NOT (Eylül 2026): Eskiden bu workflow ana çeviri hattından (translate.yml/
+# queue-worker.yml/review.yml) BİLEREK ayrı tutulur, sadece elle
+# (workflow_dispatch) tetiklenirdi — gerekçe: Gemini'nin ücretsiz katmanı
+# Groq'a göre çok daha kısıtlı (RPM/RPD), otomatik bir güvenlik ağına
+# bağlamanın kotayı gereksiz yere hızla tüketeceği düşünülmüştü.
+# Artık review.yml bitince BU workflow'u kendisi tetikliyor (bkz.
+# review.py) VE translate.yml'in periyodik güvenlik ağı da status.json'daki
+# qa_status alanına bakıp "review bitti ama QA bitmedi" durumunu görünce
+# bunu dürtüyor — bu ikinci kısım tam olarak istenen şeyi çözüyor: Gemini
+# günlük kotası tükenip iş yarım kalırsa (qa_audit.py zaten checkpoint'li,
+# .qa_progress.json ile kaldığı yerden devam ediyor), bir sonraki periyodik
+# tetiklemede (kota sıfırlandıktan sonra) otomatik devam eder — elle
+# tekrar tetiklemeye gerek kalmaz. Gemini kotası ENDİŞESİ hâlâ geçerli
+# ama artık checkpoint'li devam ettiği için tekrar denemeler ucuz (zaten
+# denetlenmiş bölümleri yeniden taramıyor).
 jobs:
   qa-audit:
     runs-on: ubuntu-latest
@@ -72,6 +81,23 @@ jobs:
           git config user.name "${{ steps.app-token.outputs.app-slug }}[bot]"
           git config user.email "${{ steps.app-token.outputs.app-slug }}[bot]@users.noreply.github.com"
 
+      # Periyodik güvenlik ağının (translate.py:_scan_and_nudge_active_books)
+      # "QA bitmedi mi, o zaman dürt" diye tekrar tekrar boşu boşuna
+      # tetiklememesi için, bu işin BAŞLADIĞINI hemen işaretliyoruz. is_stale
+      # kontrolü (diğer *_status alanlarıyla aynı desen) güvenlik ağının,
+      # gerçekten çakılmış bir run'ı normal çalışan bir run'dan ayırt
+      # etmesini sağlıyor.
+      - name: Mark QA running
+        run: |
+          python3 -c "
+          import json, os, sys
+          sys.path.insert(0, 'scripts')
+          from lib.git_utils import write_status
+          status = json.load(open('status.json', encoding='utf-8')) if os.path.exists('status.json') else {}
+          status['qa_status'] = 'running'
+          write_status(status, 'qa: başladı')
+          "
+
       # series/<slug>.json genelde main'de yaşıyor (bkz. lib/series.py) —
       # bu dal onu içermiyorsa, öneri script'inin "zaten var olan" bağlamı
       # görebilmesi için main'den bir kopyasını çekmeyi dene. Yoksa (henüz
@@ -141,6 +167,30 @@ jobs:
           PYTHONUNBUFFERED: "1"
         run: python scripts/apply_qa_fixes.py "${{ inputs.slug }}"
 
+      # NOT (Eylül 2026, gerçek üretim hatası): Bu kontrol eskiden
+      # .qa_progress.json checkpoint dosyasının yokluğuna bakıyordu VE
+      # "Apply QA fixes"ten ÖNCE çalışıyordu. Bu ikisi bir araya gelince
+      # şu hataya yol açtı: skip_audit=true ile (Gemini'yi hiç çalıştırmadan)
+      # tetiklenen bir run'da checkpoint zaten (önceki TAM taramadan)
+      # yoktu — kontrol bunu yanlışlıkla "tamamlandı" sandı ve qa_report.md
+      # hâlâ 15 çözülmemiş madde içerirken convert.yml'i tetikledi.
+      # Artık "qa_report.md'nin kendisi hâlâ var mı" diye bakıyoruz (o da
+      # apply_qa_fixes.py tarafından SADECE gerçekten 0 madde kalınca
+      # siliniyor) VE bunu düzeltmelerden SONRA kontrol ediyoruz — bu,
+      # skip_audit kullanılsa da kullanılmasa da, kalan gerçek durumu
+      # doğru yansıtan tek sinyal.
+      - name: Check QA completion
+        id: qacheck
+        if: always()
+        run: |
+          if [ -f "output/${{ inputs.slug }}/qa_report.md" ]; then
+            echo "complete=false" >> "$GITHUB_OUTPUT"
+            echo "qa_report.md hâlâ duruyor — çözülmemiş madde(ler) var."
+          else
+            echo "complete=true" >> "$GITHUB_OUTPUT"
+            echo "qa_report.md yok — ya hiç sorun bulunmadı ya da hepsi çözüldü."
+          fi
+
       - name: Run series suggestion
         if: inputs.run_series_suggest == true
         env:
@@ -171,3 +221,33 @@ jobs:
           git diff --cached --quiet && echo "Değişiklik yok." && exit 0
           git commit -m "qa: ${{ inputs.slug }} denetim raporu + seri önerisi"
           git push origin HEAD:${{ inputs.branch }}
+
+      # NOT (Eylül 2026): qa_status'u burada, HER durumda (always()) ama
+      # Check QA completion adımının sonucuna göre FARKLI değerle
+      # işaretliyoruz:
+      #  - complete=true  -> "completed" + convert.yml tetiklenir (epub artık
+      #    QA düzeltmeleri UYGULANMIŞ haliyle ciltlenir)
+      #  - complete=false -> "partial" (ASLA "completed" değil) — böylece
+      #    translate.py'nin periyodik güvenlik ağı bunu "hâlâ bitmedi" diye
+      #    görüp bir sonraki taramasında qa.yml'i TEKRAR tetikler; kaldığı
+      #    yerden (checkpoint sayesinde) devam eder. Gemini günlük kotası
+      #    doluysa, bu doğal olarak "ertesi gün otomatik devam etme" etkisini
+      #    verir — periyodik tarama zaten saatlik/günlük aralıklarla çalışıyor.
+      - name: Mark QA status & trigger next step
+        if: always()
+        env:
+          GH_TOKEN: ${{ steps.app-token.outputs.token }}
+        run: |
+          python3 -c "
+          import json, os, sys
+          sys.path.insert(0, 'scripts')
+          from lib.git_utils import write_status
+          status = json.load(open('status.json', encoding='utf-8')) if os.path.exists('status.json') else {}
+          status['qa_status'] = '${{ steps.qacheck.outputs.complete == 'true' && 'completed' || 'partial' }}'
+          write_status(status, 'qa: ${{ steps.qacheck.outputs.complete == 'true' && 'tamamlandı' || 'kısmi, devam edecek' }}')
+          "
+          if [ "${{ steps.qacheck.outputs.complete }}" = "true" ]; then
+            gh workflow run convert.yml -f branch="${{ inputs.branch }}"
+          else
+            echo "QA kısmi kaldı — convert tetiklenmedi. Periyodik güvenlik ağı bir sonraki taramada qa.yml'i tekrar tetikleyecek."
+          fi

README.md

@@ -1,16 +1,97 @@
 # eptran
 
-İngilizce epub dosyalarını Türkçeye çeviren, Groq llama-3.3-70b destekli araç.
+İngilizce epub/pdf dosyalarını Türkçeye çeviren, çok modelli (Groq + Gemini)
+bir GitHub Actions + Vercel aracı.
 
 ## Nasıl Çalışır?
 
-1. epub'u web arayüzünden yüklersin
-2. Dosya repona commit edilir, GitHub Actions tetiklenir
-3. Actions her bölümü Groq llama-3.3-70b ile çevirir
-4. Çeviri tamamlanınca bölümler epub olarak paketlenir
-5. Arayüzden ilerlemeyi takip edebilir, tamamlanınca indirebilirsin
+1. Kitabı web arayüzünden yüklersin.
+2. Sunucu, `main`'e hiç dokunmadan `main`'in ucundan `queue/<kitap-adı>`
+   adında yeni bir dal açar ve dosyayı oraya commit'ler.
+3. Bu dal, kitaba özel bir dal olan `book/<kitap-adı>`'na dönüşür; tüm
+   çeviri süreci SADECE bu dalda ilerler, `main` süreç boyunca hiç
+   etkilenmez.
+4. Groq (qwen3.8-27b) her bölümü çevirir, ardından ikinci bir geçişle
+   gözden geçirir (İngilizce kalıntı/tutarsız terim kontrolü).
+5. Kitap tamamlanınca Gemini tüm kitabı tarayıp bir kalite kontrol
+   raporu (`qa_report.md`) çıkarır; Groq bu rapordaki maddeleri otomatik
+   düzeltmeye çalışır.
+6. Bölümler epub olarak ciltlenir ve `book/<kitap-adı>` dalından `main`'e
+   **tek bir pull request** açılır — sen onaylayıp merge edene kadar
+   `main` değişmez.
+7. Arayüzden ilerlemeyi takip edebilir, tamamlanınca indirebilirsin.
+
+## Mimari Notlar
+
+- **`main` hiçbir zaman otomasyon tarafından doğrudan değiştirilmez.**
+  İstersen `main` için branch protection/ruleset kurabilirsin (PR
+  zorunluluğu, zorunlu status check vb.) — otomasyon akışı buna göre
+  tasarlandı, hiçbir adımı bundan etkilenmez.
+- Yükleme, tarayıcıya kalıcı bir GitHub kimlik bilgisi vermez. Sunucu
+  (Vercel fonksiyonu) kitap başına, sadece bu repoya ve sadece
+  Contents+Actions iznine sahip, ~1 saat sonra kendiliğinden geçersiz
+  olan bir GitHub App kurulum token'ı üretir; dosyanın kendisi
+  tarayıcıdan doğrudan GitHub'a bu token'la yüklenir (Vercel'in
+  fonksiyon başına istek boyutu sınırına takılmamak için).
+- Aynı anda yalnızca bir kitap işlenir — `book/*` ya da `queue/*` önekli
+  bir dal var olduğu sürece yeni yükleme reddedilir.
+- `main`'e giden PR, `pr_check.py` (İngilizce kalıntı taraması + Gemini
+  raporu özeti) tarafından kontrol edilir; bunu zorunlu bir status
+  check olarak ayarlamak istersen workflow adı **"Kitap Bütünlük
+  Kontrolü"**.
+
+## Dosya Yapısı
+
+```
+eptran/
+├── index.html                  # Web arayüzü (yükleme + ilerleme takibi)
+├── api/
+│   ├── upload.js                 # Yükleme: queue/<kitap> dalı açar, geçici
+│   │                              # App token üretir, workflow'u tetikler
+│   └── status.js                 # Arayüzün ilerleme durumunu okuduğu endpoint
+├── scripts/
+│   ├── translate.py               # Ana çeviri döngüsü (bölüm bölüm)
+│   ├── queue_worker.py            # Bir sonraki parçayı işleyip kendini tetikler
+│   ├── review.py                  # İkinci geçiş: İngilizce kalıntı/tutarlılık
+│   ├── qa_audit.py                # Gemini ile tüm kitabı tarayıp qa_report.md üretir
+│   ├── apply_qa_fixes.py          # qa_report.md'deki maddeleri Groq'la düzeltir
+│   ├── series_suggest.py          # Karakter/terim sözlüğü için otomatik öneri
+│   ├── pr_check.py                # main'e giden PR'ı kontrol eder ("Kitap
+│   │                               # Bütünlük Kontrolü" — zorunlu status check)
+│   ├── convert.py                 # Bölümleri epub'a ciltler, PR açar
+│   └── lib/
+│       ├── groq_client.py           # Groq API istemcisi (key rotasyonu, retry)
+│       ├── gemini_client.py         # Gemini API istemcisi
+│       ├── git_utils.py             # Dal açma/yeniden adlandırma, status.json, push
+│       ├── review_fix.py            # review.py'nin whitelist + düzeltme mantığı
+│       ├── english_detector.py      # Sözlük destekli İngilizce kalıntı tespiti
+│       ├── series.py                # Kitaba özel karakter/terim sözlüğü (series/*.json)
+│       ├── memory.py                # Çeviri sırasında öğrenilen isim/terim hafızası
+│       ├── dictionary.py            # Öğrenilen kelimeler (dictionary/learned_words.json)
+│       ├── ner.py                   # Bölüm başına isim/terim çıkarımı
+│       ├── boilerplate.py           # Tekrar eden şablon metinleri tanıma
+│       ├── unicode_cleaner.py       # Model çıktısındaki bozuk karakterleri temizleme
+│       ├── sliding_window.py        # Uzun bölümleri parçalara ayırma
+│       └── pitfalls.py              # common_pitfalls.json'ı sistem prompt'una ekler
+├── .github/workflows/
+│   ├── translate.yml              # Yükleme sonrası ana çeviri workflow'u
+│   ├── queue-worker.yml           # Bölüm/parça bazlı devam workflow'u
+│   ├── review.yml                 # İkinci geçiş workflow'u
+│   ├── qa.yml                     # Gemini denetimi + Qwen düzeltme workflow'u
+│   ├── pr-check.yml               # "Kitap Bütünlük Kontrolü"
+│   └── convert.yml                # Ciltleme + PR açma workflow'u
+├── series/
+│   └── <seri-adı>.json            # Kitaba/seriye özel karakter+terim sözlüğü
+├── dictionary/
+│   └── learned_words.json         # Kitaplar arası öğrenilen kelime hafızası
+├── common_pitfalls.json         # Kitap bağımsız, tekrar eden çeviri hataları
+├── known_proper_nouns.json      # Kitap bağımsız, İngilizce kalması gereken gerçek isimler
+├── status.json                  # main'deki son tamamlanan kitabın durumu
+├── requirements.txt
+└── vercel.json
+```
+
 
-## Kurulum
 
 ### 1. Repoyu Fork'la
 
@@ -20,44 +101,78 @@ Sağ üstten **Fork** butonuna bas.
 
 Fork'ladıktan sonra **Actions** sekmesine gidip etkinleştir.
 
-### 3. GitHub PAT Oluştur
+### 3. Bir GitHub App Oluştur
+
+Otomasyon, kalıcı bir kişisel token yerine bir GitHub App üzerinden
+çalışır (hem GitHub Actions hem Vercel tarafında).
+
+[github.com/settings/apps/new](https://github.com/settings/apps/new)
+adresinden:
+- **Repository permissions:** `Contents` (Read and Write), `Pull
+  requests` (Read and Write), `Actions` (Read and Write)
+- Oluşturduktan sonra **App ID**'yi not al, bir **private key** üret ve
+  indir (`.pem` dosyası)
+- App'i fork'ladığın repoya kur (Install App)
 
-[github.com/settings/tokens](https://github.com/settings/tokens/new) adresinden:
-- **Token adı:** eptran
-- **İzinler:** `Contents` (Read and Write), `Actions` (Write)
+### 4. GitHub Actions Secret'larını Ekle
+
+Repo → **Settings → Secrets and variables → Actions**:
+
+| İsim | Açıklama |
+|---|---|
+| `APP_ID` | 3. adımdaki App ID |
+| `APP_PRIVATE_KEY` | İndirdiğin `.pem` dosyasının tam içeriği |
+| `GROQ_API_KEY_1..4` | Groq API key'leri (bkz. aşağıdaki not) — tek key de yeterli, o zaman sadece `GROQ_API_KEY` kullan |
+| `GEMINI_API_KEY`, `GEMINI_API_KEY_2`, `GEMINI_API_KEY_3` | Gemini API key'leri (birden fazlası isteğe bağlı, rate limit rotasyonu için) |
 
-### 4. Groq API Key Al
+> **Not — birden fazla Groq/Gemini key'i:** Rotasyonun gerçekten işe
+> yaraması için her key'in **ayrı bir hesaptan** gelmesi gerekir.
+> Groq'un (ve çoğu sağlayıcının) rate limit'leri hesap/organizasyon
+> başınadır — aynı hesaptan üretilmiş birden fazla key toplam
+> kapasiteyi ARTIRMAZ, hepsi aynı havuzu paylaşır.
 
-[console.groq.com](https://console.groq.com) adresinden ücretsiz key oluştur.
+Ayrıca **Settings → Secrets and variables → Actions → Variables**
+kısmına `GEMINI_MODEL` (örn. güncel bir Gemini model adı) eklemen
+gerekir.
 
 ### 5. Vercel'e Deploy Et
 
-[vercel.com](https://vercel.com) üzerinden repoyu import et ve şu ortam değişkenlerini gir:
+[vercel.com](https://vercel.com) üzerinden repoyu import et ve şu ortam
+değişkenlerini gir:
 
 | Değişken | Açıklama |
 |---|---|
-| `GH_PAT` | 3. adımda oluşturduğun token |
+| `GH_PAT` | Sunucu tarafı işlemler (dal açma, workflow tetikleme) için bir GitHub token — repo'ya `Contents` + `Actions` yazma izni yeterli |
 | `GH_REPO` | `kullaniciadi/eptran` formatında fork'un adı |
-| `GH_BRANCH` | Branch adı (genellikle `main`) |
-
-### 6. Repo Secret Ekle
-
-GitHub repo → Settings → Secrets and variables → Actions → **New repository secret**:
-- İsim: `GROQ_API_KEY`
-- Değer: Groq API key'in
+| `GH_BRANCH` | Ana dal adı (genellikle `main`) |
+| `APP_ID` | 3. adımdaki App ID — GitHub Actions'takiyle AYNI değer |
+| `APP_PRIVATE_KEY` | 3. adımdaki private key — GitHub Actions'takiyle AYNI değer |
 
 ## Limitler
 
-Groq ücretsiz tier (llama-3.3-70b-versatile):
-- 14,400 token/gün
-- Büyük kitaplarda çeviri birden fazla güne yayılabilir
-- Actions her 6 saatte bir otomatik devam eder
+Groq'un güncel rate limit'lerini kendi hesabından doğrula:
+[console.groq.com/settings/limits](https://console.groq.com/settings/limits)
+(model, plan tipine göre değişir — ücretsiz planda dakikalık token
+tavanı düşük olabilir, çok bölümlü kitaplarda çeviri birden fazla
+çalıştırmaya yayılabilir).
 
 ## Çıktı Formatı
 
-Çeviri tamamlanınca `output/kitap-adi/kitap-adi_tr.epub` olarak indirilir.
-Bölümler ayrıca `output/kitap-adi/001_kitap-adi.txt` şeklinde de mevcuttur.
+Çeviri tamamlanınca `output/<kitap-adı>/<kitap-adı>_tr.epub` olarak
+üretilir. Bölümler ayrıca `output/<kitap-adı>/001_<kitap-adı>.txt`
+şeklinde de mevcuttur.
+
+## Bilinen İstisna Listeleri
+
+- `common_pitfalls.json` — kitap bağımsız, tekrar eden genel çeviri
+  hataları (yanlış kelime seçimleri vb.)
+- `known_proper_nouns.json` — kitap bağımsız, gerçek dünyaya ait ve
+  İngilizce bırakılması gereken özel isimler (bir çevirmen notunda
+  anılan gerçek bir eser adı gibi)
+
+Her ikisi de elle güncellenir — yeni bir örüntü/isim keşfedilince
+ilgili dosyaya bir satır eklemek yeterli, kod değişikliği gerekmez.
 
 ---
 
-*Groq llama-3.3-70b · GitHub Actions · Vercel*
+*Groq (qwen3.8-27b) · Gemini · GitHub Actions · Vercel*