C# İle Özelleştirilmiş Bir Çok Dilli Destekli Arayüz Nasıl Yapılır?

Gereksinimler ve Ön Hazırlık

Çok dilli bir arayüz geliştirmek için öncelikle doğru araçlara sahip olmalısınız. 2026 yılı standartlarında, .NET 8 veya üzeri sürümleri kullanmanız önerilir. Bu sürümler, performans iyileştirmeleri ve geliştirilmiş kaynak yönetimi sunar.

• IDE: Visual Studio 2022 (güncel sürüm) veya JetBrains Rider.
• SDK: .NET 8.0 veya .NET 9.0 SDK yüklü olmalıdır.
• Temel Bilgi: C# sınıfları, Dependency Injection (Bağımlılık Enjeksiyonu) ve temel dosya I/O işlemleri.

Projenizi oluştururken, yerelleştirme için gerekli olan Microsoft.Extensions.Localization kütüphanesinin projenize dahil edildiğinden emin olun. Bu kütüphane, metinleri merkezi bir yerden yönetmenizi sağlar.

Adım 1: Kaynak Dosyalarının (Resource Files) Yapılandırılması

Yerelleştirmenin temel taşı .resx dosyalarıdır. Bu dosyalar, anahtar-değer çiftlerini tutan XML tabanlı dosyalardır. Özelleştirilmiş bir yapı için, her dil için ayrı bir kaynak dosyası oluşturmalıyız.

Örneğin, Resources adında bir klasör oluşturun ve içine Messages.tr.resx (Türkçe) ve Messages.en.resx (İngilizce) dosyalarını ekleyin. Bu dosyaların "Access Modifier" değerini "Public" yaparak kod içerisinden erişilebilir olmalarını sağlayın.

// Messages.tr.resx içeriği (Örnek)
// Anahtar: WelcomeMessage
// Değer: Hoş geldiniz!

// Messages.en.resx içeriği (Örnek)
// Anahtar: WelcomeMessage
// Değer: Welcome!

Bu dosyalar, uygulamanızın farklı dillerdeki metinlerini tutan sözlükler gibidir. Uygulama çalışma zamanında, kullanıcının seçtiği kültüre (Culture) göre doğru dosyayı otomatik olarak seçecektir.

Adım 2: Dependency Injection ile Yerelleştirme Servisini Kaydetme

C# uygulamanızda yerelleştirme servislerini kullanabilmek için bunları Program.cs dosyasında servis koleksiyonuna eklemelisiniz. Bu, uygulamanın yaşam döngüsü boyunca yerelleştirme hizmetine erişmenizi sağlar.

var builder = WebApplication.CreateBuilder(args);

// Yerelleştirme servisini ekle
builder.Services.AddLocalization(options => options.ResourcesPath = "Resources");

var app = builder.Build();

Bu kod bloğu, uygulamanın Resources klasörünü temel alarak yerelleştirme dosyalarını aramasını sağlar. AddLocalization metodu, arka planda gerekli olan IStringLocalizer arayüzünü hazır hale getirir.

Adım 3: IStringLocalizer ile Metinleri Dinamik Olarak Çağırma

Uygulamanızın arayüz katmanında veya servislerinde, metinleri doğrudan yazmak yerine IStringLocalizer arayüzünü kullanmalısınız. Bu, kodunuzu dilden bağımsız kılar.

public class HomeController : Controller
{
    private readonly IStringLocalizer _localizer;

    public HomeController(IStringLocalizer localizer)
    {
        _localizer = localizer;
    }

    public IActionResult Index()
    {
        ViewData["Title"] = _localizer["WelcomeMessage"];
        return View();
    }
}

Burada IStringLocalizer, HomeController ile ilişkilendirilmiş kaynak dosyasını arar. Eğer bulunamazsa, varsayılan kaynak dosyasına başvurur. Bu yapı, kodun okunabilirliğini artırır.

Adım 4: Kullanıcı Dil Seçimini Yönetme (RequestLocalization)

Kullanıcıların uygulamanızı kendi dillerinde kullanabilmeleri için, gelen istekteki (Request) dil bilgisini okumalıyız. .NET, bunu RequestLocalizationOptions ile otomatikleştirir.

var supportedCultures = new[] { "tr-TR", "en-US" };
var localizationOptions = new RequestLocalizationOptions()
    .SetDefaultCulture(supportedCultures[0])
    .AddSupportedCultures(supportedCultures)
    .AddSupportedUICultures(supportedCultures);

app.UseRequestLocalization(localizationOptions);

Bu yapılandırma, uygulamanın hangi dilleri desteklediğini belirler. İstek, tarayıcı başlıklarından veya URL parametrelerinden gelen dil bilgisine göre otomatik olarak kültür ayarını değiştirir.

Adım 5: Gelişmiş Yerelleştirme Yöntemleri Karşılaştırması

Projelerinizde kullanabileceğiniz farklı yerelleştirme yaklaşımlarını aşağıdaki tabloda karşılaştırdık:

Adım 6: Hata Ayıklama ve Güvenlik Uyarıları

Yerelleştirme yaparken en sık yapılan hata, eksik anahtarların yönetilememesidir. IStringLocalizer, anahtar bulunamadığında anahtarın kendisini döndürür; bu, geliştirme aşamasında hataları fark etmenizi kolaylaştırır.

Güvenlik Uyarısı: Yerelleştirme dosyalarınızdaki metinleri doğrudan HTML içerisine basarken XSS (Cross-Site Scripting) saldırılarına karşı dikkatli olun. Kullanıcı tarafından girilen verileri asla doğrudan yerelleştirme anahtarı olarak kullanmayın ve her zaman çıktı kodlaması (Output Encoding) kullanın.

Ayrıca, üretim ortamında (Production) kaynak dosyalarınızın değiştirilmemesi için dosya izinlerini kısıtlayın. Hassas bilgileri (şifreler, API anahtarları) asla .resx dosyaları içerisinde tutmayın.

Sıkça Sorulan Sorular

Yerelleştirme dosyalarını çalışma zamanında güncelleyebilir miyim?

Evet, ancak varsayılan .resx dosyaları derleme zamanında sabitlenir. Dinamik güncellemeler için veritabanı tabanlı bir IStringLocalizer sağlayıcısı yazmanız gerekir.

Kullanıcı dilini nasıl kalıcı hale getirebilirim?

Kullanıcının dil seçimini bir Cookie (çerez) içerisinde saklayarak, RequestLocalization middleware'inin bu çerezi okumasını sağlayabilirsiniz.

Performans kaybı yaşanır mı?

.NET, yerelleştirme kaynaklarını bellekte önbelleğe alır (cache). Bu nedenle, doğru yapılandırıldığında performans kaybı ihmal edilebilir düzeydedir.

Hata mesajlarını da yerelleştirmeli miyim?

Evet, Data Annotation (veri doğrulama) mesajlarını ErrorMessageResourceType kullanarak yerelleştirebilirsiniz.

Sağdan sola (RTL) diller için ne yapmalıyım?

Arapça veya İbranice gibi diller için CSS tarafında direction: rtl; özelliğini kullanarak arayüzü aynalamanız gerekir.

İleri Seviye İpuçları: Dinamik İçerik ve Veritabanı Tabanlı Yerelleştirme

Statik .resx dosyaları küçük ve orta ölçekli projeler için ideal olsa da, içerik yönetiminin sık değiştiği veya kullanıcı tarafından oluşturulan verilerin yerelleştirilmesi gereken durumlarda yetersiz kalabilir. Bu gibi senaryolarda, yerelleştirme verilerini bir veritabanında tutmak ve özel bir IStringLocalizer implementasyonu yazmak en profesyonel yaklaşımdır.

Veritabanı tabanlı bir yerelleştirme yapısı kurarken, IStringLocalizerFactory arayüzünü özelleştirerek uygulamanızın çalışma zamanında veritabanından metin çekmesini sağlayabilirsiniz. Aşağıdaki örnek, veritabanından metin getiren temel bir yapılandırma mantığını göstermektedir:

public class DbStringLocalizer : IStringLocalizer
{
    private readonly MyDbContext _context;
    public DbStringLocalizer(MyDbContext context) => _context = context;

    public LocalizedString this[string name]
    {
        get
        {
            var culture = CultureInfo.CurrentCulture.Name;
            var value = _context.Translations
                .FirstOrDefault(t => t.Key == name && t.Culture == culture)?.Value;
            return new LocalizedString(name, value ?? name, value == null);
        }
    }

    public IEnumerable GetAllStrings(bool includeParentCultures) 
        => throw new NotImplementedException();
}

Yerelleştirme Süreçlerinde Test ve Kalite Güvencesi

Çok dilli uygulamalarda en sık karşılaşılan sorun, çevirilerin arayüzdeki buton veya etiket alanlarına sığmamasıdır (metin taşması). Bu sorunu aşmak için birim testlerinize (unit tests) yerelleştirme testlerini de dahil etmelisiniz. Ayrıca, uygulamanızın farklı dillerdeki davranışını doğrulamak için CultureInfo değiştirme testlerini otomatize etmek kritik öneme sahiptir.

Aşağıdaki test örneği, belirli bir dil seçildiğinde metnin doğru dönüp dönmediğini doğrulamak için kullanılabilir:

[Fact]
public void GetLocalizedText_ReturnsCorrectLanguage()
{
    // Arrange
    var culture = new CultureInfo("tr-TR");
    CultureInfo.CurrentCulture = culture;
    CultureInfo.CurrentUICulture = culture;

    // Act
    var result = _localizer["WelcomeMessage"];

    // Assert
    Assert.Equal("Hoş geldiniz", result.Value);
}

Çeviri Süreçlerinde Otomasyon Stratejileri

• Pseudo-Localization: Uygulamanızı yayına almadan önce, tüm metinleri özel karakterlerle (örneğin: [!!! H-o-ş g-e-l-d-i-n-i-z !!!]) değiştirerek, arayüzde çevrilmemiş veya sabit kodlanmış alanları kolayca tespit edebilirsiniz.
• CI/CD Entegrasyonu: .resx dosyalarınızı bir çeviri yönetim platformu (Crowdin, Lokalise vb.) ile senkronize ederek, geliştiricilerin manuel çeviri yapma yükünü ortadan kaldırabilirsiniz.
• Karakter Kodlaması: Tüm kaynak dosyalarınızın UTF-8 kodlaması ile kaydedildiğinden emin olun; aksi takdirde özel karakterler (ç, ş, ğ, ü, ö, ı) hatalı görüntülenecektir.

Sonuç

C# ile çok dilli bir arayüz oluşturmak, uygulamanızın profesyonel ve erişilebilir olmasını sağlar. Bu rehberde, kaynak dosyalarının yönetiminden, Dependency Injection kullanımına ve kültür yapılandırmasına kadar kritik adımları inceledik. Başarılı bir yerelleştirme stratejisi, sadece metinleri çevirmek değil, kullanıcının bulunduğu bölgeye ve kültüre uygun bir deneyim sunmaktır.

Bir sonraki adım olarak, uygulamanızda tarih ve para birimi formatlarını (Currency Formatting) yerelleştirmeyi deneyebilirsiniz. CultureInfo sınıfını kullanarak, kullanıcının seçtiği dile göre sayı ve tarih formatlarını otomatik olarak düzenlemek, uygulamanızın kalitesini bir üst seviyeye taşıyacaktır.

Sorumluluk Reddi: Bu makalede paylaşılan kod örnekleri eğitim amaçlıdır. Üretim ortamında kullanmadan önce güvenlik açıklarını (XSS, SQL Injection vb.) kontrol etmeli ve kodunuzu gerekli test süreçlerinden geçirmelisiniz.