ASP.NET Core ile Çoklu Dil Desteği Olan Uygulamalar Geliştirmek

Web sitelerimizi daha fazla kitleye ulaştırabilmek veya daha fazla ziyaret alabilmek gibi farklı sebeplerle çoklu dil desteği gerektiren yapılara ihtiyaç duyabilmekteyiz. Bu makale de günümüzde neredeyse standart hale gelen çoklu dil destekli web sitelerinin ASP.NET Core ile birlikte nasıl yapıldığını öğreneceğiz.

Örnekler ve uygulamalar C# dili kullanılarak .NET 9 ve ASP.NET Core 9 MVC destekleyecek şekilde olacaktır. Diğer .NET versiyonları, Razor Pages veya WebAPI üzerinde de benzer yapı kullanılmaktadır. WebAPI kullanımı nedeniyle view üzerinde kullanılacak olan localization yapısı ayrı başlıklar altında anlatılmıştır.

ASP.NET Core içerisinde Localization desteğini kullanabilmek için “Microsoft.AspNetCore.Mvc.Localization” sınıfına kütüphanesine ihtiyaç duymaktayız. İlgili kütüphane “Microsoft.AspNetCore.Mvc” içerisinde yer aldığından ayrıca referans vermemize gerek yoktur. Razor Pages için de durum benzerdir, Razor Pages temelinde aynı MVC yapısı çalışır ve “Microsoft.AspNetCore.App” framework paketinin içinde zaten gömülü olarak gelir.

İlk iş olarak “Program.cs” içerisinde gerekli sınıflarımızı kayıt etmemiz gerekiyor. Uygulamamız çalışmaya başladığında ilgili sınıflar burada belirtilen şekilde oluşturulacaktır. Dil tanımlamalarımızı yaparken İngilizce ve Türkçe dillerine destek vereceğiz. Varsayılan dil tanımlamamız ise İngilizce olacaktır.

“Kayıt etme işlemin ne demek?” gibi detaylara bu yazıya girmeyeceğiz, merak edenler ASP.NET Core Dependency Injection olarak araştırabilirler. Ancak yazıyı anlamak için bu detayları bilmenize gerek yoktur, okumaya devam edebilirsiniz.

// Kayıt işlemimizi gerçekleştiriyoruz ve ResourcePath vererek ilgili dil dosyalarının hangi dizin altında olacağını belirtiyoruz.
builder.Services.AddLocalization(options => options.ResourcesPath = "Resources");

builder.Services.Configure<RequestLocalizationOptions>(options =>
{
    // Uygulamamız içerisinde destek vermemizi istediğimiz dilleri tutan bir liste oluşturuyoruz.
    var supportedCultures = new List<CultureInfo>
    {
        new CultureInfo("en-US"),
        new CultureInfo("tr-TR")
    };

    // DefaultRequestCulture'a varsayılan olarak uygulamamızın hangi dil ile çalışması gerektiğini tanımlıyoruz.
    options.DefaultRequestCulture = new RequestCulture("en-US");
    options.SupportedCultures = supportedCultures;
    options.SupportedUICultures = supportedCultures;
});

// MVC servisine Localization için ViewLocalization ve DataAnnotationsLocalization özelliklerini ekliyoruz.
builder.Services.AddControllersWithViews();

Kayıt işlemimizi tamamlandıktan sonra yine aynı dosya içerisinde (Program.cs) içerisinde dil için kullanılacak middleware’i tanımlıyoruz. Burada “RequestLocalizationOptions” içerisinde kayıt ettiğimiz parametreleri alıp ilgili middleware’e iletiyoruz. Bu metod çalışma zamanında (runtime) çalışır ve gelen HTTP istekleriyle ilgili yapılandırmalara izin verir.

var localizationOptions = app.Services.GetRequiredService<IOptions<RequestLocalizationOptions>>().Value;
app.UseRequestLocalization(localizationOptions);

Kısaca bahsetmek gerekirse önce localization ile ilgili çalışacak servislerimizi kayıt ettik ve ardından UseRequestLocalization ile bu localization yapısının uygulamamıza gelen isteklerde çalışması gerektiğini söyledik.

Yukarıda yazmış olduğumuz kodlar içerisinde yer alan CultureInfo ve RequestCulture sınıfları için aşağıdaki namespace lerin ekli olduğundan emin olun.

using System.Globalization;
using Microsoft.AspNetCore.Localization;

Uygulamalarınızda İngilizce diline destek verecekseniz “en-US” kullanımının Amerikan İngilizcesini, “en-GB” kullanımının ise İngiliz İngilizcesini belirttiğini unutmayınız.

Dil desteğiyle ilgili tanımlamalarımızı yaptıktan sonra şimdi ilgili metinleri tutacağımız dil dosyalarımızı oluşturabiliriz. Bunun için uygulamamızın ana dizininde “Resources” adında yeni bir klasör oluşturuyoruz. Bu klasör adını “Program.cs” dosyasındaki “AddLocalization” kayıt işlemi yapılırken belirtmiştik. İsimlendirme konusunda özgürüz.

Uygulama içerisinde ek bir Controller veya View oluşturmayacağız, yeni bir ASP.NET Core MVC projesi oluşturduğumuzda içerisinde varsayılan olarak gelen “HomeController.cs” ve bunun View dosyalarından faydalanacağız.

Controller İçerisinden Dil Dosyalarının Kullanımı

İlk olarak “HomeController.cs” içerisinde bulunan “Privacy” isimli Action’dan başlayacağız. Buradaki ViewData[“Title”]‘ı kullanıcının seçmiş olduğu dil değerine göre getireceğiz. Bunun için az önce oluşturduğumuz “Resources” klasörü altına “Controllers.HomeController.en-US.resx” ve “Controllers.HomeController.tr-TR.resx” şeklinde iki tane resource dosyası oluşturuyorum. (“Resources” klasörüne sağ tıklayıp “Add New Item” dedikten sonra “Resources File” ı seçmeniz gerekmektedir. Eğer aşağıdaki bir ekran karşılamıyorsa açılan ekranda “Show All Templates” e tıklayabilirsiniz.)

Dosya adlarını isteğimize bağlı olarak iki farklı şekilde oluşturabiliriz. Biz örneğimizde noktalı şekilde kullanacağız.

Oluşturmuş olduğumuz herhangi bir resource dosyası içerisine gidip sol üstteki “+” butonuna basarak “PrivacyPolicy” adında bir anahtar ekliyoruz. Name değerini “PrivacyPolicy” vereceğiz ve daha sonra bu değer üzerinden kullanacağız. Diğer alanları doldurmamıza şimdilik gerek yok.

Controllers.HomeController.en-US.resx
Controllers.HomeController.tr-TR.resx

Yukarıdaki veri girişimizde “Neutral Value” alanını boş geçtik. Bu alan çağırılan değer hiçbir dil ayarlanmamış kullanıcıya gösterilecek olan değerdir. Biz middleware bölümünde varsayılan dil değerini “en-US” olarak tanımladığımızdan varsayılan olarak ilgili dil dosyasına gidecektir, ayrıca tanımlamamıza gerek yoktur. Eğer varsayılan dil değerini middleware ile tanımlamasak ve varsayılan dil için bir resource dosyası oluşturmasaydık alternatif olarak “Neutral Value” alanını da kullanabilirdik.

İlgili değer oluştuktan sonra tek seferlik üst kısımdaki toolbar dan “colums” a tıklıyoruz ve “Show All Cultures” ı seçiyoruz. Bu bize tek bir dil dosyası içerisinde mevcut tüm diller üzerinde düzenleme yapabilmemize olanak sağlayacaktır.

“en-US” alanına “Privacy Policy”, “tr-TR” alanına “Gizlilik Sözleşmesi” şeklinde giriş yapıyoruz. Son hali aşağıdaki ekran görüntüsündeki gibi olacaktır.

Visual Studio 2019’un son sürümünde yukarıdaki şekilde tanımlanmaktadır. Önceki sürümlerde resource dosyalarına ayrı ayrı girip value tanımlaması yapılması gerekmektedir.

Resource dosyalarıyla ilgili işlemlerimiz tamamlandı. Şimdi oluşturduğumuz bu resource dosyalarımızı uygulamamızda kullanalım.

“HomeController.cs” dosyasına geliyoruz ve burada bir localizer oluşturacağız. Oluşturacağımız bu localizer IStringLocalizer tipinde olacak ve kullanmak istediğimiz Controller’ı içine gönderip bize ilgili resource dosyasındaki değerlerin gelmesini sağlayacağız. Bu localizer’ı oluştururken dependency injection’dan yararlanıp constructor injection yapacağız.

Aşağıdaki kodları Controller’ımızın hemen üst kısmına ekliyoruz.

private readonly IStringLocalizer<HomeController> _localizer;

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

Kodların aşağıdaki şekilde görünmesi gerekiyor. Mevcut yapıda ILogger olduğundan onu kaldırmadan hemen yanına ekleyerek devam edebiliriz. Mevcut konumuz ile ILogger’in herhangi bir ilişkisi yok.

_localizer nesnemizi ürettiğimize ve bunu dependency injection yöntemi ile dolduruğumuza göre artık bu nesneyi kullanabiliriz.

Contact isimli Action’ımıza geliyoruz ve buradaki ViewData[“Title”] mesajının içeriğini dil dosyamızdan (resource) çekiyoruz. Bunun için ister “_localizer[“PrivacyPolicy”]” şeklinde isterseniz “_localizer.GetString(“PrivacyPolicy”)” şeklinde kullanabiliriz.,

HomeController altındaki Privacy Action’ımızı aşağıdaki şekilde düzenliyoruz.

public IActionResult Privacy()
{
    //ViewData["Title"] = _localizer["PrivacyPolicy"];
    ViewData["Title"] = _localizer.GetString("PrivacyPolicy");
    
    return View();
}

Şimdi de “/Views/Home/Privacy.cshtml” dosyasına gidiyoruz. Normalde sayfanın üst bölümünde bir ViewData tanımlaması yapılmış bunu yorum satırına çeviriyoruz, biz ViewData içerisindeki Title’a ilgili değeri controller içerisinde atadık.

// @{
//     ViewData["Title"] = "Privacy Policy";
// }
<h1>@ViewData["Title"]</h1>

<p>Use this page to detail your site's privacy policy.</p>

Uygulamamızı çalıştırıyoruz ve menüden Privacy linkine tıklayarak ilgili sayfaya gidiyoruz. Karşımıza bilgisayarınızın diline göre bir karşılama mesajı gelecektir.

Şimdi dil desteğimizin çalıştığından emin olalım ve sayfamızı iki farklı şekilde çağıralım.

http://localhost:53218/Home/Privacy?culture=tr-TR
http://localhost:53218/Home/Privacy?culture=en-US

* 53218 yerine uygulamanızın çalıştığı port değerini yazmanız gerekmektedir.

Uygulamanızı bu şekilde çağırdığınızda QueryString ile belirtmiş olduğunuz culture değerine göre mesajın değiştiğini göreceksiniz.

Aşağıdaki QueryString tanımlamalarını da kullanabilirsiniz.

?culture=tr-TR
?ui-culture=tr-TR
?culture=tr-TR&ui-culture=tr-TR

Buraya kadar öğrendiklerimiz her bir Controller dosyası için bir dil dosyası (resource) oluşturmak şeklindeydi. “Kaydet”, “İptal” gibi uygulamamızın her alanında kullandığımız genel tanımlamalar için ise paylaşılan bir dil dosyasına (resource) ihtiyacımız olacak. Bunun için Models klasörü altına “SharedResources.cs” şeklinde dummy (yapmacık) bir class oluşturuyoruz. Uygulamanızın yapısına göre farklı bir klasör altında da oluşturabiliriz. Bu class’a karşılık yine Resources klasörü altında bir dil dosyası (resource) oluşturuyoruz. Class’ımızı “Models” klasörü altına koyduğumuzdan dil dosyamızın adı “Models.SharedResource.en-US.resx” ve “Models.SharedResource.tr-TR.resx” şeklinde olacak.

Bundan sonrasında dil dosyalarımıza ulaşmak için HomeController.cs içerisinde IStringLocalizer<HomeController>‘ı nasıl kullandıysak aynı şekilde IStringLocalizer<SharedResources>‘ ı kullanabiliriz.

Dil dosyaları içerisinde tutmuş olduğunuz metinler HTML formatında ise IStringLocalizer yerine IHtmlLocalizer tercih etmemiz gerekmektedir.

Buraya kadar anlattıklarımız bir MVC ve WebAPI projesi ile birlikte backend tarafında kullanılabilir. Şimdi MVC frontend / razor tarafında nasıl kullanacağımıza bakalım.

Viewler (Arayüzler) İçerisinden Dil Dosyalarının Kullanımı

Aynı Controllerlarda olduğu gibi Viewlerimiz için de dil dosyaları (resourcelar) kullanarak birden fazla dil destekleyen arayüzler hazırlayabiliriz.

“Program.cs” dosyamıza gelerek “AddControllerWithViews” (RazorPages için AddRazorPages) çağırımı altına “AddViewLocalization()” ve “AddDataAnnotationsLocalization” ekliyoruz.

// Kayıt işlemimizi gerçekleştiriyoruz ve ResourcePath vererek ilgili dil dosyalarının hangi dizin altında olacağını belirtiyoruz.
builder.Services.AddLocalization(options => options.ResourcesPath = "Resources");

builder.Services.Configure<RequestLocalizationOptions>(options =>
{
    // Uygulamamız içerisinde destek vermemizi istediğimiz dilleri tutan bir liste oluşturuyoruz.
    var supportedCultures = new List<CultureInfo>
    {
        new CultureInfo("en-US"),
        new CultureInfo("tr-TR")
    };

    // DefaultRequestCulture'a varsayılan olarak uygulamamızın hangi dil ile çalışması gerektiğini tanımlıyoruz.
    options.DefaultRequestCulture = new RequestCulture("en-US");
    options.SupportedCultures = supportedCultures;
    options.SupportedUICultures = supportedCultures;
});

// MVC servisine Localization için ViewLocalization ve DataAnnotationsLocalization özelliklerini ekliyoruz.
builder.Services.AddControllersWithViews()
    .AddViewLocalization();

Yukarıdaki kod içerisinde dikkatimizi çeken bazı kısımları açıklayalım. “AddViewLocalization” ile .cshtml dosyaları içerisinde view seviyesinde .resx dosyalarına destek vererek çoklu dil kullanımını sağlıyoruz.

Viewler içerisinde localizer kullanabilmek için “Views” klasörü altındaki “_ViewImports.cshtml” dosyasına aşağıdaki “Microsoft.AspNetCore.Mvc.Localization” namespace’ini ekleyip inject (dependency injection) ile bir localizer nesnesi oluşturmamız gerekiyor.

@using Microsoft.AspNetCore.Mvc.Localization
@inject IViewLocalizer Localizer

Viewlerimiz için dil dosyalarımızı (resource) aynı Controllerlarda olduğu gibi iki farklı şekilde oluşturabiliyoruz. İster noktalı istersek dizin yapısını tercih edebiliyoruz.

Resources klasörü altında “Views.Home.Privacy.en-US.resx” ve “Views.Home.Privacy.tr-TR.resx” isimlerinde iki tane dil dosyası (resource) oluşturuyoruz.

Views.Home.Contact.en-US.resx
Views.Home.Contact.tr-TR.resx

Dil dosyalarımızın içerisine “PrivacyInfo” anahtarıyla aşağıdaki metinleri ekliyoruz.

Privacy.cshtml view dosyamıza geliyoruz ve içerisindeki “Use this page…“ diye başlayan metni yorum satırına alarak “Localizer” kullanarak dil dosyası üzerinden çağırıyoruz. Mevcut culture değerimize göre ilgili metin dil dosyalarından okunacaktır.

@* @{
    ViewData["Title"] = "Privacy Policy";
} *@
<h1>@ViewData["Title"]</h1>

@* <p>Use this page to detail your site's privacy policy.</p> *@
@Localizer["PrivacyInfo"]

Eğer bu aşamada hata alıyorsanız Program.cs içerisindeki kayıt ve çağrımların doğru yapılıp yapılmadığını tekrar kontrol ediniz.

Dil Seçeneklerine Göre Farklı Viewler (Arayüzler) Oluşturmak

Bir diğer alternatif olarak resource dosyaları ile uğraşmak istemiyorsak veya proje yapımız buna uygun değilse her dil için ayrı viewler de oluşturabiliriz. Bunun için View dizin yapımızın aşağıdaki şekilde olması gerekmektedir.

Dillere Göre Data Annotations Yapısını Kullanmak

Data Annotationslar ile birlikte dil desteği kullanabilmek için “Program.cs” içerisindeki AddControllerWithViews()’e  “AddDataAnnotationsLocalization()” eklememiz gerekiyor. bu bize ilgili propertylerimiz üzerinde eklediğimiz [Required] gibi annotationlar için dil desteği sağlayacak. İlgili kodu da ekledikten sonra Program.cs içeriğimizin aşağıdaki gibi görünmesi gerekmektedir.

// Kayıt işlemimizi gerçekleştiriyoruz ve ResourcePath vererek ilgili dil dosyalarının hangi dizin altında olacağını belirtiyoruz.
builder.Services.AddLocalization(options => options.ResourcesPath = "Resources");

builder.Services.Configure<RequestLocalizationOptions>(options =>
{
    // Uygulamamız içerisinde destek vermemizi istediğimiz dilleri tutan bir liste oluşturuyoruz.
    var supportedCultures = new List<CultureInfo>
    {
        new CultureInfo("en-US"),
        new CultureInfo("tr-TR")
    };

    // DefaultRequestCulture'a varsayılan olarak uygulamamızın hangi dil ile çalışması gerektiğini tanımlıyoruz.
    options.DefaultRequestCulture = new RequestCulture("en-US");
    options.SupportedCultures = supportedCultures;
    options.SupportedUICultures = supportedCultures;
});

// MVC servisine Localization için ViewLocalization ve DataAnnotationsLocalization özelliklerini ekliyoruz.
builder.Services.AddControllersWithViews()
    .AddViewLocalization()
    .AddDataAnnotationsLocalization();

“HomeController.cs” içerisinde bir “Contact” action ve buna bir view ekliyoruz. Sayfamız için örnek bir iletişim formu hazırlayacağız.

“Models” klasorü içerisinde “ContactFormViewModel.cs” adında yeni bir class oluşturuyoruz. İçeriği aşağıdaki şekilde olacaktır.

using System.ComponentModel.DataAnnotations;

namespace ASPNETCore_Localization.Models
{
    public class ContactFormViewModel
    {
        [Display(Name = "Name")]
        [Required(ErrorMessage = "NameRequired")]
        public required string Name { get; set; }
        
        [Display(Name = "Message")]
        [Required]
        public required string Message { get; set; }
    }
}

Burada Name ve Message alanlarının ekranda görünen label değerleri için “Display” attribute’ünden, boş geçilememesi için ise “Required” attribute’ünden faydalandık. ErrorMessage alanı içinse dil desteğini vereceğimiz “NameRequired” ı key olarak kullandık.

Dil dosyalarımızı oluşturmak için yine “Resources” klasörümüze geliyoruz. “Models.ContactFormViewModel.en-US.resx” ve “Models.ContactFormViewModel.tr-TR.resx” şeklinde iki yeni bir dil dosyası oluşturuyoruz ve içerisine ilgili metinlerin İngilizce karşılıklarını yazıyoruz.

Burada {0} yazılan kısımlara ilgili property üzerinde tanımladığımız DisplayName gelecektir. Eğer tanımlamadıysak property’nin direkt olarak kendi adı yansıyacaktır.

“Views” klasörümüzün altına geliyoruz ve “Contact.cshtml” e aşağıdaki HTML kodlarını ekliyoruz.

@model ContactFormViewModel

<form class="form-horizontal" method="post" action="ContactSave">
    <div class="form-group">
        <label class="col-sm-2 control-label" asp-for="Name"></label>
        <div class="col-sm-10">
            <input type="text" class="form-control" asp-for="Name">
            <span asp-validation-for="Name"></span>
        </div>
        </div>
        <div class="form-group">
            <label class="col-sm-2 control-label" asp-for="Message"></label>
            <div class="col-sm-10">
                <input type="text" class="form-control" asp-for="Message">
                <span asp-validation-for="Message"></span>
            </div>
        </div>
        <div class="form-group">
            <div class="col-sm-offset-2 col-sm-10">
            <button type="submit" class="btn btn-default">Save</button>
        </div>
    </div>
</form>

Şimdi formuzun açılacağı ve devamında verilerin gönderileceği Action’ı hazırlamamız gerekiyor. Bunun için “HomeController.cs” dosyasına aşağıdaki kodları ekliyoruz.

public IActionResult Contact()
{
    return View();
}

[HttpPost]
public IActionResult ContactSave(ContactFormViewModel viewModel)
{
    return View("Contact", viewModel);
}

Eğer ilgili sayfaya ana sayfa üzerinden ulaşmak isterseniz “Layout.cshtml” içerisine link ekleyebiliriz.

 <li class="nav-item">
     <a class="nav-link text-dark" asp-area="" asp-controller="Home" asp-action="Contact">Contact</a>
 </li>

Uygulamamızı çalıştırdığımızda eğer culture değerimiz tr-TR ise Türkçe mesajların değilse Türkçe mesajların geldiğini göreceğiz. Test etmek için tarayıcıdan QueryString ile ?culture=tr-TR gönderebiliriz.

Routing Mekanizması ile Dil Desteğinin Sağlanması

Uygulamamızda dil desteğini direkt Url/Uri üzerinden vermek isteyebiliriz. Gelen culture değerine göre uygulamamızın dilinin ayarlanmasını sağlayabiliriz.

sinanbozkus.com/tr-TR/Home
sinanbozkus.com/en-US/Home

gibi…

Bunun için “Program.cs” dosyamıza geliyoruz ve aşağıdaki kodları ekliyoruz. Öncelikle mevcutta yaptığımız kayıt işleminde bir takım düzenlemelere gitmemiz gerekiyor. Burada “RequestLocalizationOptions” tanımları yaptığımızda kısımda routing desteğini de eklememiz gerekecek.

// Kayıt işlemimizi gerçekleştiriyoruz ve ResourcePath vererek ilgili dil dosyalarının hangi dizin altında olacağını belirtiyoruz.
builder.Services.AddLocalization(options => options.ResourcesPath = "Resources");

builder.Services.Configure<RequestLocalizationOptions>(options =>
{
    // Uygulamamız içerisinde destek vermemizi istediğimiz dilleri tutan bir liste oluşturuyoruz.
    var supportedCultures = new List<CultureInfo>
    {
        new CultureInfo("tr-TR"),
        new CultureInfo("en-US")
    };

    // DefaultRequestCulture'a varsayılan olarak uygulamamızın hangi dil ile çalışması gerektiğini tanımlıyoruz.
    options.DefaultRequestCulture = new RequestCulture("tr-TR");
    options.SupportedCultures = supportedCultures;
    options.SupportedUICultures = supportedCultures;
    
    // Route yani URL üzerinden gelecek ilgili dil culture bilgisini alıyoruz.
    var routeProvider = new RouteDataRequestCultureProvider
    {
        Options = options
    };
    options.RequestCultureProviders.Insert(0, routeProvider);
});

// MVC servisine Localization için ViewLocalization ve DataAnnotationsLocalization özelliklerini ekliyoruz.
builder.Services.AddControllersWithViews()
    .AddViewLocalization()
    .AddDataAnnotationsLocalization();

İlgili servis kaydını düzenledikten sonra routing yapımızda değişikliğe gidiyor ve culture değerinin URL üzerinden geleceğini söylüyoruz.

app.MapControllerRoute(
    name: "default",
     pattern: "{culture=en-US}/{controller=Home}/{action=Index}/{id?}")
    .WithStaticAssets();

Github üzerinden uygulamaya ait kodları indirebilirsiniz.
https://github.com/sinanbozkus/ASPNETCore_Localization

Kaynak:
https://docs.microsoft.com/en-us/aspnet/core/fundamentals/localization