Merge remote-tracking branch 'origin/master'

docs/i18n-dynamic-translation-standard.md

@@ -0,0 +1,52 @@
+# i18n + Dinamik Çeviri Standardı
+
+Bu projede çok dilli yapı iki katmanlıdır:
+
+1. Statik UI metinleri `i18n` ile yönetilir.
+2. Dinamik içerikler `mk_translator` + otomatik çeviri servisi (OpenAI) ile yönetilir.
+
+## 1) Statik UI (Deterministik)
+
+Kullanım alanı:
+- buton metinleri
+- menüler
+- form label'ları
+- validasyon mesajları
+- sabit ekran başlıkları
+- route/meta/title
+
+Kural:
+- her metin key bazlı tutulur (`$t('common.save')`)
+- locale dosyaları: `tr`, `en`, `de`, `it`, `es`, `ru`, `ar`
+- fallback sırası: hedef dil -> `en` -> `tr`
+
+## 2) Dinamik İçerik (DB/CMS/Serbest metin)
+
+Akış:
+1. Kaynak metin için `mk_translator` kontrol edilir.
+2. Hedef dil karşılığı yoksa OpenAI ile çeviri üretilir.
+3. Sonuç `mk_translator` tablosuna yazılır.
+4. Sonraki isteklerde DB sonucu kullanılır (cache etkisi).
+
+Kullanım alanı:
+- ürün/kategori açıklamaları
+- CMS içerikleri
+- admin panelden girilen serbest metinler
+- şablon bazlı metin içerikleri
+
+## Kalite ve Güvenlik Kuralları
+
+- Prompt net olmalı: sadece çeviri dönsün, açıklama eklemesin.
+- Placeholder/format korunsun: `{name}`, `{{count}}`, `%s` gibi yapılar bozulmasın.
+- HTML tag'leri ve kod/SKU değerleri çevrilmesin.
+- API key sadece backend'de tutulur (`OPENAI_API_KEY` client'a verilmez).
+- 429/5xx için retry + exponential backoff uygulanır.
+- Hassas veri içeriği olan metinlerde veri politikası kontrolü yapılır.
+
+## Özet
+
+Bu servis, `i18n`'in alternatifi değildir; `i18n`'i tamamlayan dinamik çeviri katmanıdır.
+
+- Statik UI: `i18n`
+- Dinamik içerik: `mk_translator` + OpenAI + cache
+