Implementare una strategia per selezionare la lingua/le impostazioni cultura per ogni richiesta in un'app ASP.NET Core localizzata

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

Un'attività per la localizzazione di un'app consiste nell'implementare una strategia per selezionare le impostazioni cultura appropriate per ogni risposta restituita dall'app.

Configurare il middleware di localizzazione

Le impostazioni cultura correnti in un richiesta sono impostate nel middleware di localizzazione. Il middleware di localizzazione è abilitato in Program.cs. Il middleware di localizzazione deve essere configurato prima di qualsiasi middleware che possa controllare le impostazioni cultura della richiesta , ad esempio app.UseMvcWithDefaultRoute().

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

UseRequestLocalization inizializza un oggetto RequestLocalizationOptions. In ogni richiesta l'elenco di RequestCultureProvider in RequestLocalizationOptions è enumerato e viene usato il primo provider in grado di determinare le impostazioni cultura della richiesta. I provider predefiniti provengono dalla classe RequestLocalizationOptions:

1. QueryStringRequestCultureProvider
2. CookieRequestCultureProvider
3. AcceptLanguageHeaderRequestCultureProvider

L'elenco predefinito passa dal più specifico al meno specifico. Più avanti nell'articolo verrà illustrato come modificare l'ordine e persino aggiungere un provider di impostazioni cultura personalizzato. Se nessuno dei provider è in grado di determinare le impostazioni cultura della richiesta, viene usato DefaultRequestCulture.

QueryStringRequestCultureProvider

Alcune app useranno una stringa di query per impostare .CultureInfo Per le app che usano l'approccio cookie di intestazione o Accept-Language, l'aggiunta di una stringa di query all'URL è utile per il debug e il test del codice. Per impostazione predefinita, QueryStringRequestCultureProvider viene registrato come primo provider di localizzazione nell'elenco RequestCultureProvider. Passare i parametri della stringa di query culture e ui-culture. L'esempio seguente specifica le impostazioni cultura specifiche (lingua e area) per spagnolo/Messico:

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

Se viene passato solo culture o ui-culture , il provider di stringhe di query imposta entrambi i valori usando quello passato. Ad esempio, se si specificano solo le impostazioni cultura verranno impostati entrambi i parametri Culture e UICulture:

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

CookieRequestCultureProvider

Le app di produzione forniscono spesso un meccanismo per impostare le impostazioni cultura con le impostazioni cultura cookiedi base ASP.NET . Usare il MakeCookieValue metodo per creare un oggetto cookie.

Restituisce CookieRequestCultureProviderDefaultCookieName il nome predefinito cookie utilizzato per tenere traccia delle informazioni sulle impostazioni cultura preferite dell'utente. Il nome predefinito cookie è .AspNetCore.Culture.

Il cookie formato è , dove c è Culturec=%LANGCODE%|uic=%LANGCODE%e uic è UICulture, ad esempio:

c=en-UK|uic=en-US

Se vengono fornite solo informazioni cultura o impostazioni cultura dell'interfaccia utente, le impostazioni cultura fornite vengono usate sia per le informazioni sulle impostazioni cultura che per le impostazioni cultura dell'interfaccia utente.

Intestazione HTTP Accept-Language

L'intestazione Accept-Language può essere impostata nella maggior parte dei browser ed è stata originariamente progettata per specificare la lingua dell'utente. Questa impostazione indica la lingua impostata per l'invio da parte del browser o che il browser ha ereditato dal sistema operativo sottostante. L'intestazione HTTP Accept-Language di una richiesta del browser non è un metodo infallibile per individuare la lingua preferita dell'utente (vedere Setting language preferences in a browser (Impostazione delle preferenze di lingua in un browser)). Un'app di produzione deve consentire all'utente di personalizzare le impostazioni cultura.

Impostare l'intestazione HTTP Accept-Language in Edge

1. Cercare Impostazioni lingue preferite.

2. Le lingue preferite sono elencate nella casella Lingue preferite.

3. Selezionare Aggiungi lingue da aggiungere all'elenco.

4. Selezionare Altre azioni ... accanto a una lingua per modificare l'ordine delle preferenze.

Intestazione HTTP content-language

Intestazione dell'entità Content-Language :

• Viene usato per descrivere le lingue destinate al pubblico.
• Consente a un utente di distinguere in base alla lingua preferita degli utenti.

Le intestazioni di entità vengono usate sia nelle richieste HTTP che nelle risposte.

L'intestazione Content-Language può essere aggiunta impostando la proprietà ApplyCurrentCultureToResponseHeaders.

Aggiunta dell'intestazione Content-Language :

• RequestLocalizationMiddleware Consente di impostare l'intestazione Content-Language con .CurrentUICulture
• Elimina la necessità di impostare l'intestazione Content-Language della risposta in modo esplicito.

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

Applicare RouteDataRequest CultureProvider

Imposta RouteDataRequestCultureProvider le impostazioni cultura in base al valore del valore della culture route. Per informazioni su, vedere Provider di impostazioni cultura url che usano il middleware come filtri :

• Uso del middleware come funzionalità di filtri di ASP.NET Core.
• Come usare RouteDataRequestCultureProvider per impostare le impostazioni cultura di un'app dall'URL.

Vedere Applicazione globale di RouteDataRequest CultureProvider con middleware come filtri per informazioni su come applicare a RouteDataRequestCultureProvider livello globale.

Usare un provider personalizzato

Si supponga di voler consentire agli utenti di memorizzare lingua e impostazioni cultura nei database. È possibile creare un provider per la ricerca di questi valori per l'utente. Il codice seguente illustra come aggiungere un provider personalizzato:

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"));
    }));
});

Usare RequestLocalizationOptions per aggiungere o rimuovere i provider di localizzazione.

Modificare l'ordine dei provider di impostazioni cultura della richiesta

RequestLocalizationOptions ha tre provider di impostazioni cultura delle richieste predefinite: QueryStringRequestCultureProvider, CookieRequestCultureProvidere AcceptLanguageHeaderRequestCultureProvider. Usare RequestLocalizationOptions.RequestCultureProviders la proprietà per modificare l'ordine di questi provider, come illustrato di seguito:

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

Nell'esempio precedente, l'ordine di QueryStringRequestCultureProvider e CookieRequestCultureProvider viene modificato, quindi cerca RequestLocalizationMiddleware le impostazioni cultura dalla cookieprima, quindi la stringa di query.

Come accennato in precedenza, aggiungere un provider personalizzato tramite AddInitialRequestCultureProvider il quale imposta l'ordine su 0, quindi questo provider ha la precedenza sugli altri.

Impostazioni cultura di override utente

La proprietà RequestLocalizationOptions.CultureInfoUseUserOverride consente all'app di decidere se usare o meno le impostazioni di Windows non predefinite per le CultureInfoDateTimeFormat proprietà e NumberFormat . Questo non ha alcun impatto su Linux. Corrisponde direttamente a UseUserOverride.

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

Specificare le impostazioni cultura a livello di codice

Questo progetto di esempio Localization.StarterWeb in GitHub contiene l'interfaccia utente per impostare Culture. Il Views/Shared/_SelectLanguagePartial.cshtml file consente di selezionare le impostazioni cultura dall'elenco delle impostazioni cultura supportate:

@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>

Il Views/Shared/_SelectLanguagePartial.cshtml file viene aggiunto alla footer sezione del file di layout in modo che sia disponibile per tutte le visualizzazioni:

<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>

Il SetLanguage metodo imposta le impostazioni cultura cookie.

[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);
}

Non è possibile collegare l'oggetto _SelectLanguagePartial.cshtml al codice di esempio per questo progetto. Il progetto Localization.StarterWeb in GitHub include codice per passare RequestLocalizationOptions a un Razor oggetto parziale tramite il contenitore Dependency Injection .

Dati di route di associazione di modelli e stringhe di query

Vedere Comportamento della globalizzazione dei dati di route di associazione di modelli e stringhe di query.

Passaggi successivi

La localizzazione di un'app comporta anche le attività seguenti:

• Rendere localizzabile il contenuto dell'app.
• Fornire risorse localizzate per le lingue e le impostazioni cultura supportate dall'app

Risorse aggiuntive

• Provider di impostazioni cultura url che usano il middleware come filtri in ASP.NET Core
• Applicazione globale di RouteDataRequest CultureProvider con middleware come filtri
• Globalizzazione e localizzazione in ASP.NET Core
• Rendere localizzabile il contenuto di un'app ASP.NET Core
• Fornire risorse localizzate per lingue e impostazioni cultura in un'app core ASP.NET
• Risolvere i problemi di localizzazione di base di ASP.NET
• Globalizzazione e localizzazione di applicazioni .NET
• Progetto Localization.StarterWeb usato nell'articolo.
• Uso dei file RESX a livello di codice
• Microsoft Multilingual App Toolkit
• Localizzazione e generics