# Universal Dynamic Translation System

## 🌟 Genel Bakış

Citrus Platform için geliştirilmiş **evrensel, dinamik ve role-based** çeviri sistemi. Bu sistem, herhangi bir modelin çeviri desteğine sahip olmasını sağlar ve kullanıcı bazlı dil yönetimi sunar.

## 📋 Sistem Mimarisi

```
┌─────────────────┐
│   languages     │ → Dinamik dil tanımları (TR, EN, DE, FR, AR...)
└─────────────────┘
        ↓
┌─────────────────┐
│  translations   │ → Evrensel çeviri tablosu (polymorphic)
└─────────────────┘
        ↓
┌─────────────────┐
│ user_languages  │ → Kullanıcı-Dil ilişkisi (yetkiler)
└─────────────────┘
        ↓
┌─────────┐ ┌─────────┐ ┌─────────┐ ┌──────────┐
│  pages  │ │  blogs  │ │products │ │   news   │ → Herhangi bir model
└─────────┘ └─────────┘ └─────────┘ └──────────┘
```

## ✅ Kurulum ve Yapılandırma

### 1. Database Tabloları

```bash
php artisan migrate
```

Oluşturulan tablolar:
- `languages` - Dil tanımları
- `translations` - Çeviri veriler (polymorphic)
- `user_languages` - Kullanıcı-dil yetkileri

### 2. Varsayılan Diller

```bash
php artisan db:seed --class=LanguageSeeder
```

Eklenen diller:
- 🇹🇷 Türkçe (tr) - Varsayılan, Aktif
- 🇬🇧 İngilizce (en) - Aktif
- 🇩🇪 Almanca (de) - Pasif
- 🇫🇷 Fransızca (fr) - Pasif
- 🇸🇦 Arapça (ar) - Pasif, RTL

### 3. Model Entegrasyonu

Herhangi bir modele çeviri desteği eklemek için:

```php
use App\Traits\HasTranslations;

class YourModel extends Model
{
    use HasTranslations;
    
    protected $translatable = [
        'title',
        'description',
        'content',
    ];
}
```

## 🎯 Kullanım

### Çeviri Kaydetme

```php
// Basit çeviri kaydetme
$blog->setTranslation('title', 'en', 'My Blog Post');

// Status ile kaydetme
$blog->setTranslation('title', 'en', 'My Blog Post', 'published');

// Kullanıcı ID ile
$blog->setTranslation('title', 'en', 'My Blog Post', 'draft', auth()->id());
```

### Çeviri Okuma

```php
// Mevcut dilde
$title = $blog->translate('title');

// Belirli bir dilde
$title = $blog->translate('title', 'en');

// Fallback olmadan
$title = $blog->translate('title', 'en', false);
```

### Toplu İşlemler

```php
// Tüm çevirileri al (bir alan için)
$translations = $blog->getTranslations('title');
// ['tr' => 'Blog Yazım', 'en' => 'My Blog Post']

// Bir dildeki tüm çevirileri al
$translations = $blog->getTranslationsForLanguage('en');
// ['title' => 'My Blog Post', 'content' => '...']

// Çeviri var mı kontrol et
if ($blog->hasTranslation('title', 'en')) {
    // ...
}
```

### Translation Progress

```php
// Tüm diller için ilerleme
$progress = $blog->getTranslationProgress();
// ['tr' => 100, 'en' => 75, 'de' => 0]

// Eksik çevirileri bul
$missing = $blog->getMissingTranslations('en');
// ['meta_description', 'excerpt']

// Çeviri durumu
$status = $blog->getTranslationStatus('en');
// 'complete', 'partial', 'missing'
```

### Translation Workflow

```php
// Çeviri oluştur (draft)
$translation = $blog->setTranslation('title', 'en', 'My Title', 'draft');

// Onaya gönder
$translation->submitForReview();

// Onayla
$translation->approve(auth()->id());

// Yayınla
$translation->publish(auth()->id());

// Reddet
$translation->reject();
```

### Dil Değiştirme

```php
// Runtime'da dil değiştir
switch_language('en');

// Uygulama dili
app()->setLocale('tr');
```

## 🔐 Kullanıcı Yetkilendirme

### Kullanıcıya Dil Atama

```php
// Tam yetki ile dil ata
$user->assignLanguage('tr', 
    canCreate: true, 
    canEdit: true, 
    canApprove: true, 
    canPublish: true
);

// Sadece oluşturma ve düzenleme yetkisi
$user->assignLanguage('en', 
    canCreate: true, 
    canEdit: true, 
    canApprove: false, 
    canPublish: false
);
```

### Yetki Kontrolleri

```php
// Kullanıcı bu dili yönetebilir mi?
if ($user->canManageLanguage('en')) {
    // ...
}

// Specific permissions
if ($user->canCreateInLanguage('en')) { }
if ($user->canEditInLanguage('en')) { }
if ($user->canApproveInLanguage('en')) { }
if ($user->canPublishInLanguage('en')) { }

// Kullanıcının yönettiği diller
$languages = $user->getManagedLanguages();
$codes = $user->getManagedLanguageCodes(); // ['tr', 'en']
```

### Query Filtering

```php
// Sadece belirli dildeki içerikleri getir
Blog::whereHasTranslation('en')->get();

// Kullanıcının yönettiği dillerdeki içerikleri getir
Blog::whereHasTranslationForUser(auth()->user())->get();
```

## 🛠️ Helper Functions

```php
// Mevcut dil
$language = current_language(); // Language model
$code = current_language_code(); // 'tr'

// Varsayılan dil
$defaultLang = default_language();
$defaultCode = default_language_code();

// Aktif diller
$languages = available_languages(); // Collection
$codes = available_language_codes(); // ['tr', 'en']

// Model çevirisi
$value = translate_model($blog, 'title', 'en');

// Çeviri kontrolü
$exists = has_translation($blog, 'title', 'en');

// İlerleme
$progress = translation_progress($blog, 'en'); // 75

// Kullanıcı yetkileri
$can = user_can_manage_language('en');
$languages = user_managed_languages();
$codes = user_managed_language_codes();

// Dil bilgileri
$flag = get_language_flag('tr'); // 🇹🇷
$name = format_language_name('tr'); // Turkish (Türkçe)

// Status
$badge = get_translation_status_badge('published');
$color = get_translation_status_color('draft');
```

## 📊 Filament Admin Panel

### Language Management

Admin panelde **Languages** resource'u üzerinden:
- ✅ Dil ekleme/düzenleme/silme
- ✅ Dil aktif/pasif yapma
- ✅ Varsayılan dil seçme
- ✅ Sıralama düzenleme
- ✅ RTL/LTR desteği

### Permissions

Spatie Permission ile entegre:
- `language::viewAny`
- `language::view`
- `language::create`
- `language::update`
- `language::delete`
- `language::restore`
- `language::forceDelete`
- `language::activate`
- `language::setDefault`

### Policy Kuralları

- Varsayılan dil silinemez
- Varsayılan dil pasif edilemez
- Super admin tüm yetkilere sahip
- Diğer kullanıcılar permission'lara göre erişir

## 🎨 Translation Workflow Statuses

| Status | Açıklama | Badge Color |
|--------|----------|-------------|
| `draft` | Taslak, henüz onaylanmamış | Gray |
| `review` | Onay bekliyor | Warning |
| `approved` | Onaylanmış, yayınlanmayı bekliyor | Success |
| `published` | Yayınlanmış, görünür | Primary |

## 📦 Database Schema

### languages

```sql
id, code (unique), name, native_name, flag, direction,
is_active, is_default, sort_order,
created_by, updated_by, created_at, updated_at, deleted_at
```

### translations

```sql
id, translatable_type, translatable_id, language_code, 
field_name, field_value, status, version,
created_by, updated_by, approved_by, approved_at, published_at,
created_at, updated_at, deleted_at

UNIQUE: translatable_type + translatable_id + language_code + field_name
```

### user_languages

```sql
id, user_id, language_code,
can_create, can_edit, can_approve, can_publish,
created_at, updated_at

UNIQUE: user_id + language_code
```

## 🚀 Örnekler

### Yeni Model için Çeviri Ekle

```php
// 1. Model oluştur
class Product extends Model
{
    use HasTranslations;
    
    protected $translatable = ['name', 'description', 'features'];
}

// 2. Çeviri ekle
$product = Product::create(['name' => 'Ürün', 'slug' => 'urun']);
$product->setTranslation('name', 'en', 'Product', 'published');
$product->setTranslation('description', 'en', 'Product description', 'published');

// 3. Kullan
echo $product->translate('name'); // Mevcut dilde
echo $product->translate('name', 'en'); // İngilizce'de
```

### Çeviri İlerlemesi Widget

```php
$progress = $blog->getTranslationProgress();
foreach ($progress as $langCode => $percentage) {
    $language = Language::findByCode($langCode);
    echo "{$language->flag} {$language->name}: {$percentage}%";
}
```

### Kullanıcı Dil Yönetimi

```php
// Turkish Editor oluştur
$user = User::find(1);
$user->assignLanguage('tr', true, true, false, true);

// English Translator oluştur
$translator = User::find(2);
$translator->assignLanguage('en', true, true, false, false);

// Multi-language Manager
$manager = User::find(3);
$manager->assignLanguage('tr', true, true, true, true);
$manager->assignLanguage('en', true, true, true, true);
```

## ⚡ Performans

- ✅ Indexed queries (translatable_type, translatable_id, language_code)
- ✅ Eager loading desteği
- ✅ Cache-ready yapı
- ✅ Efficient polymorphic relationships
- ✅ Unique constraints

## 🔄 Migration

Mevcut projeden yeni sisteme geçiş için:

```php
// Eski sistem
$blog->title_tr
$blog->title_en

// Yeni sisteme migrate
$blog->setTranslation('title', 'tr', $blog->title_tr, 'published');
$blog->setTranslation('title', 'en', $blog->title_en, 'published');
```

## 📝 Notlar

1. **Zero Configuration**: Yeni model için sadece trait ekle
2. **Dynamic**: Runtime'da dil ekle/çıkar
3. **Role-Based**: Her kullanıcı farklı dilleri yönetebilir
4. **Workflow**: Draft → Review → Approved → Published
5. **Fallback**: Çeviri yoksa default dile düş
6. **Version Control**: Her çevirinin versiyonu
7. **Soft Delete**: Tüm tablolar soft delete destekli

## 🎯 Gelecek Özellikler (TODO)

- [ ] Translation approval notifications
- [ ] Bulk translation import/export
- [ ] Translation memory (önceki çevirilerden öner)
- [ ] AI-powered translation suggestions
- [ ] Translation dashboard widget
- [ ] Language-specific user roles
- [ ] Translation history/audit log
- [ ] Compare translations side-by-side
- [ ] Missing translations report

## 📚 İlgili Dosyalar

- Models: `app/Models/Language.php`, `Translation.php`, `UserLanguage.php`
- Trait: `app/Traits/HasTranslations.php`
- Helpers: `app/Helpers/translation_helpers.php`
- Resource: `app/Filament/Admin/Resources/Languages/`
- Policy: `app/Policies/LanguagePolicy.php`
- Migrations: `database/migrations/*_create_languages_table.php`
- Translations: `lang/tr/language.php`, `lang/en/language.php`

---

**Geliştirici:** Citrus Platform Team  
**Versiyon:** 1.0.0  
**Tarih:** 1 Ekim 2025