Yerelleştirilmiş ASP.NET Core uygulamasındaki her istek için dil/kültür seçmek için bir strateji uygulama

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

Bir uygulamayı yerelleştirmeye yönelik bir görev, uygulamanın döndürdüğü her yanıt için uygun kültürü seçmeye yönelik bir strateji uygulamaktır.

Yerelleştirme ara yazılımını yapılandırma

İstekteki geçerli kültür, yerelleştirme Ara Yazılımı'nda ayarlanır. Yerelleştirme ara yazılımı içinde Program.csetkindir. 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()).

builder.Services.Configure<RequestLocalizationOptions>(options =>
{
    var supportedCultures = new[] { "en-US", "fr" };
    options.SetDefaultCulture(supportedCultures[0])
        .AddSupportedCultures(supportedCultures)
        .AddSupportedUICultures(supportedCultures);
});

UseRequestLocalization bir RequestLocalizationOptions nesneyi başlatır. Her istekte içindeki RequestLocalizationOptions listesi RequestCultureProvider 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öreceksiniz. Sağlayıcılardan hiçbiri istek kültürünü belirleyemezse, DefaultRequestCulture kullanılır.

QueryStringRequestCultureProvider

Bazı uygulamalar, ayarlamak CultureInfoiç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

Yalnızca culture veya ui-culture geçirilirse, sorgu dizesi sağlayıcısı geçirilen değeri kullanarak her iki değeri de ayarlar. Örneğin, yalnızca kültürün ayarlanması hem hem de Culture ayarını yapacaktır UICulture:

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 bir oluşturmak cookieiçin yöntemini 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%burada cCulture ve uic şeklindedirUICulture, örneğin:

c=en-UK|uic=en-US

Kültür bilgilerinden veya kullanıcı arabirimi kültüründen yalnızca biri sağlanmışsa, sağlanan 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.

Edge'de Accept-Language HTTP üst bilgisini ayarlama

1. Tercih edilen diller için Arama Ayarları.

2. Tercih edilen diller, Tercih edilen diller kutusunda listelenir.

3. Listeye eklemek için Dil ekle'yi seçin.

4. Tercih sırasını değiştirmek için bir dilin yanındaki Diğer eylemler ... öğesini seçin.

İçerik Dili HTTP üst bilgisi

İçerik Dili varlık üst bilgisi:

• Hedef kitleye yönelik dilleri açıklamak için kullanılır.
• Kullanıcının kendi tercih ettiği dile göre ayrım yapmasına izin verir.

Varlık üst bilgileri hem HTTP isteklerinde hem de yanıtlarda kullanılır.

Content-Language üst bilgisi özelliği ApplyCurrentCultureToResponseHeadersayarlanarak eklenebilir.

Content-Language Üst bilgi ekleniyor:

• RequestLocalizationMiddleware üst bilgisini ile ayarlamasına Content-LanguageCurrentUICultureizin verir.
• Yanıt üst bilgisini Content-Language açıkça ayarlama gereksinimini ortadan kaldırır.

app.UseRequestLocalization(new RequestLocalizationOptions
{
    ApplyCurrentCultureToResponseHeaders = true
});

RouteDataRequest CultureProvider'i uygulama

, RouteDataRequestCultureProvider rota değerinin değerine culture göre kültürü ayarlar. Aşağıdakiler hakkında bilgi için bkz . Ara yazılımı filtre olarak kullanan URL kültürü sağlayıcısı:

• ara yazılımı ASP.NET Core'un filtre olarak kullanma özelliği.
• Url'den bir uygulamanın kültürünü ayarlamak için kullanma RouteDataRequestCultureProvider .

Genel olarak uygulama RouteDataRequestCultureProvider hakkında bilgi için bkz. Ara yazılım ile RouteDataRequest CultureProvider'ı genel olarak uygulama.

Ö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 özelliğini kullanın RequestLocalizationOptions.RequestCultureProviders :

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

Yukarıdaki örnekte, ve'nin QueryStringRequestCultureProviderCookieRequestCultureProvider sırası değiştirildiğinden RequestLocalizationMiddleware , önce kültürleri cookie, sonra 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.

Kullanıcı geçersiz kılma kültürü

RequestLocalizationOptions.CultureInfoUseUserOverride özelliği, uygulamanın ve NumberFormat özellikleri için varsayılan olmayan Windows ayarlarını kullanıp kullanmayeceğine karar vermesine CultureInfoDateTimeFormat olanak tanır. Bunun Linux üzerinde hiçbir etkisi yoktur. Bu doğrudan öğesine UseUserOverridekarşılık gelir.

    app.UseRequestLocalization(options =>
    {
        options.CultureInfoUseUserOverride = false;
    });

Kültürü program aracılığıyla ayarlama

GitHub'dabu örnek Localization.StarterWeb projesi, ayarlamak Cultureiçin kullanıcı arabirimini 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ü cookieayarlar.

[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 kodu takamazsınız _SelectLanguagePartial.cshtml . GitHub'da Localization.StarterWeb projesi, Bağımlılık Ekleme kapsayıcısı aracılığıyla öğesini kısmi akışa Razor aktaracak koda RequestLocalizationOptions sahiptir.

Model bağlama yönlendirme verileri ve sorgu dizeleri

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

Sonraki adımlar

Bir uygulamayı yerelleştirmek aşağıdaki görevleri de içerir:

• Uygulamanın içeriğini yerelleştirilebilir hale getirin.
• Uygulamanın desteklediği diller ve kültürler için yerelleştirilmiş kaynaklar sağlama

Ek kaynaklar

• ASP.NET Core'da ara yazılımı filtre olarak kullanan URL kültürü sağlayıcısı
• RouteDataRequest CultureProvider'i genel olarak ara yazılımla filtre olarak uygulama
• ASP.NET Core'da genelleştirme ve yerelleştirme
• ASP.NET Core uygulamasının içeriğini yerelleştirilebilir hale getirme
• ASP.NET Core uygulamasında diller ve kültürler için yerelleştirilmiş kaynaklar sağlama
• ASP.NET Çekirdek yerelleştirme sorunlarını giderme
• .NET uygulamalarını genelleştirme ve yerelleştirme
• Makalede kullanılan Localization.StarterWeb projesi .
• .resx Dosyalarındaki Kaynaklar
• Microsoft Çok Dilli Uygulama Araç Seti
• Yerelleştirme ve Genel Değerler