ASP.NET Globalizzazione e localizzazione di base Blazor

Questo articolo illustra come eseguire il rendering del contenuto globalizzato e localizzato agli utenti in lingue e impostazioni cultura diverse.

Per la globalizzazione, Blazor fornisce la formattazione di numeri e date. Per la localizzazione, Blazor esegue il rendering del contenuto usando il sistema .NET Resources.

Sono supportati un set limitato di funzionalità di localizzazione di ASP.NET Core:

✔️Supportato:IStringLocalizer e IStringLocalizer<T> sono supportati nelle Blazor app.

❌La localizzazione delle annotazioni dei dati non supportate:IHtmlLocalizerIViewLocalizer e le annotazioni dei dati sono ASP.NET funzionalità core MVC e non supportate nelle Blazor app.

Questo articolo descrive come usare Blazorle funzionalità di globalizzazione e localizzazione basate su:

• IntestazioneAccept-Language, impostata dal browser in base alle preferenze di lingua di un utente nelle impostazioni del browser.
• Impostazioni cultura impostate dall'app non in base al valore dell'intestazioneAccept-Language. L'impostazione può essere statica per tutti gli utenti o dinamica in base alla logica dell'app. Quando l'impostazione si basa sulla preferenza dell'utente, l'impostazione viene in genere salvata per ricaricare le visite future.

Per altre informazioni generali, vedere le risorse seguenti:

• Globalizzazione e localizzazione in ASP.NET Core
• Nozioni fondamentali su .NET: Globalizzazione
• Nozioni fondamentali su .NET: localizzazione

Spesso, i termini lingua e cultura vengono usati in modo intercambiabile quando si gestiscono concetti di globalizzazione e localizzazione.

In questo articolo la lingua fa riferimento alle selezioni effettuate da un utente nelle impostazioni del browser. Le selezioni della lingua dell'utente vengono inviate nelle richieste del browser nell'intestazioneAccept-Language. Le impostazioni del browser usano in genere la parola "lingua" nell'interfaccia utente.

Le impostazioni cultura riguardano i membri di .NET e Blazor API. Ad esempio, la richiesta di un utente può includere l'intestazione Accept-Language che specifica una lingua dal punto di vista dell'utente, ma l'app imposta infine la CurrentCulture proprietà ("culture") dalla lingua richiesta dall'utente. L'API usa in genere la parola "culture" nei nomi dei membri.

Nota

Gli esempi di codice in questo articolo adottano tipi di riferimento nullable (NRT) e l'analisi statica dello stato null del compilatore .NET, supportati in ASP.NET Core 6.0 o versione successiva. Quando la destinazione è ASP.NET Core 5.0 o versioni precedenti, rimuovere la designazione di tipo Null (?) dagli esempi dell'articolo.

In questo articolo vengono usati i termini lato client/e lato server/per distinguere le posizioni in cui viene eseguito il codice dell'app:

• Lato/client
  • Rendering lato client (CSR) di un'app Blazor Web. Il Program file è Program.cs del progetto client (.Client). Blazor La configurazione di avvio dello script è disponibile nel App componente (Components/App.razor) del progetto server. I componenti della modalità di rendering Interattiva WebAssembly e Interactive Auto con una @page direttiva vengono inseriti nella cartella del Pages progetto client. Posizionare componenti condivisi non instradabili nella radice del .Client progetto o in cartelle personalizzate in base alla funzionalità del componente.
  • Un'app Blazor WebAssembly . Il Program file è Program.cs. Blazor La configurazione di avvio dello wwwroot/index.html script è disponibile nel file .
• Lato/ server: rendering interattivo lato server (SSR interattivo) di un'app Blazor Web. Il Program file è Program.cs del progetto server. Blazor La configurazione di avvio dello App script si trova nel componente (Components/App.razor). Solo i componenti della modalità di rendering Interactive Server instradabili con una @page direttiva vengono inseriti nella Components/Pages cartella . I componenti condivisi non instradabili vengono inseriti nella cartella del Components progetto server. Creare cartelle personalizzate in base alla funzionalità del componente in base alle esigenze.

Globalizzazione

La @bind direttiva attribute applica i formati e analizza i valori per la visualizzazione in base alla prima lingua preferita dell'utente supportata dall'app. @bind supporta il @bind:culture parametro per fornire un oggetto System.Globalization.CultureInfo per l'analisi e la formattazione di un valore.

È possibile accedere alle impostazioni cultura correnti dalla System.Globalization.CultureInfo.CurrentCulture proprietà .

CultureInfo.InvariantCulture viene usato per i tipi di campo seguenti (<input type="{TYPE}" />, dove il {TYPE} segnaposto è il tipo):

• date
• number

Tipi di campo precedenti:

• Vengono visualizzati usando le regole di formattazione appropriate basate su browser.
• Non può contenere testo in formato libero.
• Specificare le caratteristiche di interazione dell'utente in base all'implementazione del browser.

Quando si usano i date tipi di campo e number , non è consigliabile specificare impostazioni cultura con @bind:culture perché Blazor fornisce il supporto predefinito per il rendering dei valori nelle impostazioni cultura correnti.

I tipi di campo seguenti hanno requisiti di formattazione specifici e non sono attualmente supportati da Blazor perché non sono supportati da tutti i principali browser:

• datetime-local
• month
• week

Per il supporto corrente del browser dei tipi precedenti, vedere È possibile usare.

Supporto per la globalizzazione di .NET e i componenti internazionali per Unicode (ICU) (Blazor WebAssembly)

Blazor WebAssembly usa un'API di globalizzazione ridotta e un set di impostazioni locali predefinite di Componenti internazionali per le impostazioni locali Unicode .Uses a reduced globalization API and set of built-in International Components for Unicode (ICU). Per altre informazioni, vedere Globalizzazione .NET e ICU: ICU in WebAssembly.

Per caricare un file di dati di ICU personalizzato per controllare le impostazioni locali dell'app, vedere WASM Globalization Icu. Attualmente, è necessario compilare manualmente il file di dati di ICU personalizzato. Gli strumenti .NET per semplificare il processo di creazione del file sono pianificati per .NET 9 a novembre 2024.

Globalizzazione invariante

Se l'app non richiede la localizzazione, configurare l'app per supportare le impostazioni cultura invarianti, in genere basate su Stati Uniti inglese (en-US). Impostare la InvariantGlobalization proprietà su true nel file di progetto dell'app (.csproj):

<PropertyGroup>
  <InvariantGlobalization>true</InvariantGlobalization>
</PropertyGroup>

In alternativa, configurare la globalizzazione invariante con gli approcci seguenti:

• In runtimeconfig.json:

  {
    "runtimeOptions": {
      "configProperties": {
        "System.Globalization.Invariant": true
      }
    }
  }
  

• Con una variabile di ambiente:

  • Chiave: DOTNET_SYSTEM_GLOBALIZATION_INVARIANT
  • Valore: true o 1

Per altre informazioni, vedere Opzioni di configurazione del runtime per la globalizzazione (documentazione di .NET).

Componente dimostrativo

Il componente seguente CultureExample1 può essere usato per illustrare Blazor i concetti relativi alla globalizzazione e alla localizzazione trattati in questo articolo.

CultureExample1.razor:

@page "/culture-example-1"
@using System.Globalization

<h1>Culture Example 1</h1>

<p>
    <b>CurrentCulture</b>: @CultureInfo.CurrentCulture
</p>

<h2>Rendered values</h2>

<ul>
    <li><b>Date</b>: @dt</li>
    <li><b>Number</b>: @number.ToString("N2")</li>
</ul>

<h2><code>&lt;input&gt;</code> elements that don't set a <code>type</code></h2>

<p>
    The following <code>&lt;input&gt;</code> elements use
    <code>CultureInfo.CurrentCulture</code>.
</p>

<ul>
    <li><label><b>Date:</b> <input @bind="dt" /></label></li>
    <li><label><b>Number:</b> <input @bind="number" /></label></li>
</ul>

<h2><code>&lt;input&gt;</code> elements that set a <code>type</code></h2>

<p>
    The following <code>&lt;input&gt;</code> elements use
    <code>CultureInfo.InvariantCulture</code>.
</p>

<ul>
    <li><label><b>Date:</b> <input type="date" @bind="dt" /></label></li>
    <li><label><b>Number:</b> <input type="number" @bind="number" /></label></li>
</ul>

@code {
    private DateTime dt = DateTime.Now;
    private double number = 1999.69;
}

Il formato della stringa numerica () nell'esempio precedente (N2.ToString("N2")) è un identificatore di formato numerico .NET standard. Il N2 formato è supportato per tutti i tipi numerici, include un separatore di gruppo ed esegue il rendering fino a due posizioni decimali.

Facoltativamente, aggiungere una voce di menu al riquadro di spostamento nel NavMenu componente (NavMenu.razor) per il CultureExample1 componente.

Impostare dinamicamente le impostazioni cultura dall'intestazione Accept-Language

Aggiungere il Microsoft.Extensions.Localization pacchetto all'app.

L'intestazione Accept-Language viene impostata dal browser e controllata dalle preferenze di lingua dell'utente nelle impostazioni del browser. Nelle impostazioni del browser, un utente imposta una o più lingue preferite in ordine di preferenza. L'ordine delle preferenze viene utilizzato dal browser per impostare i valori di qualità (q, 0-1) per ogni lingua nell'intestazione. L'esempio seguente specifica Stati Uniti inglese, inglese e spagnolo cileno con una preferenza per Stati Uniti inglese o inglese:

Accept-Language: en-US,en; q=0.9,es-CL; q=0.8

Le impostazioni cultura dell'app vengono impostate associando la prima lingua richiesta corrispondente alle impostazioni cultura supportate dell'app.

Nello sviluppo sul lato client impostare la BlazorWebAssemblyLoadAllGlobalizationData proprietà su true nel file di progetto dell'app sul lato client (.csproj):

<PropertyGroup>
  <BlazorWebAssemblyLoadAllGlobalizationData>true</BlazorWebAssemblyLoadAllGlobalizationData>
</PropertyGroup>

Nota

Se la specifica dell'app richiede la limitazione delle impostazioni cultura supportate a un elenco esplicito, vedere la sezione Impostazione dinamica delle impostazioni cultura lato client in base alle preferenze utente di questo articolo.

Le app vengono localizzate usando il middleware di localizzazione. Aggiungere servizi di localizzazione all'app con AddLocalization.

Aggiungere la riga seguente al file in Program cui vengono registrati i servizi:

builder.Services.AddLocalization();

Nello sviluppo lato server è possibile specificare le impostazioni cultura supportate dell'app immediatamente dopo l'aggiunta del middleware di routing alla pipeline di elaborazione. L'esempio seguente configura le impostazioni cultura supportate per Stati Uniti spagnolo inglese e cileno:

app.UseRequestLocalization(new RequestLocalizationOptions()
    .AddSupportedCultures(new[] { "en-US", "es-CL" })
    .AddSupportedUICultures(new[] { "en-US", "es-CL" }));

Per informazioni sull'ordinamento del middleware di localizzazione nella pipeline middleware del Program file, vedere ASP.NET Middleware core.

Usare il CultureExample1 componente illustrato nella sezione Componente dimostrativo per studiare il funzionamento della globalizzazione. Eseguire una richiesta con Stati Uniti inglese (en-US). Passare allo spagnolo cileno (es-CL) nelle impostazioni della lingua del browser. Richiedere di nuovo la pagina Web.

Nota

Alcuni browser forzano l'uso dell'impostazione della lingua predefinita sia per le richieste che per le impostazioni dell'interfaccia utente del browser. Ciò può rendere difficile modificare la lingua in uno che si capisce difficile perché tutte le schermate dell'interfaccia utente delle impostazioni potrebbero terminare in una lingua che non è possibile leggere. Un browser come Opera è una buona scelta per il test perché consente di impostare una lingua predefinita per le richieste di pagine Web, ma lasciare l'interfaccia utente delle impostazioni del browser nella lingua.

Quando le impostazioni cultura sono Stati Uniti inglese (en-US), il componente sottoposto a rendering usa la formattazione della data mese/giorno (6/7), l'ora di 12 ore (PMAM/) e i separatori di virgole in numeri con un punto per il valore decimale ():1,999.69

• Data: 7/6/2021 6:45:22
• Numero: 1.999.69

Quando le impostazioni cultura sono spagnolo cileno (es-CL), il componente sottoposto a rendering usa la formattazione della data giorno/mese (7/6), l'ora di 24 ore e i separatori di periodo in numeri con una virgola per il valore decimale (1.999,69):

• Data: 6/7/2021 6:49:38
• Numero: 1,999,69

Impostare in modo statico le impostazioni cultura lato client

Impostare la BlazorWebAssemblyLoadAllGlobalizationData proprietà su true nel file di progetto dell'app (.csproj):

<PropertyGroup>
  <BlazorWebAssemblyLoadAllGlobalizationData>true</BlazorWebAssemblyLoadAllGlobalizationData>
</PropertyGroup>

Le impostazioni cultura dell'app possono essere impostate in JavaScript quando Blazor inizia con l'opzione applicationCultureBlazor start. L'esempio seguente configura l'app per l'avvio usando le impostazioni cultura inglese (en-US) Stati Uniti.

Impedire l'avvio Blazor automatico aggiungendo autostart="false" al Blazortag script di :

<script src="{BLAZOR SCRIPT}" autostart="false"></script>

Nell'esempio precedente il {BLAZOR SCRIPT} segnaposto è il percorso dello script e il Blazor nome del file. Per la posizione dello script, vedere ASP.NET Struttura del progetto CoreBlazor.

Aggiungere il blocco seguente <script> dopo Blazoril tag e prima del tag di <script> chiusura </body> :

Blazor App Web:

<script>
  Blazor.start({
    webAssembly: {
      applicationCulture: 'en-US'
    }
  });
</script>

Blazor WebAssembly autonomo:

<script>
  Blazor.start({
    applicationCulture: 'en-US'
  });
</script>

Il valore per applicationCulture deve essere conforme al formato del tag di lingua BCP-47. Per altre informazioni sull'avvio di Blazor, vedere Avvio di ASP.NET Core Blazor.

Un'alternativa all'impostazione dell'opzione iniziale delle impostazioni cultura Blazorconsiste nell'impostare le impostazioni cultura nel codice C#. Impostare CultureInfo.DefaultThreadCurrentCulture e CultureInfo.DefaultThreadCurrentUICulture nel Program file sulle stesse impostazioni cultura.

Aggiungere lo System.Globalization spazio dei nomi al Program file:

using System.Globalization;

Aggiungere le impostazioni cultura prima della riga che compila ed esegue (WebAssemblyHostBuilderawait builder.Build().RunAsync();):

CultureInfo.DefaultThreadCurrentCulture = new CultureInfo("en-US");
CultureInfo.DefaultThreadCurrentUICulture = new CultureInfo("en-US");

Importante

Impostare DefaultThreadCurrentCulture sempre e DefaultThreadCurrentUICulture sulle stesse impostazioni cultura per usare IStringLocalizer e IStringLocalizer<T>.

Usare il CultureExample1 componente illustrato nella sezione Componente dimostrativo per studiare il funzionamento della globalizzazione. Eseguire una richiesta con Stati Uniti inglese (en-US). Passare allo spagnolo cileno (es-CL) nelle impostazioni della lingua del browser. Richiedere di nuovo la pagina Web. Quando la lingua richiesta è lo spagnolo cileno, le impostazioni cultura dell'app rimangono Stati Uniti inglese (en-US).

Impostare in modo statico le impostazioni cultura lato server

Le app sul lato server vengono localizzate usando il middleware di localizzazione. Aggiungere servizi di localizzazione all'app con AddLocalization.

Nel file Program:

builder.Services.AddLocalization();

Specificare le impostazioni cultura statiche nel Program file immediatamente dopo l'aggiunta del middleware di routing alla pipeline di elaborazione. L'esempio seguente configura Stati Uniti inglese:

app.UseRequestLocalization("en-US");

Il valore delle impostazioni cultura per UseRequestLocalization deve essere conforme al formato del tag di lingua BCP-47.

Per informazioni sull'ordinamento del middleware di localizzazione nella pipeline middleware del Program file, vedere ASP.NET Middleware core.

Usare il CultureExample1 componente illustrato nella sezione Componente dimostrativo per studiare il funzionamento della globalizzazione. Eseguire una richiesta con Stati Uniti inglese (en-US). Passare allo spagnolo cileno (es-CL) nelle impostazioni della lingua del browser. Richiedere di nuovo la pagina Web. Quando la lingua richiesta è lo spagnolo cileno, le impostazioni cultura dell'app rimangono Stati Uniti inglese (en-US).

Impostare dinamicamente le impostazioni cultura lato client in base alle preferenze utente

Esempi di posizioni in cui un'app potrebbe archiviare le preferenze di un utente includono nell'archiviazione locale del browser (comune per gli scenari lato client), in una localizzazione cookie o in un database (comune per scenari lato server) o in un servizio esterno collegato a un database esterno e accessibile da un'API Web. Nell'esempio seguente viene illustrato come usare l'archiviazione locale del browser.

Aggiungere il Microsoft.Extensions.Localization pacchetto all'app.

Nota

Per indicazioni sull'aggiunta di pacchetti alle app .NET, vedere gli articoli sotto Installare e gestire pacchetti in Flusso di lavoro dell'utilizzo di pacchetti (documentazione di NuGet). Confermare le versioni corrette del pacchetto all'indirizzo NuGet.org.

Impostare la BlazorWebAssemblyLoadAllGlobalizationData proprietà su true nel file di progetto:

<PropertyGroup>
  <BlazorWebAssemblyLoadAllGlobalizationData>true</BlazorWebAssemblyLoadAllGlobalizationData>
</PropertyGroup>

Le impostazioni cultura dell'app per il rendering lato client sono impostate usando l'API Blazor del framework. La selezione delle impostazioni cultura di un utente può essere salvata in modo permanente nell'archiviazione locale del browser.

Fornire JS funzioni per ottenere e impostare la selezione delle impostazioni cultura dell'utente con l'archiviazione locale del browser:

<script>
  window.blazorCulture = {
    get: () => window.localStorage['BlazorCulture'],
    set: (value) => window.localStorage['BlazorCulture'] = value
  };
</script>

Nota

L'esempio precedente inquina il client con metodi globali. Per un approccio migliore nelle app di produzione, vedere Isolamento JavaScript nei moduli JavaScript.

Aggiungere gli spazi dei nomi per System.Globalization e Microsoft.JSInterop all'inizio del Program file:

using System.Globalization;
using Microsoft.JSInterop;

Rimuovere la riga seguente:

- await builder.Build().RunAsync();

Sostituire la riga precedente con il codice seguente. Il codice aggiunge Blazoril servizio di localizzazione alla raccolta di servizi dell'app con AddLocalization e usa JS l'interoperabilità per chiamare JS e recuperare la selezione delle impostazioni cultura dell'utente dalla risorsa di archiviazione locale. Se l'archiviazione locale non contiene impostazioni cultura per l'utente, il codice imposta un valore predefinito di Stati Uniti inglese (en-US).

builder.Services.AddLocalization();

var host = builder.Build();

CultureInfo culture;
var js = host.Services.GetRequiredService<IJSRuntime>();
var result = await js.InvokeAsync<string>("blazorCulture.get");

if (result != null)
{
    culture = new CultureInfo(result);
}
else
{
    culture = new CultureInfo("en-US");
    await js.InvokeVoidAsync("blazorCulture.set", "en-US");
}

CultureInfo.DefaultThreadCurrentCulture = culture;
CultureInfo.DefaultThreadCurrentUICulture = culture;

await host.RunAsync();

Importante

Impostare DefaultThreadCurrentCulture sempre e DefaultThreadCurrentUICulture sulle stesse impostazioni cultura per usare IStringLocalizer e IStringLocalizer<T>.

Il componente seguente CultureSelector illustra come eseguire le azioni seguenti:

• Impostare la selezione delle impostazioni cultura dell'utente nell'archiviazione locale del browser tramite JS interoperabilità.
• Ricaricare il componente richiesto (forceLoad: true), che usa le impostazioni cultura aggiornate.

CultureSelector.razor:

@using  System.Globalization
@inject IJSRuntime JS
@inject NavigationManager Navigation

<p>
    <label>
        Select your locale:
        <select @bind="Culture">
            @foreach (var culture in supportedCultures)
            {
                <option value="@culture">@culture.DisplayName</option>
            }
        </select>
    </label>
</p>

@code
{
    private CultureInfo[] supportedCultures = new[]
    {
        new CultureInfo("en-US"),
        new CultureInfo("es-CL"),
    };

    private CultureInfo Culture
    {
        get => CultureInfo.CurrentCulture;
        set
        {
            if (CultureInfo.CurrentCulture != value)
            {
                var js = (IJSInProcessRuntime)JS;
                js.InvokeVoid("blazorCulture.set", value.Name);

                Navigation.NavigateTo(Navigation.Uri, forceLoad: true);
            }
        }
    }
}

Nota

Per altre informazioni su IJSInProcessRuntime, vedere Chiamare le funzioni JavaScript dai metodi .NET in ASP.NET Core Blazor.

All'interno del tag di chiusura dell'elemento </main> nel MainLayout componente (MainLayout.razor), aggiungere il CultureSelector componente:

<article class="bottom-row px-4">
    <CultureSelector />
</article>

Usare il CultureExample1 componente illustrato nella sezione Componente dimostrativo per studiare il funzionamento dell'esempio precedente.

Impostare dinamicamente le impostazioni cultura lato server in base alle preferenze utente

Esempi di posizioni in cui un'app potrebbe archiviare le preferenze di un utente includono nell'archiviazione locale del browser (comune per gli scenari lato client), in una localizzazione cookie o in un database (comune per scenari lato server) o in un servizio esterno collegato a un database esterno e accessibile da un'API Web. Nell'esempio seguente viene illustrato come usare una localizzazione cookie.

Nota

Nell'esempio seguente si presuppone che l'app adotta l'interattività globale specificando il rendering interattivo lato server (SSR interattivo) nel Routes componente App (Components/App.razor):

<Routes @rendermode="InteractiveServer" />

Se l'app adotta l'interattività per pagina/componente , vedi le osservazioni alla fine di questa sezione per modificare le modalità di rendering dei componenti dell'esempio.

Aggiungere il Microsoft.Extensions.Localization pacchetto all'app.

Nota

Per indicazioni sull'aggiunta di pacchetti alle app .NET, vedere gli articoli sotto Installare e gestire pacchetti in Flusso di lavoro dell'utilizzo di pacchetti (documentazione di NuGet). Confermare le versioni corrette del pacchetto all'indirizzo NuGet.org.

Le app sul lato server vengono localizzate usando il middleware di localizzazione. Aggiungere servizi di localizzazione all'app con AddLocalization.

Nel file Program:

builder.Services.AddLocalization();

Impostare le impostazioni cultura predefinite e supportate dell'app con RequestLocalizationOptions.

Prima della chiamata a app.MapRazorComponents nella pipeline di elaborazione della richiesta, inserire il codice seguente:

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

app.UseRequestLocalization(localizationOptions);

Per informazioni sull'ordinamento del middleware di localizzazione nella pipeline middleware, vedere ASP.NET Middleware core.

Nell'esempio seguente viene illustrato come impostare le impostazioni cultura correnti in un oggetto cookie che può essere letto dal middleware di localizzazione.

Per il App componente sono necessari gli spazi dei nomi seguenti:

• System.Globalization
• Microsoft.AspNetCore.Localization

Aggiungere quanto segue all'inizio del file del App componente (Components/App.razor):

@using System.Globalization
@using Microsoft.AspNetCore.Localization

Aggiungere il blocco seguente @code alla fine del file del App componente:

@code {
    [CascadingParameter]
    public HttpContext? HttpContext { get; set; }

    protected override void OnInitialized()
    {
        HttpContext?.Response.Cookies.Append(
            CookieRequestCultureProvider.DefaultCookieName,
            CookieRequestCultureProvider.MakeCookieValue(
                new RequestCulture(
                    CultureInfo.CurrentCulture,
                    CultureInfo.CurrentUICulture)));
    }
}

Per informazioni sull'ordinamento del middleware di localizzazione nella pipeline middleware, vedere ASP.NET Middleware core.

Se l'app non è configurata per elaborare le azioni del controller:

• Aggiungere servizi MVC chiamando AddControllers nella raccolta di servizi nel Program file:

  builder.Services.AddControllers();
  

• Aggiungere il routing dell'endpoint ProgramIEndpointRouteBuilder controller nel file chiamando MapControllers su (app):

  app.MapControllers();
  

Per fornire l'interfaccia utente per consentire a un utente di selezionare impostazioni cultura, usare un approccio basato sul reindirizzamento con una localizzazione cookie. L'app mantiene le impostazioni cultura selezionate dall'utente tramite un reindirizzamento a un controller. Il controller imposta le impostazioni cultura selezionate dell'utente in un cookie e reindirizza l'utente all'URI originale. Il processo è simile a quello che accade in un'app Web quando un utente tenta di accedere a una risorsa protetta, in cui l'utente viene reindirizzato a una pagina di accesso e quindi reindirizzato alla risorsa originale.

Controllers/CultureController.cs:

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

[Route("[controller]/[action]")]
public class CultureController : Controller
{
    public IActionResult Set(string culture, string redirectUri)
    {
        if (culture != null)
        {
            HttpContext.Response.Cookies.Append(
                CookieRequestCultureProvider.DefaultCookieName,
                CookieRequestCultureProvider.MakeCookieValue(
                    new RequestCulture(culture, culture)));
        }

        return LocalRedirect(redirectUri);
    }
}

Avviso

Usare il risultato dell'azione LocalRedirect per impedire attacchi di reindirizzamento aperti. Per altre informazioni, vedere Impedire attacchi di reindirizzamento aperti in ASP.NET Core.

Il componente seguente CultureSelector illustra come chiamare il Set metodo di CultureController con le nuove impostazioni cultura. Il componente viene inserito nella Shared cartella per l'uso in tutta l'app.

CultureSelector.razor:

@using System.Globalization
@inject NavigationManager Navigation

<p>
    <label>
        Select your locale:
        <select @bind="Culture">
            @foreach (var culture in supportedCultures)
            {
                <option value="@culture">@culture.DisplayName</option>
            }
        </select>
    </label>
</p>

@code
{
    private CultureInfo[] supportedCultures = new[]
    {
        new CultureInfo("en-US"),
        new CultureInfo("es-CL"),
    };

    protected override void OnInitialized()
    {
        Culture = CultureInfo.CurrentCulture;
    }

    private CultureInfo Culture
    {
        get => CultureInfo.CurrentCulture;
        set
        {
            if (CultureInfo.CurrentCulture != value)
            {
                var uri = new Uri(Navigation.Uri)
                    .GetComponents(UriComponents.PathAndQuery, UriFormat.Unescaped);
                var cultureEscaped = Uri.EscapeDataString(value.Name);
                var uriEscaped = Uri.EscapeDataString(uri);

                Navigation.NavigateTo(
                    $"Culture/Set?culture={cultureEscaped}&redirectUri={uriEscaped}",
                    forceLoad: true);
            }
        }
    }
}

Aggiungere il CultureSelector componente al MainLayout componente. Inserire il markup seguente all'interno del tag di chiusura </main> nel Components/Layout/MainLayout.razor file:

Aggiungere il CultureSelector componente al MainLayout componente. Inserire il markup seguente all'interno del tag di chiusura </main> nel Shared/MainLayout.razor file:

<article class="bottom-row px-4">
    <CultureSelector />
</article>

Usare il CultureExample1 componente illustrato nella sezione Componente dimostrativo per studiare il funzionamento dell'esempio precedente.

L'esempio precedente presuppone che l'app adotti l'interattività globale specificando la modalità di rendering di Interactive Server nel AppRoutes componente (Components/App.razor):

<Routes @rendermode="InteractiveServer" />

Se l'app adotta l'interattività per pagina/componente , apportare le modifiche seguenti:

• Aggiungere la modalità di rendering Interactive Server all'inizio del CultureExample1 file del componente (Components/Pages/CultureExample1.razor):

  @rendermode InteractiveServer
  

• Nel layout principale dell'app (Components/Layout/MainLayout.razor) applicare la modalità di rendering Interactive Server al CultureSelector componente:

  <CultureSelector @rendermode="InteractiveServer" />
  

Localizzazione

Se l'app non supporta già la selezione delle impostazioni cultura dinamiche, aggiungere il Microsoft.Extensions.Localization pacchetto all'app.

Nota

Per indicazioni sull'aggiunta di pacchetti alle app .NET, vedere gli articoli sotto Installare e gestire pacchetti in Flusso di lavoro dell'utilizzo di pacchetti (documentazione di NuGet). Confermare le versioni corrette del pacchetto all'indirizzo NuGet.org.

Localizzazione lato client

Impostare la BlazorWebAssemblyLoadAllGlobalizationData proprietà su true nel file di progetto dell'app (.csproj):

<PropertyGroup>
  <BlazorWebAssemblyLoadAllGlobalizationData>true</BlazorWebAssemblyLoadAllGlobalizationData>
</PropertyGroup>

Program Nel file aggiungere lo spazio dei nomi per System.Globalization all'inizio del file:

using System.Globalization;

Aggiungere Blazoril servizio di localizzazione alla raccolta di servizi dell'app con AddLocalization:

builder.Services.AddLocalization();

Localizzazione lato server

Usa il middleware di localizzazione per impostare le impostazioni cultura dell'app.

Se l'app non supporta già la selezione dinamica delle impostazioni cultura:

• Aggiungere servizi di localizzazione all'app con AddLocalization.
• Specificare le impostazioni cultura predefinite e supportate dell'app nel Program file. Nell'esempio seguente vengono configurate le impostazioni cultura supportate per Stati Uniti spagnolo inglese e cileno.

builder.Services.AddLocalization();

Subito dopo l'aggiunta del middleware di routing alla pipeline di elaborazione:

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

app.UseRequestLocalization(localizationOptions);

Per informazioni sull'ordinamento del middleware di localizzazione nella pipeline middleware, vedere ASP.NET Middleware core.

Se l'app deve localizzare le risorse in base all'archiviazione dell'impostazione delle impostazioni cultura di un utente, usare le impostazioni cultura cookiedi localizzazione. L'uso di garantisce cookie che la connessione WebSocket possa propagare correttamente le impostazioni cultura. Se gli schemi di localizzazione sono basati sul percorso URL o sulla stringa di query, lo schema potrebbe non essere in grado di usare WebSocket, pertanto non riuscirà a rendere persistenti le impostazioni cultura. Pertanto, l'approccio consigliato consiste nell'usare impostazioni cultura cookiedi localizzazione. Vedere la sezione Impostazione dinamica delle impostazioni cultura lato server in base alle preferenze utente di questo articolo per visualizzare un'espressione di esempio Razor che rende persistente la selezione delle impostazioni cultura dell'utente.

Esempio di risorse localizzate

L'esempio di risorse localizzate in questa sezione funziona con gli esempi precedenti in questo articolo in cui le impostazioni cultura supportate dell'app sono inglese (en) come impostazioni locali predefinite e spagnolo (es) come impostazioni locali alternative selezionabili dall'utente o specificate dal browser.

Creare risorse per ogni impostazione locale. Nell'esempio seguente vengono create risorse per una stringa predefinita Greeting :

• Inglese: Hello, World!
• Spagnolo (es): ¡Hola, Mundo!

Nota

È possibile aggiungere il file di risorse seguente in Visual Studio facendo clic con il pulsante destro del mouse e scegliendo Aggiungi>nuovo file di risorse elemento.> Denominare il file CultureExample2.resx. Quando viene visualizzato l'editor, specificare i dati per una nuova voce. Impostare Name su Greeting e Value su Hello, World!. Salva il file.

CultureExample2.resx:

<?xml version="1.0" encoding="utf-8"?>
<root>
  <xsd:schema id="root" xmlns="" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:msdata="urn:schemas-microsoft-com:xml-msdata">
    <xsd:import namespace="http://www.w3.org/XML/1998/namespace" />
    <xsd:element name="root" msdata:IsDataSet="true">
      <xsd:complexType>
        <xsd:choice maxOccurs="unbounded">
          <xsd:element name="metadata">
            <xsd:complexType>
              <xsd:sequence>
                <xsd:element name="value" type="xsd:string" minOccurs="0" />
              </xsd:sequence>
              <xsd:attribute name="name" use="required" type="xsd:string" />
              <xsd:attribute name="type" type="xsd:string" />
              <xsd:attribute name="mimetype" type="xsd:string" />
              <xsd:attribute ref="xml:space" />
            </xsd:complexType>
          </xsd:element>
          <xsd:element name="assembly">
            <xsd:complexType>
              <xsd:attribute name="alias" type="xsd:string" />
              <xsd:attribute name="name" type="xsd:string" />
            </xsd:complexType>
          </xsd:element>
          <xsd:element name="data">
            <xsd:complexType>
              <xsd:sequence>
                <xsd:element name="value" type="xsd:string" minOccurs="0" msdata:Ordinal="1" />
                <xsd:element name="comment" type="xsd:string" minOccurs="0" msdata:Ordinal="2" />
              </xsd:sequence>
              <xsd:attribute name="name" type="xsd:string" use="required" msdata:Ordinal="1" />
              <xsd:attribute name="type" type="xsd:string" msdata:Ordinal="3" />
              <xsd:attribute name="mimetype" type="xsd:string" msdata:Ordinal="4" />
              <xsd:attribute ref="xml:space" />
            </xsd:complexType>
          </xsd:element>
          <xsd:element name="resheader">
            <xsd:complexType>
              <xsd:sequence>
                <xsd:element name="value" type="xsd:string" minOccurs="0" msdata:Ordinal="1" />
              </xsd:sequence>
              <xsd:attribute name="name" type="xsd:string" use="required" />
            </xsd:complexType>
          </xsd:element>
        </xsd:choice>
      </xsd:complexType>
    </xsd:element>
  </xsd:schema>
  <resheader name="resmimetype">
    <value>text/microsoft-resx</value>
  </resheader>
  <resheader name="version">
    <value>2.0</value>
  </resheader>
  <resheader name="reader">
    <value>System.Resources.ResXResourceReader, System.Windows.Forms, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089</value>
  </resheader>
  <resheader name="writer">
    <value>System.Resources.ResXResourceWriter, System.Windows.Forms, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089</value>
  </resheader>
  <data name="Greeting" xml:space="preserve">
    <value>Hello, World!</value>
  </data>
</root>

Nota

È possibile aggiungere il file di risorse seguente in Visual Studio facendo clic con il pulsante destro del mouse e scegliendo Aggiungi>nuovo file di risorse elemento.> Denominare il file CultureExample2.es.resx. Quando viene visualizzato l'editor, specificare i dati per una nuova voce. Impostare Name su Greeting e Value su ¡Hola, Mundo!. Salva il file.

CultureExample2.es.resx:

<?xml version="1.0" encoding="utf-8"?>
<root>
  <xsd:schema id="root" xmlns="" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:msdata="urn:schemas-microsoft-com:xml-msdata">
    <xsd:import namespace="http://www.w3.org/XML/1998/namespace" />
    <xsd:element name="root" msdata:IsDataSet="true">
      <xsd:complexType>
        <xsd:choice maxOccurs="unbounded">
          <xsd:element name="metadata">
            <xsd:complexType>
              <xsd:sequence>
                <xsd:element name="value" type="xsd:string" minOccurs="0" />
              </xsd:sequence>
              <xsd:attribute name="name" use="required" type="xsd:string" />
              <xsd:attribute name="type" type="xsd:string" />
              <xsd:attribute name="mimetype" type="xsd:string" />
              <xsd:attribute ref="xml:space" />
            </xsd:complexType>
          </xsd:element>
          <xsd:element name="assembly">
            <xsd:complexType>
              <xsd:attribute name="alias" type="xsd:string" />
              <xsd:attribute name="name" type="xsd:string" />
            </xsd:complexType>
          </xsd:element>
          <xsd:element name="data">
            <xsd:complexType>
              <xsd:sequence>
                <xsd:element name="value" type="xsd:string" minOccurs="0" msdata:Ordinal="1" />
                <xsd:element name="comment" type="xsd:string" minOccurs="0" msdata:Ordinal="2" />
              </xsd:sequence>
              <xsd:attribute name="name" type="xsd:string" use="required" msdata:Ordinal="1" />
              <xsd:attribute name="type" type="xsd:string" msdata:Ordinal="3" />
              <xsd:attribute name="mimetype" type="xsd:string" msdata:Ordinal="4" />
              <xsd:attribute ref="xml:space" />
            </xsd:complexType>
          </xsd:element>
          <xsd:element name="resheader">
            <xsd:complexType>
              <xsd:sequence>
                <xsd:element name="value" type="xsd:string" minOccurs="0" msdata:Ordinal="1" />
              </xsd:sequence>
              <xsd:attribute name="name" type="xsd:string" use="required" />
            </xsd:complexType>
          </xsd:element>
        </xsd:choice>
      </xsd:complexType>
    </xsd:element>
  </xsd:schema>
  <resheader name="resmimetype">
    <value>text/microsoft-resx</value>
  </resheader>
  <resheader name="version">
    <value>2.0</value>
  </resheader>
  <resheader name="reader">
    <value>System.Resources.ResXResourceReader, System.Windows.Forms, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089</value>
  </resheader>
  <resheader name="writer">
    <value>System.Resources.ResXResourceWriter, System.Windows.Forms, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089</value>
  </resheader>
  <data name="Greeting" xml:space="preserve">
    <value>¡Hola, Mundo!</value>
  </data>
</root>

Il componente seguente illustra l'uso della stringa localizzata Greeting con IStringLocalizer<T>. Il Razor markup @Loc["Greeting"] nell'esempio seguente localizza la stringa con chiave sul Greeting valore impostato nei file di risorse precedenti.

Aggiungere lo spazio dei nomi per Microsoft.Extensions.Localization al file dell'app _Imports.razor :

@using Microsoft.Extensions.Localization

CultureExample2.razor:

@page "/culture-example-2"
@using System.Globalization
@inject IStringLocalizer<CultureExample2> Loc

<h1>Culture Example 2</h1>

<p>
    <b>CurrentCulture</b>: @CultureInfo.CurrentCulture
</p>

<h2>Greeting</h2>

<p>
    @Loc["Greeting"]
</p>

<p>
    @greeting
</p>

@code {
    private string? greeting;

    protected override void OnInitialized()
    {
        greeting = Loc["Greeting"];
    }
}

Facoltativamente, aggiungere una voce di menu per il CultureExample2 componente al riquadro di spostamento nel NavMenu componente (NavMenu.razor).

Origine di riferimento del provider delle impostazioni cultura WebAssembly

Per comprendere meglio come il framework elabora la Blazor localizzazione, vedere la WebAssemblyCultureProvider classe nell'origine di riferimento ASP.NET Core.

Nota

I collegamenti della documentazione all'origine del riferimento .NET in genere caricano il ramo predefinito del repository, che rappresenta lo sviluppo corrente per la versione successiva di .NET. Per selezionare un tag per una versione specifica, usare l'elenco a discesa Switch branches or tags. Per altre informazioni, vedere How to select a version tag of ASP.NET Core source code (dotnet/AspNetCore.Docs #26205) (Come selezionare un tag di versione del codice sorgente di ASP.NET - dotnet/AspNetCore.Docs #26205).

Risorse condivise

Per creare risorse condivise di localizzazione, adottare l'approccio seguente.

• Creare una classe fittizia con un nome di classe arbitrario. Nell'esempio seguente:

  • L'app usa lo spazio dei BlazorSample nomi e gli asset di localizzazione usano lo spazio dei BlazorSample.Localization nomi .
  • La classe fittizia è denominata SharedResource.
  • Il file di classe viene inserito in una Localization cartella nella radice dell'app.

  Localization/SharedResource.cs:

  namespace BlazorSample.Localization;
  
  public class SharedResource
  {
  }
  

• Creare i file di risorse condivise con un'azione di compilazione di Embedded resource. Nell'esempio seguente:

  • I file vengono inseriti nella Localization cartella con la classe fittizia SharedResource (Localization/SharedResource.cs).

  • Denominare i file di risorse in modo che corrispondano al nome della classe fittizia. I file di esempio seguenti includono un file di localizzazione predefinito e un file per la localizzazione spagnola (es).

  • Localization/SharedResource.resx

  • Localization/SharedResource.es.resx

  Nota

  Localization è il percorso della risorsa che può essere impostato tramite LocalizationOptions.

• Per fare riferimento alla classe fittizia per un componente inserito IStringLocalizer<T> in un Razor componente, inserire una @using direttiva per lo spazio dei nomi di localizzazione o includere lo spazio dei nomi di localizzazione nel riferimento fittizio della classe. Negli esempi seguenti:

  • Il primo esempio indica lo Localization spazio dei nomi per la SharedResource classe fittizia con una @using direttiva .
  • Il secondo esempio indica in modo esplicito lo SharedResource spazio dei nomi della classe fittizia.

  In un Razor componente usare uno degli approcci seguenti:

  @using Localization
  @inject IStringLocalizer<SharedResource> Loc
  

  @inject IStringLocalizer<Localization.SharedResource> Loc
  

Per altre indicazioni, vedere Globalizzazione e localizzazione in ASP.NET Core.

Risorse aggiuntive

• Impostare il percorso di base dell'app
• Globalizzazione e localizzazione in ASP.NET Core
• Globalizzazione e localizzazione di applicazioni .NET
• Uso dei file RESX a livello di codice
• Microsoft Multilingual App Toolkit
• Generics di localizzazione &
• La chiamata InvokeAsync(StateHasChanged) causa il fallback delle impostazioni cultura predefinite della pagina (dotnet/aspnetcore #28521)