Gereksinimler ve Ön Hazırlık

Çalışmaya başlamadan önce sisteminizde Laravel 11 veya daha yeni bir sürümün kurulu olduğundan emin olmalısınız. Ayrıca, dil dosyalarının yönetimi için temel komut satırı (CLI) bilginizin olması yeterlidir.

• PHP 8.2 veya üzeri bir sürüm.
• Laravel framework kurulu bir proje dizini.
• Composer paket yöneticisi erişimi.

Projenizde dil dosyalarının yönetimi için lang dizininin varlığını kontrol edin. Eğer dizin görünmüyorsa, Laravel'in dil paketlerini yüklemek için şu komutu çalıştırabilirsiniz:

php artisan lang:publish

Bu komut, Laravel'in temel çeviri dosyalarını projenize dahil eder ve lang/en dizinini oluşturur.

Dil Yapılandırması ve Yerel Ayarlar

Laravel'de dil ayarları config/app.php dosyası üzerinden yönetilir. Uygulamanızın varsayılan dilini ve desteklenen dilleri burada tanımlamanız gerekir. 2026 standartlarına uygun olarak, ayarlarınızı .env dosyasından çekmek en güvenli yöntemdir.

Öncelikle config/app.php dosyasını şu şekilde güncelleyin:

'locale' => env('APP_LOCALE', 'tr'),
'fallback_locale' => env('APP_FALLBACK_LOCALE', 'en'),
'faker_locale' => 'tr_TR',

Bu yapılandırma, uygulamanızın varsayılan olarak Türkçe başlamasını sağlar. Eğer bir çeviri bulunamazsa, fallback_locale devreye girerek İngilizceye döner.

Middleware ile Dinamik Dil Yönetimi

Kullanıcının seçtiği dili tüm isteklerde (request) hatırlamak için bir Middleware oluşturmalıyız. Bu middleware, URL'deki veya session'daki dil bilgisini kontrol ederek Laravel'in uygulama dilini o anlık değiştirir.

Yeni bir middleware oluşturmak için şu komutu kullanın:

php artisan make:middleware SetLocale

Oluşturulan app/Http/Middleware/SetLocale.php dosyasını şu şekilde düzenleyin:

public function handle(Request $request, Closure $next)
{
    if ($request->has('lang') && array_key_exists($request->lang, ['tr' => 'Türkçe', 'en' => 'English'])) {
        session()->put('locale', $request->lang);
    }

    $locale = session()->get('locale', config('app.locale'));
    app()->setLocale($locale);

    return $next($request);
}

Bu kod, kullanıcının gönderdiği lang parametresini alır, doğrular ve oturuma kaydeder. Ardından app()->setLocale() fonksiyonu ile Laravel'in o istek için dilini ayarlar.

Dil Dosyalarının Hazırlanması ve Kullanımı

Çevirileri yönetmek için lang/tr/messages.php ve lang/en/messages.php dosyalarını oluşturun. Bu dosyalar, anahtar-değer çiftlerinden oluşan basit PHP dizileridir.

Örnek bir lang/tr/messages.php içeriği:

return [
    'welcome' => 'Hoş geldiniz!',
    'login' => 'Giriş Yap',
];

Blade şablonlarınızda bu çevirileri kullanmak için __() helper fonksiyonunu kullanmalısınız. Bu yöntem, XSS (Cross-Site Scripting) saldırılarına karşı otomatik olarak veriyi sanitize eder.

{{ __('messages.welcome') }}
{{ __('messages.login') }}

Veritabanı İçeriklerinin Yerelleştirilmesi

Statik metinlerin yanı sıra, veritabanından gelen içerikleri de çevirmeniz gerekebilir. Bunun için en yaygın yöntem, "translatable" (çevrilebilir) bir tablo yapısı kurmaktır. Genellikle posts ve post_translations şeklinde iki tablo kullanılır.

Kritik Güvenlik Uyarısı: Kullanıcıdan gelen dil parametresini doğrudan setLocale fonksiyonuna göndermeyin. Mutlaka yukarıdaki örnekteki gibi bir beyaz liste (whitelist) kontrolünden geçirerek, sistem dosyalarına erişimi engelleyin.

Sıkça Sorulan Sorular

Laravel'de dil dosyaları neden JSON formatında değil de PHP dizisi olarak kullanılır?

PHP dizileri, daha karmaşık mantıklar (çoğul yapılar, iç içe geçmiş diziler) için daha esnektir ve performans açısından derlenmiş PHP dosyaları olduğu için daha hızlıdır.

URL'de dil parametresi kullanmak SEO açısından doğru mudur?

Evet, example.com/tr/home veya tr.example.com gibi yapılar, arama motorlarının içeriğin hangi dilde olduğunu anlamasını kolaylaştırır.

Çoğul ifadeleri nasıl çevirebilirim?

Laravel'in trans_choice() fonksiyonunu kullanarak, dil dosyalarınızda 'elma' => '{0} Elma yok|[1,19] Az elma|[20,*] Çok elma' gibi tanımlamalar yapabilirsiniz.

Veritabanı çevirileri için paket kullanmalı mıyım?

Başlangıçta kendi yapınızı kurmak öğreticidir, ancak büyük projelerde spatie/laravel-translatable gibi topluluk tarafından test edilmiş paketleri kullanmak zaman kazandırır.

Dil değiştiğinde tarih formatlarını nasıl güncellerim?

PHP'nin Carbon kütüphanesini kullanarak Carbon::setLocale(app()->getLocale()) komutu ile tarihlerin otomatik olarak yerel dile göre formatlanmasını sağlayabilirsiniz.

Performans Optimizasyonu ve Önbellekleme Stratejileri

Çoklu dil desteği sunan uygulamalarda, her istekte dil dosyalarının diskten okunması küçük de olsa bir performans maliyeti oluşturur. Laravel, dil dosyalarını otomatik olarak önbelleğe almasa da, üretim ortamında (production) bu süreci optimize etmek için yapılandırma dosyalarınızı ve çeviri dizilerinizi optimize edebilirsiniz.

Özellikle binlerce çeviri anahtarına sahip büyük ölçekli uygulamalarda, lang dizinindeki dosyaların okunması yerine cache mekanizmasını kullanmak hız kazandıracaktır. Aşağıdaki örnekte, çeviri dosyalarını bir servis sağlayıcı (Service Provider) üzerinden nasıl önbelleğe alabileceğinizi görebilirsiniz:

// AppServiceProvider.php içerisindeki boot metodu
public function boot()
{
    $locale = app()->getLocale();
    
    $translations = Cache::remember("translations.{$locale}", 3600, function () use ($locale) {
        return trans('*'); // Tüm çevirileri dizi olarak çeker
    });
}

Ayrıca, php artisan config:cache ve php artisan route:cache komutlarını deployment sürecinize dahil ederek, Laravel'in dil yapılandırmalarını ve rota tanımlarını derlemesini sağlamalısınız. Bu, uygulamanın her istekte disk I/O işlemlerini minimize etmesine yardımcı olur.

Çok Dilli Uygulamalarda Hata Ayıklama (Debugging)

Çoklu dil yapılarında en sık karşılaşılan sorun, eksik çeviri anahtarlarıdır. Geliştirme aşamasında hangi anahtarın çevirisinin eksik olduğunu anlamak için Laravel'in sunduğu translator.missing olayını (event) dinleyebilirsiniz.

Bu yöntem, çevirisi bulunamayan anahtarları log dosyasına yazdırarak geliştirme sürecinde hata payını sıfıra indirir. AppServiceProvider içerisinde şu yapılandırmayı kullanabilirsiniz:

use Illuminate\Support\Facades\Event;
use Illuminate\Translation\Events\MissingTranslation;

public function boot()
{
    Event::listen(MissingTranslation::class, function ($event) {
        Log::warning("Eksik çeviri anahtarı: {$event->key} - Dil: {$event->locale}");
    });
}

Bu yaklaşım, özellikle büyük ekiplerle çalışırken çeviri dosyalarının güncel tutulmasını sağlar. Eksik anahtarların loglanması sayesinde, hangi sayfalarda çeviri hatası olduğunu kolayca tespit edebilir ve lang/tr.json gibi dosyalarınızı hızlıca güncelleyebilirsiniz.

Deployment ve CI/CD Süreçlerinde Dil Yönetimi

Uygulamanızı canlıya alırken (deployment), dil dosyalarınızın da sunucu üzerinde güncel olduğundan emin olmalısınız. Özellikle Git tabanlı deployment süreçlerinde, çeviri dosyalarındaki değişikliklerin sunucuya yansıması için şu adımları içeren bir script kullanmanız önerilir:

• Versiyon Kontrolü: Dil dosyalarını her zaman ana kod tabanıyla birlikte commit edin.
• Otomatik Temizlik: Deployment sırasında php artisan view:clear komutunu çalıştırarak, önbelleğe alınmış eski dil çıktılarını temizleyin.
• Dosya İzinleri: storage/framework/cache dizininin yazılabilir olduğundan emin olun, aksi takdirde önbellek mekanizması çalışmayacaktır.

Eğer veritabanı tabanlı bir çeviri sistemi kullanıyorsanız, deployment sırasında veritabanı migration'larının yanı sıra, yeni eklenen çeviri anahtarlarını sisteme yükleyen bir seeder çalıştırmak, uygulamanın kararlılığı açısından kritik öneme sahiptir.

Sonuç

Laravel ile çoklu dil desteği modülü oluşturmak, uygulamanızın profesyonellik seviyesini bir üst noktaya taşır. Middleware kullanarak dil yönetimini merkezileştirmek, kodunuzun temiz kalmasını sağlar. Bu aşamadan sonra, bir sonraki adım olarak dil seçimi için bir açılır menü (dropdown) bileşeni oluşturabilir ve kullanıcının seçtiği dili veritabanındaki users tablosunda kalıcı hale getirebilirsiniz.

Sorumluluk Reddi: Bu rehberdeki kod örnekleri eğitim amaçlıdır. Üretim ortamında (production) kullanmadan önce her zaman kodunuzu güvenlik testlerinden geçirin ve güncel Laravel dokümantasyonunu takip ederek bağımlılıklarınızı güncel tutun.