ASP.NET Core'da genelleştirme ve yerelleştirme

Note

Bu, bu makalenin en son sürümü değildir. Geçerli sürüm için bu makalenin .NET 10 sürümüne bakın.

Warning

ASP.NET Core'un bu sürümü artık desteklenmiyor. Daha fazla bilgi için bkz . .NET ve .NET Core Destek İlkesi. Geçerli sürüm için bu makalenin .NET 10 sürümüne bakın.

Rick Anderson, Damien Bowden, Bart Calixto, Nadeem Afana ve Hisham Bin Ateya

Çok dilli bir web sitesi, bir web sitesinin daha geniş bir hedef kitleye ulaşmasını sağlar. ASP.NET Core, farklı dillere ve kültürlere yerelleştirme için hizmetler ve ara yazılım sağlar.

Bu makaledeki yönergeleri ekleyen veya yerine geçen yerelleştirme kılavuzu için, ASP.NET Core genelleştirme ve yerelleştirme bölümüne bkz.

Terms

  • Genelleştirme (G11N): Uygulama oluşturma işlemi farklı dilleri ve bölgeleri destekler. Kısaltma, ilk ve son harflerden ve aralarındaki harf sayısından gelir.
  • Yerelleştirme (L10N): Belirli diller ve bölgeler için genelleştirilmiş bir uygulamayı özelleştirme işlemi.
  • Uluslararasılaştırma (I18N): Hem genelleştirme hem de yerelleştirme.
  • Kültür: Dil ve isteğe bağlı olarak bir bölge.
  • Nötr kültür: Belirli bir dile sahip olan ancak bölge olmayan bir kültür (örneğin, "en", "es").
  • Belirli bir kültür: Belirtilen dil ve bölgeye sahip bir kültür (örneğin, "en-US", "en-GB", "es-CL").
  • Ana kültür: Belirli bir kültürü içeren nötr kültür (örneğin, "en", "en-US" ve "en-GB"nin ana kültürüdür).
  • Yerel ayar: Yerel ayar, bir kültürle aynıdır.

Dil ve ülke/bölge kodları

Kültür adı için RFC 4646 biçimi, dili ve <language code>-<country/region code> alt kültürü tanımlayan biçimidir<language code><country/region code>. Örneğin, es-CL İspanyolca (Şili), en-US İngilizce (Birleşik Devletler) ve en-AU İngilizce (Avustralya) için. RFC 4646 , bir dille ilişkilendirilmiş ISO 639 iki harfli küçük harfli kültür kodunun ve bir ülke veya bölgeyle ilişkili ISO 3166 iki harfli büyük harfli alt kültür kodunun bir birleşimidir. Daha fazla bilgi için bkz. System.Globalization.CultureInfo.

Uygulamayı yerelleştirme görevleri

Bir uygulamayı genelleştirme ve yerelleştirme aşağıdaki görevleri içerir:

Örnek kodu görüntüleme veya indirme (indirme)

Ek kaynaklar

Rick Anderson, Damien Bowden, Bart Calixto, Nadeem Afana ve Hisham Bin Ateya

Çok dilli bir web sitesi, bir web sitesinin daha geniş bir hedef kitleye ulaşmasını sağlar. ASP.NET Core, farklı dillere ve kültürlere yerelleştirme için hizmetler ve ara yazılım sağlar.

Terms

  • Genelleştirme (G11N): Uygulama oluşturma işlemi farklı dilleri ve bölgeleri destekler. Kısaltma, ilk ve son harflerden ve aralarındaki harf sayısından gelir.
  • Yerelleştirme (L10N): Belirli diller ve bölgeler için genelleştirilmiş bir uygulamayı özelleştirme işlemi.
  • Uluslararasılaştırma (I18N): Hem genelleştirme hem de yerelleştirme.
  • Kültür: Dil ve isteğe bağlı olarak bir bölge.
  • Nötr kültür: Belirli bir dile sahip olan ancak bölge olmayan bir kültür (örneğin, "en", "es").
  • Belirli bir kültür: Belirtilen dil ve bölgeye sahip bir kültür (örneğin, "en-US", "en-GB", "es-CL").
  • Ana kültür: Belirli bir kültürü içeren nötr kültür (örneğin, "en", "en-US" ve "en-GB"nin ana kültürüdür).
  • Yerel ayar: Yerel ayar, bir kültürle aynıdır.

Dil ve ülke/bölge kodları

Kültür adı için RFC 4646 biçimi, dili ve <language code>-<country/region code> alt kültürü tanımlayan biçimidir<language code><country/region code>. Örneğin, es-CL İspanyolca (Şili), en-US İngilizce (Birleşik Devletler) ve en-AU İngilizce (Avustralya) için. RFC 4646 , bir dille ilişkilendirilmiş ISO 639 iki harfli küçük harfli kültür kodunun ve bir ülke veya bölgeyle ilişkili ISO 3166 iki harfli büyük harfli alt kültür kodunun bir birleşimidir. Daha fazla bilgi için bkz. System.Globalization.CultureInfo.

Uygulamayı yerelleştirme görevleri

Bir uygulamayı genelleştirme ve yerelleştirme aşağıdaki görevleri içerir:

Örnek kodu görüntüleme veya indirme (indirme)

Ek kaynaklar

Rick Anderson, Damien Bowden, Bart Calixto, Nadeem Afana ve Hisham Bin Ateya

Çok dilli bir web sitesi, sitenin daha geniş bir hedef kitleye ulaşmasını sağlar. ASP.NET Core, farklı dillere ve kültürlere yerelleştirme için hizmetler ve ara yazılım sağlar.

Uluslararasılaştırma ve Yerelleştirmeyi System.Globalizationiçerir. Genelleştirme, farklı kültürleri destekleyen uygulamalar tasarlama işlemidir. Genelleştirme, belirli coğrafi alanlarla ilişkili tanımlı bir dil betikleri kümesinin giriş, görüntüleme ve çıkışı için destek ekler.

Yerelleştirme, yerelleştirilebilirlik için önceden işlediğiniz genelleştirilmiş bir uygulamayı belirli bir kültüre/yerel ayara uyarlama işlemidir. Daha fazla bilgi için bkz . Bu belgenin sonuna yakın genelleştirme ve yerelleştirme terimleri .

Uygulama yerelleştirmesi şunları içerir:

  1. Uygulamanın içeriğini yerelleştirilebilir hale getirme
  2. Desteklediğiniz diller ve kültürler için yerelleştirilmiş kaynaklar sağlayın
  3. Her istek için dil/kültür seçmek için bir strateji uygulama

Örnek kodu görüntüleme veya indirme (indirme)

Uygulama içeriğini yerelleştirilebilir hale getirme

IStringLocalizer ve IStringLocalizer<T> yerelleştirilmiş uygulamalar geliştirirken üretkenliği artırmak için tasarlanmıştır. IStringLocalizer, ResourceManager ve ResourceReader'yi kullanarak çalışma zamanında kültüre özgü kaynaklar sağlar. Arabirim, bir dizin oluşturucuya ve yerelleştirilmiş dizeleri döndüren bir IEnumerable öğesine sahiptir. IStringLocalizer varsayılan dil dizelerinin bir kaynak dosyasında depolanmasını gerektirmez. Yerelleştirme için hedeflenen bir uygulama geliştirebilirsiniz ve geliştirmenin erken aşamalarında kaynak dosyaları oluşturmanız gerekmez. Aşağıdaki kod, yerelleştirme için "Başlık Hakkında" dizesinin nasıl sarılacağını göstermektedir.

using Microsoft.AspNetCore.Mvc;
using Microsoft.Extensions.Localization;

namespace Localization.Controllers
{
    [Route("api/[controller]")]
    public class AboutController : Controller
    {
        private readonly IStringLocalizer<AboutController> _localizer;

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

        [HttpGet]
        public string Get()
        {
            return _localizer["About Title"];
        }
    }
}

Önceki kodda, IStringLocalizer<T> uygulama kısmı Bağımlılık Enjeksiyonu'ndan gelir. "Başlık Hakkında" yerelleştirilmiş değeri bulunamazsa, dizin oluşturucu anahtarı döndürülür, yani "Başlık Hakkında" dizesi. Varsayılan dil değişmez dizelerini uygulamada bırakabilir ve uygulamayı geliştirmeye odaklanabilmeniz için yerelleştiriciye sarmalayabilirsiniz. Uygulamanızı varsayılan dilinizle geliştirir ve önce varsayılan bir kaynak dosyası oluşturmadan yerelleştirme adımına hazırlarsınız. Alternatif olarak, geleneksel yaklaşımı kullanabilir ve varsayılan dil dizesini almak için bir anahtar sağlayabilirsiniz. Birçok geliştirici için varsayılan dil .resx dosyası olmadan ve metin sabitlerini kaydırarak yeni iş akışı, bir uygulamayı yerelleştirme yükünü azaltabilir. Diğer geliştiriciler, daha uzun metinlerle çalışmayı kolaylaştırdığı ve yerelleştirilmiş dizeleri güncellemeyi kolaylaştırdığı için geleneksel iş akışını tercih edebilir.

IHtmlLocalizer<T> UYGULAMAYı HTML içeren kaynaklar için kullanın. IHtmlLocalizer HTML, kaynak dizesinde biçimlendirilmiş bağımsız değişkenleri kodlar, ancak HTML kaynak dizesini kodlamaz. Aşağıda vurgulanan örnekte, yalnızca parametrenin değeri name HTML kodlanmıştır.

using System;
using Microsoft.AspNetCore.Http;
using Microsoft.AspNetCore.Localization;
using Microsoft.AspNetCore.Mvc;
using Microsoft.AspNetCore.Mvc.Localization;

namespace Localization.Controllers
{
    public class BookController : Controller
    {
        private readonly IHtmlLocalizer<BookController> _localizer;

        public BookController(IHtmlLocalizer<BookController> localizer)
        {
            _localizer = localizer;
        }

        public IActionResult Hello(string name)
        {
            ViewData["Message"] = _localizer["<b>Hello</b><i> {0}</i>", name];

            return View();
        }

Note

Genel olarak, HTML'yi değil, yalnızca metni yerelleştirin.

En düşük düzeyde IStringLocalizerFactoryBağımlılık Enjeksiyonu'ndan yararlanabilirsiniz:

{
    public class TestController : Controller
    {
        private readonly IStringLocalizer _localizer;
        private readonly IStringLocalizer _localizer2;

        public TestController(IStringLocalizerFactory factory)
        {
            var type = typeof(SharedResource);
            var assemblyName = new AssemblyName(type.GetTypeInfo().Assembly.FullName);
            _localizer = factory.Create(type);
            _localizer2 = factory.Create("SharedResource", assemblyName.Name);
        }       

        public IActionResult About()
        {
            ViewData["Message"] = _localizer["Your application description page."] 
                + " loc 2: " + _localizer2["Your application description page."];

Yukarıdaki kod, iki fabrika oluşturma yönteminin her birini gösterir.

Yerelleştirilmiş dizelerinizi denetleyiciye, alana göre bölümleyebilir veya yalnızca bir kapsayıcınız olabilir. Örnek uygulamada, paylaşılan kaynaklar için adlı SharedResource bir sahte sınıf kullanılır.

// Dummy class to group shared resources

namespace Localization
{
    public class SharedResource
    {
    }
}

Bazı geliştiriciler genel veya paylaşılan dizeler içermek için sınıfını Startup kullanır. Aşağıdaki örnekte, InfoController ve SharedResource yerelleştiricileri kullanılmıştır:

public class InfoController : Controller
{
    private readonly IStringLocalizer<InfoController> _localizer;
    private readonly IStringLocalizer<SharedResource> _sharedLocalizer;

    public InfoController(IStringLocalizer<InfoController> localizer,
                   IStringLocalizer<SharedResource> sharedLocalizer)
    {
        _localizer = localizer;
        _sharedLocalizer = sharedLocalizer;
    }

    public string TestLoc()
    {
        string msg = "Shared resx: " + _sharedLocalizer["Hello!"] +
                     " Info resx " + _localizer["Hello!"];
        return msg;
    }

Yerelleştirmeyi görüntüle

IViewLocalizer hizmet, bir görünüm için yerelleştirilmiş dizeler sağlar. ViewLocalizer sınıfı bu arabirimi uygular ve görünüm dosyası yolundan kaynak konumunu bulur. Aşağıdaki kod, IViewLocalizer: varsayılan uygulamasının nasıl kullanılacağını gösterir.

@using Microsoft.AspNetCore.Mvc.Localization

@inject IViewLocalizer Localizer

@{
    ViewData["Title"] = Localizer["About"];
}
<h2>@ViewData["Title"].</h2>
<h3>@ViewData["Message"]</h3>

<p>@Localizer["Use this area to provide additional information."]</p>

varsayılan uygulaması IViewLocalizer , görünümün dosya adına göre kaynak dosyasını bulur. Genel paylaşılan kaynak dosyası kullanma seçeneği yoktur. ViewLocalizer kullanarak yerelleştiriciyi IHtmlLocalizeruygular, bu nedenle Razor HTML yerelleştirilmiş dizeyi kodlamaz. Kaynak dizelerini parametreleştirebilirsiniz ve IViewLocalizer HTML parametreleri kodlar, ancak kaynak dizesini kodlamaz. Aşağıdaki Razor işaretlemeyi göz önünde bulundurun:

@Localizer["<i>Hello</i> <b>{0}!</b>", UserManager.GetUserName(User)]

Fransız kaynak dosyası aşağıdakileri içerebilir:

Key Value
<i>Hello</i> <b>{0}!</b> <i>Bonjour</i> <b>{0} !</b>

İşlenen görünüm, kaynak dosyasındaki HTML işaretlemesini içerir.

Note

Genel olarak, HTML'yi değil, yalnızca metni yerelleştirin.

Paylaşılan kaynak dosyasını bir görünümde kullanmak için ekleyin IHtmlLocalizer<T>:

@using Microsoft.AspNetCore.Mvc.Localization
@using Localization.Services

@inject IViewLocalizer Localizer
@inject IHtmlLocalizer<SharedResource> SharedLocalizer

@{
    ViewData["Title"] = Localizer["About"];
}
<h2>@ViewData["Title"].</h2>

<h1>@SharedLocalizer["Hello!"]</h1>

DataAnnotations yerelleştirmesi

DataAnnotations hata mesajları IStringLocalizer<T> ile yerelleştirilir. seçeneğini ResourcesPath = "Resources"kullanarak içindeki RegisterViewModel hata iletileri aşağıdaki yollardan birinde depolanabilir:

  • Resources/ViewModels.Account.RegisterViewModel.fr.resx
  • Resources/ViewModels/Account/RegisterViewModel.fr.resx
public class RegisterViewModel
{
    [Required(ErrorMessage = "The Email field is required.")]
    [EmailAddress(ErrorMessage = "The Email field is not a valid email address.")]
    [Display(Name = "Email")]
    public string Email { get; set; }

    [Required(ErrorMessage = "The Password field is required.")]
    [StringLength(8, ErrorMessage = "The {0} must be at least {2} characters long.", MinimumLength = 6)]
    [DataType(DataType.Password)]
    [Display(Name = "Password")]
    public string Password { get; set; }

    [DataType(DataType.Password)]
    [Display(Name = "Confirm password")]
    [Compare("Password", ErrorMessage = "The password and confirmation password do not match.")]
    public string ConfirmPassword { get; set; }
}

Geçersizlik öznitelikleri yerelleştirilmiştir.

Birden çok sınıf için bir kaynak dizesi kullanma

Aşağıdaki kod, birden çok sınıfa sahip doğrulama öznitelikleri için bir kaynak dizesinin nasıl kullanılacağını gösterir:

public void ConfigureServices(IServiceCollection services)
{
    services.AddMvc()
        .AddDataAnnotationsLocalization(options => {
            options.DataAnnotationLocalizerProvider = (type, factory) =>
                factory.Create(typeof(SharedResource));
        });
}

Yukarıdaki kodda, SharedResource doğrulama iletilerinizin depolandığı resx'e karşılık gelen sınıftır. Bu yaklaşımla, DataAnnotations her sınıfın kaynağı yerine yalnızca SharedResource kullanır.

Desteklediğiniz diller ve kültürler için yerelleştirilmiş kaynaklar sağlayın

SupportedCultures ve SupportedUICultures

ASP.NET Core, SupportedCultures ve SupportedUICulturesolmak üzere iki kültür değeri belirtmenize olanak tanır. CultureInfo nesnesi SupportedCultures tarih, saat, sayı ve para birimi biçimlendirmesi gibi kültüre bağımlı işlevlerin sonuçlarını belirler. SupportedCultures ayrıca metnin sıralama düzenini, büyük/küçük harf kurallarını ve dize karşılaştırmalarını belirler. Sunucunun kültürü nasıl aldığı hakkında daha fazla bilgi için CultureInfo.CurrentCulture ve CultureInfo.CurrentUICulture öğelerine bakın. SupportedUICultures, ResourceManager tarafından aranmak üzere hangi çevrilmiş dizelerin (.resx dosyalarından) kullanılacağını belirler. ResourceManager, CurrentUICulture tarafından belirlenen kültüre özgü dizeleri arar. .NET'teki her iş parçacığında CurrentCulture ve CurrentUICulture nesneleri vardır. Çerçeve, kültüre bağımlı işlevleri işlerken bu değerleri inceler. Geçerli iş parçacığının kültürü en-US (İngilizce, Birleşik Devletler) olarak ayarlandıysa DateTime.Now.ToLongDateString() görüntüler; ancak CurrentCulturees-ES (İspanyolca, İspanya) olarak ayarlanırsa, çıktı jueves, 18 de febrero de 2016 olur.

Kaynak dosyaları

Kaynak dosyası, yerelleştirilebilir dizeleri koddan ayırmak için kullanışlı bir mekanizmadır. Varsayılan olmayan dil için çevrilmiş dizeler .resx kaynak dosyalarında yalıtılır. Örneğin, çevrilmiş dizeler içeren Welcome.es.resx adlı İspanyolca kaynak dosyası oluşturmak isteyebilirsiniz. "es", İspanyolca için dil kodudur. Visual Studio'da bu kaynak dosyasını oluşturmak için:

  1. Çözüm Gezgini'nde, kaynak dosyasını içerecek klasöre sağ tıklayın ve Ekle>Yeni Öğeyi seçin.

    İç içe bağlam menüsü: Çözüm Gezgini'nde, Kaynaklar için bir bağlam menüsü açılır. Yeni Öğe komutunun vurgulandığı Ekle için ikinci bir bağlam menüsü açılır.

  2. Yüklü şablonları ara kutusuna "kaynak" yazın ve dosyayı adlandırın.

    Yeni Öğe Ekle iletişim kutusu

  3. Ad sütununa anahtar değerini (yerel dize) ve Değer sütununa çevrilmiş dizeyi girin.

    Welcome.es.resx dosyası (İspanyolca için Hoş Geldiniz kaynak dosyası) ve Ad sütununda Hello sözcüğü ve Değer sütununda Hola (İspanyolca'da Hello) sözcüğü

    Visual Studio Welcome.es.resx dosyasını gösterir.

    Hoş Geldiniz İspanyolca (es) kaynak dosyasını gösteren Çözüm Gezgini

Kaynak dosya adlandırma

Kaynaklar, sınıflarının tam tür adı kullanılarak, derleme adı hariç olacak şekilde adlandırılır. Örneğin, ana derlemesi LocalizationWebsite.Web.dll sınıfı LocalizationWebsite.Web.Startup için olan bir projedeki Fransızca kaynağı Startup.fr.resx olarak adlandırılır. Sınıfın LocalizationWebsite.Web.Controllers.HomeController kaynağı Controllers.HomeController.fr.resx olarak adlandırılır. Hedeflenen sınıfınızın ad alanı derleme adıyla aynı değilse tam tür adı gerekir. Örneğin, örnek projede türü ExtraNamespace.Tools için bir kaynak ExtraNamespace.Tools.fr.resx olarak adlandırılabilir.

Örnek projede, yöntemi "Kaynaklar" olarak ayarlar; bu nedenle ev denetleyicisinin Fransızca kaynak dosyasının proje göreli yolu resources/controllers.homecontroller.fr.resxolur. Alternatif olarak, kaynak dosyalarını düzenlemek için klasörleri kullanabilirsiniz. Ev denetleyicisi için yol Resources/Controllers/HomeController.fr.resxolacaktır. seçeneğini kullanmazsanız ResourcesPath , .resx dosyası proje temel dizinine gider. için HomeController kaynak dosyası Controllers.HomeController.fr.resx olarak adlandırılır. Nokta veya yol adlandırma kuralını kullanma seçimi, kaynak dosyalarınızı nasıl düzenlemek istediğinize bağlıdır.

Kaynak adı Nokta veya yol adlandırma
Resources/Controllers.HomeController.fr.resx Dot
Resources/Controllers/HomeController.fr.resx Path

@inject IViewLocalizer kullanan kaynak dosyaları Razor görünümlerinde benzer bir kalıba uyar. Bir görünümün kaynak dosyası nokta adlandırma veya yol adlandırma kullanılarak adlandırılabilir. Razor kaynak dosyaları, ilişkili oldukları görünüm dosyalarının yolunu taklit eder. "Kaynaklar" olarak ayarladığımız ResourcesPath varsayıldığında, görünümle Views/Home/About.cshtml ilişkili Fransız kaynak dosyası aşağıdakilerden biri olabilir:

  • Kaynaklar/Görünümler/Home/About.fr.resx

  • Kaynaklar/Görünümler.Home. About.fr.resx

seçeneğini kullanmazsanız ResourcesPath , bir görünümün .resx dosyası görünümle aynı klasörde yer alır.

RootNamespaceAttribute

özniteliği, RootNamespaceAttribute bir derlemenin kök ad alanı derleme adından farklı olduğunda derlemenin kök ad alanını sağlar.

Warning

Projenin adı geçerli bir .NET tanımlayıcısı olmadığında bu durum oluşabilir. Örneğin my-project-name.csproj , kök ad alanını my_project_name ve bu hataya yol açan derleme adını my-project-name kullanır.

Bir derlemenin kök ad alanı derleme adından farklıysa:

  • Yerelleştirme varsayılan olarak çalışmaz.
  • Yerelleştirme, kaynakların derleme içinde aranma şeklinden dolayı başarısız oluyor. RootNamespace , yürütme işlemi sırasında erişilemeyen bir derleme zamanı değeridir.

RootNamespace AssemblyName'den farklıysa, aşağıdakini AssemblyInfo.cs' ye dahil edin (parametre değerleri gerçek değerlerle değiştirilir):

using System.Reflection;
using Microsoft.Extensions.Localization;

[assembly: ResourceLocation("Resource Folder Name")]
[assembly: RootNamespace("App Root Namespace")]

Yukarıdaki kod, resx dosyalarının başarılı bir şekilde çözümlenmesine olanak tanır.

Kültür geri dönüşü davranışı

Bir kaynağı ararken, yerelleştirme "kültür geri dönüşü" ile etkileşim kurar. İstenen kültürden başlayarak bulunamazsa, bu kültürün ana kültürüne geri döner. Bir yana, CultureInfo.Parent özelliği üst kültürü temsil eder. Bu genellikle (ancak her zaman değil), ulusal işaretleyicinin ISO'dan kaldırılması anlamına gelir. Örneğin, Meksika'da İspanyolca konuşulan diyalekt "es-MX" şeklindedir. "‘es’ (herhangi bir ülkeye özgü olmayan İspanyolca) ana dildir."

Sitenizin "fr-CA" kültürünü kullanarak bir "Hoş Geldiniz" kaynağı isteği aldığını düşünün. Yerelleştirme sistemi sırayla aşağıdaki kaynakları arar ve ilk eşleşmeyi seçer:

  • Welcome.fr-CA.resx
  • Welcome.fr.resx
  • Welcome.resx (eğer NeutralResourcesLanguage "fr-CA" ise)

Örneğin, ".fr" kültür belirleyicisini kaldırırsanız ve kültür Fransızca olarak ayarlanırsa, varsayılan kaynak dosyası okunur ve dizeler yerelleştirilir. Resource manager, istenen kültürü hiçbir şey karşılamadığında varsayılan veya geri dönüş kaynağı belirtir. İstenen kültür için bir kaynak bulunamadığında sadece anahtarı döndürmek istiyorsanız, varsayılan kaynak dosyanız bulunmamalıdır.

Visual Studio ile kaynak dosyaları oluşturma

Visual Studio'da dosya adında bir kültür olmadan bir kaynak dosyası oluşturursanız (örneğin, Welcome.resx), Visual Studio her dize için bir özelliği olan bir C# sınıfı oluşturur. Genellikle ASP.NET Core'da istediğiniz bu değildir. Normalde varsayılan bir .resx kaynak dosyanız (kültür adı olmayan bir .resx dosyası) yoktur. .resx dosyasını bir kültür adıyla (örneğin Welcome.fr.resx) oluşturmanızı öneririz. Kültür adıyla bir .resx dosyası oluşturduğunuzda, Visual Studio sınıf dosyasını oluşturmaz.

Diğer kültürleri ekleme

Her dil ve kültür bileşimi (varsayılan dil dışında) benzersiz bir kaynak dosyası gerektirir. ISO dil kodlarının dosya adının bir parçası olduğu (örneğin, en-us, fr-ca ve en-gb) yeni kaynak dosyaları oluşturarak farklı kültürler ve yerel ayarlar için kaynak dosyaları oluşturursunuz. Bu ISO kodları, Welcome.es-MX.resx (İspanyolca/Meksika) içinde olduğu gibi dosya adı ile .resx dosya uzantısı arasına yerleştirilir.

Her istek için dil/kültür seçmek için bir strateji uygulama

Yerelleştirmeyi yapılandırma

Startup.ConfigureServices yönteminde yerelleştirme yapılandırılır.

services.AddLocalization(options => options.ResourcesPath = "Resources");

services.AddMvc()
    .AddViewLocalization(LanguageViewLocationExpanderFormat.Suffix)
    .AddDataAnnotationsLocalization();

  • AddLocalization , yerelleştirme hizmetlerini services kapsayıcısına ekler. Yukarıdaki kod ayrıca kaynak yolunu "Kaynaklar" olarak ayarlar.

  • AddViewLocalization yerelleştirilmiş görünüm dosyaları için destek ekler. Bu örnekteki görünümde yerelleştirme, görünüm dosyasının son ekine dayanmaktadır. Örneğin, Index.fr.cshtml dosyasındaki "fr".

  • AddDataAnnotationsLocalizationsoyutlamalar aracılığıyla DataAnnotations yerelleştirilmiş IStringLocalizer doğrulama iletileri için destek ekler.

Yerelleştirme ara yazılımı

İstekteki geçerli kültür, yerelleştirme Ara Yazılımı'nda ayarlanır. Yerelleştirme orta katman yazılımı Startup.Configure metodunda etkinleştirilir. Yerelleştirme ara yazılımının, istek kültürünü denetleyebilen herhangi bir ara yazılımdan önce yapılandırılması gerekir (örneğin, app.UseMvcWithDefaultRoute()). kullanıyorsanız RouteDataRequestCultureProvider, Yönlendirme Ara Yazılımı'nın ardından Yerelleştirme Ara Yazılımı görünmelidir. Ara yazılım sırası hakkında daha fazla bilgi için bkz. ASP.NET Core Ara Yazılımı.

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

app.UseRequestLocalization(localizationOptions);

UseRequestLocalization bir RequestLocalizationOptions nesneyi başlatır. Her istekte içindeki RequestCultureProvider listesi RequestLocalizationOptions numaralandırılır ve istek kültürünü başarıyla belirleyebilen ilk sağlayıcı kullanılır. Varsayılan sağlayıcılar sınıfından RequestLocalizationOptions gelir:

  1. QueryStringRequestCultureProvider
  2. CookieRequestCultureProvider
  3. AcceptLanguageHeaderRequestCultureProvider

Varsayılan liste en özelden en az belirliye gider. Makalenin ilerleyen bölümlerinde sırayı nasıl değiştirebileceğinizi ve hatta özel bir kültür sağlayıcısı nasıl ekleyebileceğinizi göreceğiz. Sağlayıcılardan hiçbiri istek kültürünü belirleyemezse, DefaultRequestCulture kullanılır.

QueryStringRequestCultureProvider

Bazı uygulamalar, CultureInfo öğesini ayarlamak için bir sorgu dizesi kullanır. veya Accept-Language üst bilgisi yaklaşımını cookie kullanan uygulamalar için URL'ye sorgu dizesi eklemek hata ayıklama ve test kodu için yararlıdır. varsayılan olarak, QueryStringRequestCultureProvider listedeki ilk yerelleştirme sağlayıcısı RequestCultureProvider olarak kaydedilir. ve sorgu dizesi parametrelerini cultureui-culturegeçirirsiniz. Aşağıdaki örnek belirli kültürü (dil ve bölge) İspanyolca/Meksika olarak ayarlar:

http://localhost:5000/?culture=es-MX&ui-culture=es-MX

İkiden yalnızca birini (culture veya ui-culture) geçirirseniz, sorgu dizesi sağlayıcısı her iki değeri de geçirdiğiniz değeri kullanarak ayarlar. Örneğin, yalnızca kültür ayarlanması hem Culture hem de UICulture ayar yapacaktır.

http://localhost:5000/?culture=es-MX

CookieRequestCultureProvider

Üretim uygulamaları genellikle ASP.NET Core kültürü cookieile kültürü ayarlamak için bir mekanizma sağlar. MakeCookieValue yöntemini, bir cookie oluşturmak için kullanın.

, CookieRequestCultureProviderDefaultCookieName kullanıcının tercih edilen kültür bilgilerini izlemek için kullanılan varsayılan cookie adı döndürür. Varsayılan cookie addır .AspNetCore.Culture.

cookie biçimi c=%LANGCODE%|uic=%LANGCODE%, cCulture ve uicUICulture şeklindedir, örneğin:

c=en-UK|uic=en-US

Kültür bilgilerinden ve ui kültüründen yalnızca birini belirtirseniz, belirtilen kültür hem kültür bilgileri hem de kullanıcı arabirimi kültürü için kullanılır.

Accept-Language HTTP üst bilgisi

Accept-Language üst bilgisi çoğu tarayıcıda ayarlanabilir ve başlangıçta kullanıcının dilini belirtmek için tasarlanmıştır. Bu ayar, tarayıcının temel işletim sisteminden ne gönderecek veya devralınacak şekilde ayarlandığını gösterir. Tarayıcı isteğindeki Accept-Language HTTP üst bilgisi, kullanıcının tercih ettiği dili algılamanın yanılgılı bir yolu değildir (bkz . Tarayıcıda dil tercihlerini ayarlama). Üretim uygulaması, bir kullanıcının kendi kültür tercihlerini özelleştirmesi için bir yol içermelidir.

IE'de Accept-Language HTTP üst bilgisini ayarlama

  1. Dişli simgesinden İnternet Seçenekleri'ne dokunun.

  2. Diller'e dokunun.

    İnternet Seçenekleri

  3. Dil Tercihlerini Ayarla'ya dokunun.

  4. Dil ekle'ye dokunun.

  5. Dili ekleyin.

  6. Dile dokunun, ardından Yukarı Taşı'ya dokunun.

Özel sağlayıcı kullanma

Müşterilerinizin dil ve kültürlerini veritabanlarınızda depolamasına izin vermek istediğinizi varsayalım. Kullanıcı için bu değerleri aramak üzere bir sağlayıcı yazabilirsiniz. Aşağıdaki kodda özel sağlayıcının nasıl ekleneceği gösterilmektedir:

private const string enUSCulture = "en-US";

services.Configure<RequestLocalizationOptions>(options =>
{
    var supportedCultures = new[]
    {
        new CultureInfo(enUSCulture),
        new CultureInfo("fr")
    };

    options.DefaultRequestCulture = new RequestCulture(culture: enUSCulture, uiCulture: enUSCulture);
    options.SupportedCultures = supportedCultures;
    options.SupportedUICultures = supportedCultures;

    options.AddInitialRequestCultureProvider(new CustomRequestCultureProvider(async context =>
    {
        // My custom request culture logic
        return await Task.FromResult(new ProviderCultureResult("en"));
    }));
});

Yerelleştirme sağlayıcıları eklemek veya kaldırmak için kullanın RequestLocalizationOptions .

değişiklik isteği kültürü sağlayıcıları sırası

RequestLocalizationOptions üç varsayılan istek kültürü sağlayıcısına sahiptir: QueryStringRequestCultureProvider, CookieRequestCultureProviderve AcceptLanguageHeaderRequestCultureProvider. Aşağıda gösterildiği gibi bu sağlayıcıların sırasını değiştirmek için [RequestLocalizationOptions.RequestCultureProviders]](xref:Microsoft.AspNetCore.Builder.RequestLocalizationOptions.RequestCultureProviders) özelliğini kullanın:

    app.UseRequestLocalization(options =>
    {
        var questStringCultureProvider = options.RequestCultureProviders[0];    
        options.RequestCultureProviders.RemoveAt(0);
        options.RequestCultureProviders.Insert(1, questStringCultureProvider);
    });

Önceki örnekte, QueryStringRequestCultureProvider ve CookieRequestCultureProvider sırası değiştirildiği için RequestLocalizationMiddleware, önce tanımlama bilgilerinden kültürleri, sonra da sorgu dizesini arar.

Daha önce belirtildiği gibi, üzerinden AddInitialRequestCultureProvider sırasını 0olarak ayarlayan özel bir sağlayıcı ekleyin, böylece bu sağlayıcı diğerlerinden önceliklidir.

Kültürü programatik olarak ayarlayın

GitHub'daki bu örnek Localization.StarterWeb projesi, Culture'yi ayarlamak için bir kullanıcı arabirimi içerir. Dosya, Views/Shared/_SelectLanguagePartial.cshtml desteklenen kültürler listesinden kültürü seçmenize olanak tanır:

@using Microsoft.AspNetCore.Builder
@using Microsoft.AspNetCore.Http.Features
@using Microsoft.AspNetCore.Localization
@using Microsoft.AspNetCore.Mvc.Localization
@using Microsoft.Extensions.Options

@inject IViewLocalizer Localizer
@inject IOptions<RequestLocalizationOptions> LocOptions

@{
    var requestCulture = Context.Features.Get<IRequestCultureFeature>();
    var cultureItems = LocOptions.Value.SupportedUICultures
        .Select(c => new SelectListItem { Value = c.Name, Text = c.DisplayName })
        .ToList();
    var returnUrl = string.IsNullOrEmpty(Context.Request.Path) ? "~/" : $"~{Context.Request.Path.Value}";
}

<div title="@Localizer["Request culture provider:"] @requestCulture?.Provider?.GetType().Name">
    <form id="selectLanguage" asp-controller="Home" 
          asp-action="SetLanguage" asp-route-returnUrl="@returnUrl" 
          method="post" class="form-horizontal" role="form">
        <label asp-for="@requestCulture.RequestCulture.UICulture.Name">@Localizer["Language:"]</label> <select name="culture"
          onchange="this.form.submit();"
          asp-for="@requestCulture.RequestCulture.UICulture.Name" asp-items="cultureItems">
        </select>
    </form>
</div>

Dosya Views/Shared/_SelectLanguagePartial.cshtml , düzen dosyasının footer bölümüne eklenir, böylece tüm görünümlerde kullanılabilir:

<div class="container body-content" style="margin-top:60px">
    @RenderBody()
    <hr>
    <footer>
        <div class="row">
            <div class="col-md-6">
                <p>&copy; @System.DateTime.Now.Year - Localization</p>
            </div>
            <div class="col-md-6 text-right">
                @await Html.PartialAsync("_SelectLanguagePartial")
            </div>
        </div>
    </footer>
</div>

SetLanguage yöntemi, kültürünü cookie ayarlar.

[HttpPost]
public IActionResult SetLanguage(string culture, string returnUrl)
{
    Response.Cookies.Append(
        CookieRequestCultureProvider.DefaultCookieName,
        CookieRequestCultureProvider.MakeCookieValue(new RequestCulture(culture)),
        new CookieOptions { Expires = DateTimeOffset.UtcNow.AddYears(1) }
    );

    return LocalRedirect(returnUrl);
}

Bu proje için örnek koduna _SelectLanguagePartial.cshtml takamazsınız. GitHub'daki Localization.StarterWeb projesi, RequestLocalizationOptions bir parçaya aktarmak için Bağımlılık Enjeksiyonu konteynerinden geçen koda Razor sahiptir.

Model bağlama yönlendirme verileri ve sorgu dizeleri

Bkz. Model bağlama yönlendirme verilerinin ve sorgu dizelerinin genelleştirme davranışı.

Genelleştirme ve yerelleştirme terimleri

Uygulamanızı yerelleştirme işlemi, modern yazılım geliştirmede yaygın olarak kullanılan ilgili karakter kümelerinin temel olarak anlaşılmasını ve bunlarla ilişkili sorunların anlaşılmasını da gerektirir. Tüm bilgisayarlar metinleri sayı (kod) olarak depolasa da, farklı sistemler farklı sayılar kullanarak aynı metni depolar. Yerelleştirme işlemi, belirli bir kültür/yerel ayar için uygulama kullanıcı arabirimini (UI) çevirmeyi ifade eder.

Yerelleştirilebilirlik , genelleştirilmiş bir uygulamanın yerelleştirme için hazır olduğunu doğrulamaya yönelik bir ara işlemdir.

Kültür adı için RFC 4646 biçimi, <languagecode2>-<country/regioncode2>burada <languagecode2> dil kodu ve <country/regioncode2> alt kültür kodudur. Örneğin, es-CL İspanyolca (Şili), en-US İngilizce (Birleşik Devletler) ve en-AU İngilizce (Avustralya) için. RFC 4646 , bir dille ilişkilendirilmiş ISO 639 iki harfli küçük harfli kültür kodunun ve bir ülke veya bölgeyle ilişkili ISO 3166 iki harfli büyük harfli alt kültür kodunun bir birleşimidir. Daha fazla bilgi için bkz. System.Globalization.CultureInfo.

Uluslararasılaştırma genellikle "I18N" olarak kısaltılır. Kısaltma, aralarındaki ilk ve son harfleri ve harf sayısını alır, bu nedenle 18, ilk "I" ile son "N" arasındaki harf sayısını ifade eder. Aynı durum Genelleştirme (G11N) ve Yerelleştirme (L10N) için de geçerlidir.

Terms:

  • Genelleştirme (G11N): Uygulama oluşturma işlemi farklı dilleri ve bölgeleri destekler.
  • Yerelleştirme (L10N): Belirli bir dil ve bölge için bir uygulamayı özelleştirme işlemi.
  • Uluslararasılaştırma (I18N): Hem genelleştirmeyi hem de yerelleştirmeyi açıklar.
  • Kültür: Bu bir dil ve isteğe bağlı olarak bir bölgedir.
  • Nötr kültür: Belirli bir dile sahip olan ancak bölge olmayan bir kültür. (örneğin, "en", "es")
  • Belirli bir kültür: Belirtilen dile ve bölgeye sahip bir kültür. (örneğin, "en-US", "en-GB", "es-CL")
  • Ana kültür: Belirli bir kültürü içeren nötr kültür. (örneğin, "en", "en-US" ve "en-GB" için ana kültürdür)
  • Yerel ayar: Yerel ayar, bir kültürle aynıdır.

Note

Ondalık alanlara ondalık virgül girmeniz mümkün olmayabilir. İngilizce olmayan ve ondalık ayırıcı için virgül (",") ile ABD İngilizcesi olmayan tarih biçimleri kullanan yerel ayarlarda jQuery doğrulamasını desteklemek için uygulamanızı küreselleştirme adımlarını uygulamanız gerekir. Bu GitHub'daki 4076 numaralı yoruma ondalık virgül ekleme yönergeleri için bakın.

Note

ASP.NET Core 3.0'dan önceki web uygulamaları, istenen kültür desteklenmiyorsa her istek için bir log kaydı yazar. İstek başına bir LogLevel.Warning günlük kaydı, tekrarlayan bilgiler içeren büyük günlük dosyaları oluşturabilir. Bu davranış ASP.NET Core 3.0'da değiştirilmiştir. türünde RequestLocalizationMiddleware bir günlük LogLevel.Debugyazar ve bu da üretim günlüklerinin boyutunu küçültür.

Ek kaynaklar

  • Last updated on