docs: add multilingual i18n rollout plan

2026-07-19 03:06:30 +03:00
parent bace8c86cf
commit 0548820584
11 changed files with 2498 additions and 0 deletions
@@ -0,0 +1,84 @@
+---
+title: Faz 0 Migration ve Geri Donus Sozlesmesi
+description: Cok dillilik calismasi icin expand/migrate/contract sirasi ve backup kurallari.
+phase: 0
+status: completed
+last_updated: 2026-07-19
+---
+
+# Faz 0 Migration ve Geri Donus Sozlesmesi
+
+Bu sozlesme Faz-1'den itibaren veritabani degisikliklerinin nasil yapilacagini
+tanımlar. Neta self-host bir urun oldugu icin migration'lar veri kaybi riski
+tasimamali ve rollback hikayesi basit kalmalidir.
+
+## Uygulama sirasi
+
+1. Expand
+
+Yeni tablolar ve yeni nullable kolonlar eklenir. Mevcut kolonlar kaldirilmaz,
+renamelenmez ve zorunlu hale getirilmez.
+
+2. Backfill
+
+Mevcut Turkce veriler instance default locale'i kabul edilerek
+`content_translations` icine kopyalanir. Orijinal kolonlar okunabilir kalir.
+
+3. Dual read
+
+Okuma katmani once translation resolver'a bakar, eksikse mevcut kolona duser.
+Bu asamada eski veriler ve yeni veriler ayni anda calisir.
+
+4. Dual write
+
+Formlar instance default locale alanini hem mevcut kolona hem translation
+tablosuna yazar. Ek locale'ler sadece translation tablosuna yazilir.
+
+5. Contract
+
+Ancak en az bir release sonra eski kolonlarin kaldirilmasi veya tamamen internal
+fallback haline getirilmesi tartisilir. Ilk cok dillilik fazlarinda contract
+adimi yapilmayacak.
+
+## Backup adimlari
+
+Her schema migration oncesi:
+
+```bash
+pnpm db:backup
+```
+
+Backup dosyasi deploy notuna yazilmalidir. Dokploy veya Docker deploy'da volume
+path'i kontrol edilmeden migration calistirilmamalidir.
+
+## Geri donus adimlari
+
+Migration sonrasi kritik hata varsa:
+
+1. Uygulama yeni surumden onceki image/commit'e geri alinir.
+2. SQLite dosyasi backup'tan restore edilir.
+3. `pnpm db:restore <backup-file>` veya host tarafindaki manuel restore adimi
+   kullanilir.
+4. Restore sonrasi `pnpm phase9:smoke` ile health/API temel davranisi kontrol
+   edilir.
+
+## Faz bazli DB dokunuslari
+
+| Faz | DB degisikligi | Risk | Not |
+| --- | --- | --- | --- |
+| Faz-1 | Locale ve translation tablolari, `clients.portal_locale`, `portal_invitations.locale`, preference check constraint genisletme | Orta | Expand only. |
+| Faz-2 | DB yok veya yalnizca katalog version seed'i | Dusuk | Runtime/cache agirlikli. |
+| Faz-3 | UI translation CRUD | Orta | Admin-only mutation ve audit gerekli. |
+| Faz-5 | Domain content translations dual write | Yuksek | Backfill ve resolver testleri sart. |
+| Faz-6 | Portal locale davet akisi | Orta | Auth oncesi davet dili kritik. |
+| Faz-8 | API contract genisletme | Dusuk/Orta | Backward compatible response alanlari eklenir. |
+
+## Non-goal
+
+Ilk cok dillilik release'inde asagidakiler yapilmayacak:
+
+- Mevcut `projects.name`, `tasks.title` gibi kolonlari kaldirmak.
+- Otomatik makine cevirisi eklemek.
+- Public route'lara locale prefix eklemek.
+- Chat/gunluk/revizyon taleplerini otomatik cevirmek.
+- Kullanici yazili icerigini farkli locale'e sessizce overwrite etmek.