bssapp/docs/i18n-dynamic-translation-standard.md

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