Filament eklentisinde çok dilli çalışma zamanı koleksiyonları oluşturma

Filament Studio’nun v1.2.0 sürümünü yayınladım. Bu sürüm, runtime koleksiyonları, özel alanlar, panolar, filtreler ve API’ler için geliştirdiğim bir Filament v5 eklentisidir.

Kısa versiyon: Bu sürüm çok dilli destek ekliyor.

Uzun versiyon: Runtime veri modeline çok dilli destek eklemek, sadece bir translations JSON sütunu ekleyip devam etmekten daha fazlasıdır.

Filament Studio, uygulama çalışmaya başladıktan sonra veri modelinin değiştiği admin panelleri için tasarlanmıştır. Bir kullanıcı, her yeni içerik türü için yeni bir migration ve Filament kaynağı yazmadan koleksiyon oluşturabilir, alan ekleyebilir, kayıtları yönetebilir, panolar oluşturabilir ve API uç noktalarını ifşa edebilir.

Bu esneklik, çeviriler için spesifik bir sorun yaratmaktadır.

Alanlar runtime’da tanımlandığında, çeviri davranışı da runtime’da tanımlanmalıdır.

Çözmek İstediğim Problem

Gerçek admin sistemlerinde, çok dilli içerik genellikle ya tamamen ya da hiç olmaz. Bir koleksiyon İngilizce ve Fransızca desteği sağlayabilir.

Bu koleksiyon içinde:

• title çevrilebilir olmalıdır.
• description çevrilebilir olmalıdır.
• price paylaşılan kalmalıdır.
• published_at paylaşılan kalmalıdır.
• is_featured paylaşılan kalmalıdır.

Bu, çeviri davranışının yalnızca kayıt veya koleksiyon seviyesinde değil, alan seviyesinde de olmasının gerektiğini gösterir.

Ayrıca bu özelliğin plugin genelinde çalışmasını istedim:

• oluşturulan Filament formları
• EAV depolama
• query builder okuma ve yazma
• REST API yanıtları
• OpenAPI belgeleri
• fallback davranışı
• sürüm anlık görüntüleri

Aksi takdirde, bu kısmi bir özellik gibi hissedilecekti.

Global ve Koleksiyon Konfigürasyonu

Çok dilli destek isteğe bağlıdır.

// config/filament-studio.php
'locales' => [
    'enabled' => true,
    'available' => ['en', 'fr', 'de'],
    'default' => 'en',
],

Ayrıca bunu ortam aracılığıyla etkinleştirebilirsiniz:

STUDIO_LOCALES_ENABLED=true

Her koleksiyon kendi desteklediği dilleri ve varsayılan dili tanımlayabilir:

$collection->update([
    'supported_locales' => [, ],
    => ,
]);

Eğer bir koleksiyon desteklenen dilleri tanımlamazsa, global listeyi kullanır.

Alan Bazında Çeviri

Her alan artık çevrilebilir bir bayrağa sahiptir.

Bu, bir koleksiyonun yerelleştirilmiş ve paylaşılan verileri karıştırmasına olanak tanır:

title        translatable
description  translatable
price        shared
published_at shared
is_featured  shared

Bu tasarım kısmı benim için en önemli olanıdır. Çok dilli yönetimde, her değer içerik değildir. Bazı değerler gerçekler, bayraklar, fiyatlar, tarihler veya ilişkiler olabilir. Hepsini çevrilebilir olarak değerlendirmenin yarattığı gürültü ve bazen hatalar benim için problem oluşturur.

Depolama Modeli

Filament Studio, alanların runtime’da oluşturulması nedeniyle bir EAV modeli kullanır.

v1.2.0 için, studio_values tablosu artık bir locale sütununu içermektedir.

Çevrilebilir alanlar için, değerler her dil için saklanır.

Paylaşılan alanlar içinse, aktif dil fark etmeksizin bir değer kullanılır.

Benzersizlik sınırı:

record_id + field_id + locale

Bu, bir kaydın aynı runtime alanı için farklı yerelleştirilmiş değerlere sahip olmasına olanak tanır; her çevrilebilir alan için yeni veritabanı sütunları oluşturmadan.

Dil Çözümü

Kuralları tek bir yerde tutmak için özel bir LocaleResolver servisi ekledim.

Aktif dil, bu sırayla çözülür:

1. ?locale= query parametresi
2. X-Locale başlığı
3. oturum
4. koleksiyon varsayılanı
5. global varsayılan

Bu, API tüketicilerine bir dil talep etmenin doğrudan bir yolunu sağlar; admin paneli ise seçilen dili oturumda hatırlayabilir.

Sorgu Oluşturucu API

EavQueryBuilder artık bir locale() metodunu desteklemektedir:

$data = EavQueryBuilder::for()
    ->locale()
    ->getRecordData$record);

Oluşturma ve güncelleme işlemleri de bir dili hedef alabilir:

$record = EavQueryBuilder::for()
    ->locale'fr')
    ->create'title' => ,
    ]);

EavQueryBuilder::for()
    ->locale'fr')
    ->update$record->id, [
        => ,
    ]);

Ayrıca bir seferde tüm çevirileri almak için getAllLocaleData() kullanılabilir:

= EavQueryBuilder::for()
    ->getAllLocaleData$record);

Örnek sonuç:

[
    => [
        => ,
        => ,
    ],
    => ,
]

Çevrilebilir alanlar dil haritaları döndürür. Paylaşılan alanlar ise düz kalır.

Fallback Meta Verisi

Fallback davranışının sessiz olmasını istemedim.

Eğer bir API istemcisi Fransızca talep ederse ve bir alan İngilizceye geri dönerse, istemci bunu algılayabilmelidir.

Bu nedenle getRecordDataWithMeta() fallback bilgisi döndürür:

= EavQueryBuilder::for()
    ->locale'fr')
    ->getRecordDataWithMeta$record);

Örnek:

[
    => [
        => ,
        => ,
    ],
    => [],
]

Bu, arayan kişiye slug‘un varsayılan dilden geldiğini bildirir.

REST API Desteği

API uç noktaları artık query parametreleri aracılığıyla dil seçimlerini kabul ediyor:

curl -H  \
     

ya da başlıklar aracılığıyla:

curl -H  \
     -H  \
     

Yanıtlar meta veri içerir:

{
  : {
    : ,
    : {
      : ,
      : ,
      : 
    }
  },
  : 
    : ,
    : "slug"]
  }
}

Tek kayıt okumaları için, all_locales=true her dili döndürür:

curl -H  \
     

OpenAPI Belgeleri

Çok dilli destek etkinleştirildiğinde, üretilen OpenAPI belgeleri şunları içerir:

• locale query parametresi
• X-Locale başlık parametresi
• all_locales query parametresi
• _meta.locale
• _meta.fallbacks

Bunu yapmak önemliydi çünkü API özellikleri, belgeler talep ve yanıt şekli göstermediğinde yanlış anlaşılabilir.

Admin UI ve Sürümleme

Filament admin panelinde, çok dilli koleksiyonlar artık kayıt sayfalarında bir dil değiştiriciye sahiptir.

Editörler, dili değiştirebilir ve sadece o dil için değişmesi gereken alanları düzenleyebilir.

Sürüm anlık görüntüleri de çevrilebilir alanlar için tüm dil değerlerini saklar:

{
  : 
    : ,
    : 
  },
  : 
    : 
  },
  : 
}

Böylece bir sürüm geri yüklemek, sadece o sırada aktif olan dili geri yüklemekle kalmaz.

Neden Paylaşıyorum

Bu güncelleme, paketin daha pratik hissettirmesini sağladı.

Dinamık bir admin oluşturucunun ilk versiyonu, yalnızca runtime alanlar ve oluşturulmuş formlarla iyi görünebilir.

Ancak gerçek projeler, daha az gösterişli olan parçalar için ısrarcıdır:

• izinler
• API’ler
• sürümleme
• tenancy
• filtreleme
• çok dilli içerik

Filament Studio’nun itmek istediğim yön budur.

GitHub: https://github.com/flexpik/filament-studio

Packagist: https://packagist.org/packages/flexpik/filament-studio

Eğer Laravel’de çok dilli admin panelleri geliştirdiyseniz, model hakkında geribildirim almak isterim:

• çeviri davranışı alan bazında mı olmalı?
• fallback meta verisi pratikte yararlı mı?
• all_locales=true sizin API kullanım durumlarınız için çalışır mı?
• Hangi uç noktaları atladım?