Implémenter une stratégie pour sélectionner la langue/culture de chaque requête dans une application ASP.NET Core localisée

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

L’une des tâches de localisation d’une application consiste à implémenter une stratégie de sélection de la culture appropriée pour chaque réponse retournée par l’application.

Configurer l’intergiciel de localisation

La culture actuelle sur une requête est définie dans l’intergiciel (middleware) de localisation. L’intergiciel de localisation est activé dans Program.cs. L’intergiciel de localisation doit être configuré avant tout intergiciel susceptible de vérifier la culture de la requête (par exemple, app.UseMvcWithDefaultRoute()).

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

UseRequestLocalization initialise un objet RequestLocalizationOptions. Sur chaque requête, la liste de RequestCultureProvider dans RequestLocalizationOptions est énumérée et le premier fournisseur capable de déterminer correctement la culture de la requête est utilisé. Les fournisseurs par défaut proviennent de la classe RequestLocalizationOptions :

1. QueryStringRequestCultureProvider
2. CookieRequestCultureProvider
3. AcceptLanguageHeaderRequestCultureProvider

La liste par défaut va du plus spécifique au moins spécifique. Plus loin dans l’article, vous verrez comment vous pouvez modifier l’ordre et même ajouter un fournisseur de culture personnalisé. Si aucun des fournisseurs ne peut déterminer la culture de la requête, DefaultRequestCulture est utilisé.

QueryStringRequestCultureProvider

Certaines applications utilisent une chaîne de requête pour définir la CultureInfo. Pour les applications qui utilisent l’approche du cookie ou de l’en-tête Accept-Language, l’ajout d’une chaîne de requête à l’URL s’avère utile pour déboguer et tester le code. Par défaut, QueryStringRequestCultureProvider est inscrit en tant que premier fournisseur de localisation dans la liste RequestCultureProvider. Vous passez les paramètres de chaîne de requête culture et ui-culture. L’exemple suivant affecte à la culture spécifique (langue et région) la valeur espagnol/Mexique :

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

Si seul culture ou ui-culture est transmis, le fournisseur de chaînes de requête définit les deux valeurs à l’aide de celle transmise. Par exemple, la seule définition de la culture définit à la fois Culture et UICulture :

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

CookieRequestCultureProvider

Les applications de production fournissent souvent un mécanisme permettant de définir la culture à l’aide du cookie de culture ASP.NET Core. Utilisez la méthode MakeCookieValue pour créer un cookie.

CookieRequestCultureProviderDefaultCookieName retourne le nom de cookie par défaut utilisé pour effectuer le suivi des informations de culture préférée de l’utilisateur. Le nom cookie par défaut est .AspNetCore.Culture.

Le format du cookie est c=%LANGCODE%|uic=%LANGCODE%, où c correspond à Culture et uic correspond à UICulture, par exemple :

c=en-UK|uic=en-US

Si une seule des informations de culture ou cultures de l’interface utilisateur est fournie, la culture fournie est utilisée à la fois pour les informations de culture et la culture de l’interface utilisateur.

En-tête HTTP Accept-Language

L’en-tête Accept-Language peut être défini dans la plupart des navigateurs et a d’abord été conçu pour spécifier la langue de l’utilisateur. Ce paramètre indique ce que le navigateur doit envoyer ou ce dont il a hérité du système d’exploitation sous-jacent. L’en-tête HTTP Accept-Language d’une requête de navigateur n’est pas un moyen infaillible de détecter la langue préférée de l’utilisateur (consultez Définition des préférences de langue dans un navigateur). Une application de production doit inclure un moyen permettant à l’utilisateur de personnaliser son choix de culture.

Définir l’en-tête HTTP Accept-Language dans Edge

1. Recherchez Langues préférées dans les Paramètres.

2. Les langues préférées sont répertoriées dans la zone Langues préférées.

3. Sélectionnez Ajouter des langues pour en ajouter à la liste.

4. Sélectionnez Plus d’actions... en regard d’une langue pour modifier l’ordre de préférence.

En-tête HTTP Content-Language

L’en-tête d’entité Content-Language :

• Est utilisé pour décrire la ou les langues destinées au public.
• Permet à un utilisateur de différencier en fonction de la langue préférée de l’utilisateur.

Les en-têtes d’entité sont utilisés dans les requêtes et les réponses HTTP.

L’en-tête Content-Language peut être ajouté en définissant la propriété ApplyCurrentCultureToResponseHeaders.

Ajout de l’en-tête Content-Language :

• Permet à RequestLocalizationMiddleware de définir l’en-tête Content-Language avec CurrentUICulture.
• Élimine la nécessité de définir explicitement l’en-tête de réponse Content-Language.

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

Appliquer RouteDataRequest CultureProvider

RouteDataRequestCultureProvider permet de définir la culture en fonction de la valeur de la route culture. Consultez Fournisseur de culture d’URL qui utilise des intergiciels comme filtres pour obtenir des informations sur :

• Utilisation de l’intergiciel comme la fonctionnalité des filtres de ASP.NET Core.
• Procédure d’utilisation de RouteDataRequestCultureProvider pour définir la culture d’une application à partir de l’URL.

Consultez Application globale de RouteDataRequest CultureProvider avec des intergiciels en tant que filtres pour obtenir plus d’informations sur l’application de RouteDataRequestCultureProvider globalement.

Utiliser un fournisseur personnalisé

Supposons que vous vouliez permettre à vos clients de stocker leur langue et leur culture dans vos bases de données. Vous pouvez écrire un fournisseur pour rechercher ces valeurs pour l’utilisateur. Le code suivant illustre l’ajout d’un fournisseur personnalisé :

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

Utilisez RequestLocalizationOptions pour ajouter ou supprimer des fournisseurs de localisation.

Modifier l’ordre des fournisseurs de culture de requête

RequestLocalizationOptions a trois fournisseurs de culture de requête par défaut : QueryStringRequestCultureProvider, CookieRequestCultureProvider et AcceptLanguageHeaderRequestCultureProvider. Utilisez la propriété RequestLocalizationOptions.RequestCultureProviders pour modifier l’ordre de ces fournisseurs, comme indiqué ci-dessous :

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

Dans l’exemple précédent, l’ordre de QueryStringRequestCultureProvider et CookieRequestCultureProvider étant commuté, RequestLocalizationMiddleware recherche d’abord les cultures dans les cookies, puis dans la chaîne de requête.

Comme mentionné précédemment, ajoutez un fournisseur personnalisé via AddInitialRequestCultureProvider, qui définit l’ordre de 0, de sorte que ce fournisseur est prioritaire sur les autres.

Remplacement de culture de l’utilisateur

La propriété RequestLocalizationOptions.CultureInfoUseUserOverride permet à l’application de décider s’il faut ou non utiliser les paramètres Windows autres que ceux par défaut pour les propriétés CultureInfoDateTimeFormat et NumberFormat. Cela n’a aucun impact sur Linux. Cela correspond directement à UseUserOverride.

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

Définir la culture par programmation

Cet exemple de projet Localization.StarterWeb sur GitHub contient l’interface utilisateur permettant de définir Culture. Le fichier Views/Shared/_SelectLanguagePartial.cshtml vous permet de sélectionner la culture dans la liste des cultures prises en charge :

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

Le fichier Views/Shared/_SelectLanguagePartial.cshtml est ajouté à la section footer du fichier de disposition afin d’être disponible pour toutes les vues :

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

La méthode SetLanguage définit le cookie de la culture.

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

Vous ne pouvez pas connecter _SelectLanguagePartial.cshtml pour obtenir un exemple de code pour ce projet. Le projet Localization.StarterWeb sur GitHub comporte du code pour faire passer RequestLocalizationOptions à une ligne de code partiellement exécutée Razor par le biais du conteneur Injection de dépendances.

Données de routage et chaînes de requête de liaison de modèle

Consultez Comportement de globalisation des données de routage et des chaînes de requête de liaison de modèle.

Étapes suivantes

La localisation d’une application implique également les tâches suivantes :

• Rendre le contenu de l’application localisable.
• Fournir des ressources localisées aux langues et cultures prises en charge par l’application

Ressources supplémentaires

• Fournisseur de culture d’URL qui utilise des intergiciels comme filtres dans ASP.NET Core
• Application globale de RouteDataRequest CultureProvider avec des intergiciel en tant que filtres
• Globalisation et localisation dans ASP.NET Core
• Rendre le contenu d’une application ASP.NET Core localisable
• Fournir des ressources localisées pour les langues et les cultures dans une application ASP.NET Core
• Résoudre les problèmes liés à la localisation ASP.NET Core
• Internationalisation et localisation d’applications .NET
• Projet Localization.StarterWeb utilisé dans l’article.
• Ressources dans les fichiers .resx
• Kit de ressources pour application multilingue Microsoft
• Localisation et classes génériques