ASP.NET Core Blazor globalizzazione e localizzazione

Nota

Questa non è la versione più recente di questo articolo. Per la versione corrente, vedere la versione .NET 11 di questo articolo.

Avviso

Questa versione di ASP.NET Core non è più supportata. Per altre informazioni, vedere .NET e .NET Core Support Policy. Per la versione corrente, vedere la versione .NET 10 di questo articolo.

Questo articolo illustra come presentare il contenuto globalizzato e localizzato agli utenti in lingue e culture diverse.

Globalizzazione e localizzazione

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

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

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

Non supportato:IHtmlLocalizer e IViewLocalizer sono funzionalità MVC di ASP.NET Core e non supportate nelle Blazor app.

Per Blazor le app, la localizzazione dei messaggi di convalida per la convalida dei moduli tramite annotazioni di dati è supportata se DisplayAttribute.ResourceType e ValidationAttribute.ErrorMessageResourceType vengono implementati.

Per Blazor le app, i messaggi di convalida localizzati per la convalida dei moduli tramite annotazioni dei dati sono supportati tramite due percorsi:

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.
  • Una cultura definita dall'applicazione non basata sul 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:

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.

La cultura riguarda 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.

Le indicazioni contenute in questo articolo non illustrano l'impostazione dell'attributo del linguaggio HTML (<html lang="...">) della pagina, usato dagli strumenti di accessibilità. È possibile impostare il valore in modo statico assegnando un linguaggio all'attributo lang del <html> tag o a document.documentElement.lang in JavaScript. È possibile impostare dinamicamente il valore di document.documentElement.lang con JS interop.

Nota

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

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 alla cultura corrente dalla proprietà System.Globalization.CultureInfo.CurrentCulture.

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.

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

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

  • datetime-local
  • month
  • week

Per il supporto corrente del browser dei tipi precedenti, vedere Can I use.

Per impostazione predefinita, Blazor carica un sottoinsieme dei dati di globalizzazione che contiene la cultura dell'app. Per caricare tutti i dati di globalizzazione, impostare <BlazorWebAssemblyLoadAllGlobalizationData> su true nel file di progetto dell'app (.csproj):

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

Supporto .NET globalization e International Components for Unicode (ICU) (Blazor WebAssembly)

Blazor WebAssembly usa un'API di globalizzazione ridotta e un set di impostazioni locali predefinite international components for Unicode (ICU).

Nelle app WebAssembly (Wasm) quando la modalità invariante della globalizzazione è disabilitata, viene caricato un file di dati ICU. Esistono quattro tipi di base di questi file:

  • icudt.dat: dati completi
  • icudt_EFIGS.dat: dati per locali: en-*, es-ES, fr-FR, it-IT, e de-DE.
  • icudt_CJK.dat: dati per le impostazioni locali: en-*, ko, ja, e zh-*.
  • icudt_no_CJK.dat: dati per tutte le impostazioni locali da icudt.dat, escluso ja, koe zh-*.

Specificare un file da caricare con la <BlazorIcuDataFileName> proprietà MSBuild nel file di progetto dell'app (.csproj). L'esempio seguente carica il icudt_no_CJK.dat file:

<PropertyGroup>
  <BlazorIcuDataFileName>icudt_no_CJK.dat</BlazorIcuDataFileName>
</PropertyGroup>

<BlazorIcuDataFileName> accetta solo un singolo file. Il file può essere un file personalizzato creato dallo sviluppatore. Per creare un file di ICU personalizzato, vedere Icu di globalizzazione WASM: ICU personalizzato.

Se un file non è specificato con <BlazorIcuDataFileName>, la cultura dell'app viene controllata e il file ICU corrispondente viene caricato per la sua cultura. Ad esempio, la en-US cultura comporta il caricamento del icudt_EFIGS.dat file. Per zh-CN, viene usato il icudt_CJK.dat file .

Per altre informazioni, vedere .NET globalization and ICU: ICU on WebAssembly.

Blazor WebAssembly usa un'API di globalizzazione ridotta e un set di impostazioni locali predefinite di International Components for Unicode (ICU). Per altre informazioni, vedere .NET globalization and ICU: ICU on WebAssembly.

Il caricamento di un subset personalizzato di impostazioni locali in un'app Blazor WebAssembly è supportato in .NET 8 o versione successiva. Per altre informazioni, accedere a questa sezione per una versione .NET 8 o successiva di questo articolo.

Globalizzazione invariante

Questa sezione si applica solo agli scenari lato Blazor client.

Se l'app non richiede la localizzazione, configurare l'app per supportare la cultura invariante, che è generalmente basata sull'inglese degli Stati Uniti (en-US). L'uso della globalizzazione invariante riduce le dimensioni di download dell'app e comporta un avvio più rapido dell'app. 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 ulteriori informazioni, vedere le opzioni di configurazione Runtime per la globalizzazione (documentazione .NET).

Informazioni sul fuso orario

Questa sezione si applica solo agli scenari lato Blazor client.

L'adozione della globalizzazione invariante comporta solo l'uso di nomi di fuso orario non localizzati. Per ridurre il codice e i dati del fuso orario, riducendo le dimensioni di download dell'app e comportando un avvio più rapido dell'app, applicare la <InvariantTimezone> proprietà MSBuild con un valore di true nel file di progetto dell'app:

<PropertyGroup>
  <InvariantTimezone>true</InvariantTimezone>
</PropertyGroup>

Nota

<BlazorEnableTimeZoneSupport> sovrascrive un'impostazione <InvariantTimezone> precedente. È consigliabile rimuovere l'impostazione <BlazorEnableTimeZoneSupport> .

È incluso un file di dati per correggere le informazioni sul fuso orario. Se l'app non richiede questa funzionalità, è consigliabile disabilitarla impostando la <BlazorEnableTimeZoneSupport> proprietà MSBuild su false nel file di progetto dell'app:

<PropertyGroup>
  <BlazorEnableTimeZoneSupport>false</BlazorEnableTimeZoneSupport>
</PropertyGroup>

Il prerendering sul lato client in un Blazor Web App preserva le impostazioni cultura del server

Per impostazione predefinita, il prerendering lato client sul server (.Client progetto in un Blazor Web App) mantiene i valori del server CurrentCulture e CurrentUICulture nello stato del componente e li applica sul client prima del caricamento degli assembly satellite.

Le applicazioni che richiedono al client di scegliere le impostazioni cultura indipendentemente dal server possono disattivarlo con WebAssemblyComponentsOptions.UseCultureFromServer nel file Blazor Web App di Program:

builder.Services.AddRazorComponents()
    .AddInteractiveWebAssemblyComponents(options =>
    {
        options.UseCultureFromServer = false;
    });

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>

<ul>
    <li><b>CurrentCulture</b>: @CultureInfo.CurrentCulture</li>
    <li><b>CurrentUICulture</b>: @CultureInfo.CurrentUICulture</li>
</ul>

<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 (N2) nell'esempio precedente (.ToString("N2")) è un specificatore di formato numerico standard .NET. Il N2 formato è supportato per tutti i tipi numerici, include un separatore di gruppo ed esegue il rendering fino a due posizioni decimali.

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

Impostare dinamicamente la cultura dall'intestazione Accept-Language

Questa sezione si applica alle app lato server e alle app lato client Blazor.

Aggiungere il pacchetto Microsoft.Extensions.Localization 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 l'inglese statunitense, inglese e spagnolo costaricano con una preferenza per l'inglese statunitense o inglese.

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

La cultura dell'app è impostata dalla prima lingua richiesta che corrisponde a una cultura supportata dall'app.

Nello sviluppo client-side, impostare la proprietà su nel file di progetto dell'app client-side (BlazorWebAssemblyLoadAllGlobalizationData):

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

Nello sviluppo lato client, l'impostazione dinamica della lingua dall'intestazione Accept-Language non è supportata.

Nota

Se la specifica dell'app necessita di limitare le culture supportate a un elenco esplicito, vedere la sezione Impostazione dinamica della cultura lato client in base alle preferenze dell'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 sul lato server, specificare le culture supportate dall'app prima di qualsiasi middleware che possa controllare la cultura della richiesta. In genere, collocare il middleware di localizzazione immediatamente prima di chiamare MapRazorComponents. L'esempio seguente configura le culture supportate per inglese degli Stati Uniti e spagnolo di Costa Rica.

Nello sviluppo lato server, specifica le impostazioni cultura supportate dall'app immediatamente dopo l'aggiunta del middleware di routing (UseRouting) alla pipeline di elaborazione. L'esempio seguente configura le culture supportate per l'inglese degli Stati Uniti e lo spagnolo costaricano usando l'API seguente.

  • AddSupportedCultures aggiunge il set di impostazioni cultura supportate per la globalizzazione (data, numero e formattazione valuta).
  • AddSupportedUICultures aggiunge il set delle impostazioni cultura dell'interfaccia utente supportate per la localizzazione (stringhe dell'interfaccia utente tradotte per il rendering del contenuto).
app.UseRequestLocalization(new RequestLocalizationOptions()
    .AddSupportedCultures(new[] { "en-US", "es-CR" })
    .AddSupportedUICultures(new[] { "en-US", "es-CR" }));

Nell'esempio precedente, gli stessi formati culturali supportati e le impostazioni della cultura dell'interfaccia utente vengono specificati in un caso specifico in cui l'app viene usata solo negli Stati Uniti e in Costa Rica. In alternativa, un'app può usare un set più ampio di impostazioni culturali per la formattazione di data, numero e valuta, ma fornire solo contenuto localizzato per gli Stati Uniti e la Costa Rica, come illustrato nell'esempio seguente.

var uiCultures = new[] { "en-US", "es-CR" };

var formattingCultures = CultureInfo
    .GetCultures(CultureTypes.SpecificCultures)
    .Select(c => c.Name)
    .ToArray();

var localizationOptions = new RequestLocalizationOptions()
    .SetDefaultCulture(uiCultures[0])
    .AddSupportedCultures(formattingCultures)
    .AddSupportedUICultures(uiCultures);

app.UseRequestLocalization(localizationOptions);

Nell'esempio precedente, CultureTypes.SpecificCultures restituisce solo le culture specifiche di un paese o di una regione—come en-US o fr-FR—che dispongono di dati di globalizzazione completi e concreti (incluse date, numeri, calendari e altre interfacce utente culturali) che .NET può utilizzare per una formattazione e un'analisi accurate. Le culture neutre, ad esempio en o fr, potrebbero non avere dati di globalizzazione completi, quindi non sono incluse in questo elenco.

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

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

Quando le impostazioni cultura sono inglese degli Stati Uniti (en-US), il componente sottoposto a rendering usa la formattazione della data mese/giorno (6/7), il formato orario a 12 ore (AM/PM) e i separatori delle migliaia con la virgola nei numeri, con il punto come separatore decimale (1,999.69):

  • Data: 7/6/2021 6:45:22
  • Numero: 1.999,69

Quando le impostazioni cultura sono spagnolo costa ricano (es-CR), 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: 7/6/2021 6:49:38
  • Numero: 1.999,69

Impostare in modo statico le impostazioni cultura lato client

Questa sezione si applica alle Blazor Web App app e ai Blazor WebAssembly componenti che adottano la modalità di rendering Interactive WebAssembly.

Questa sezione si applica alle Blazor WebAssembly app.

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

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

La configurazione del linker del linguaggio intermedio (IL) per il rendering lato client rimuove le informazioni di internazionalizzazione, ad eccezione dei locali richiesti in modo esplicito. Per altre informazioni, vedere Configurare il linker per ASP.NET Core Blazor.

La cultura dell'app può essere configurata in JavaScript quando Blazor inizia con l'opzione di avvio applicationCultureBlazor. L'esempio seguente configura l'app per l'avvio usando la cultura inglese degli Stati Uniti (en-US).

Impedire l'avvio Blazor automatico aggiungendo autostart="false" al Blazor<script> tag :

<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 il percorso dello script, vedere ASP.NET Core Blazor struttura del progetto.

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

Blazor Web App:

<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 ASP.NET Core Blazor startup.

Un'alternativa all'impostazione dell'opzione d'avvio della cultura Blazor consiste nell'impostare la cultura nel codice C#. Impostare CultureInfo.DefaultThreadCurrentCulture e CultureInfo.DefaultThreadCurrentUICulture nel file Program alla stessa cultura.

Aggiungere il System.Globalization namespace al Program file:

using System.Globalization;

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

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

Nota

In .NET 9 o versioni precedenti, le app autonome Blazor WebAssembly caricano le risorse di globalizzazione dell'interfaccia utente in base a CultureInfo.DefaultThreadCurrentCulture. Se desideri caricare anche i dati di globalizzazione per la cultura di localizzazione definita da CultureInfo.DefaultThreadCurrentUICulture, aggiorna l'app a .NET 10 o versione successiva.

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

Impostare in modo statico la cultura lato server

Questa sezione si applica ai Blazor Web App componenti che adottano la modalità di rendering Interactive Server e alle app Blazor Server.

Questa sezione si applica alle Blazor Server app.

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

Nel file Program:

builder.Services.AddLocalization();

Specificare la cultura statica nel Program file prima di qualsiasi middleware che potrebbe controllare la cultura della richiesta. In genere, posizionare il middleware di localizzazione immediatamente prima di MapRazorComponents. L'esempio seguente configura l'inglese degli Stati Uniti.

Specificare le impostazioni cultura statiche nel file Program immediatamente dopo aver aggiunto il middleware di routing (UseRouting) alla pipeline di elaborazione. L'esempio seguente configura l'inglese degli Stati Uniti.

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 Core middleware.

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

In Startup.ConfigureServices (Startup.cs):

services.AddLocalization();

Specificare la cultura statica in Startup.Configure (Startup.cs) immediatamente dopo che il middleware di routing viene aggiunto alla pipeline di elaborazione. L'esempio seguente configura l'inglese degli Stati Uniti.

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 di Startup.Configure, vedere ASP.NET Core middleware.

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

Impostare dinamicamente la cultura lato client in base alle preferenze dell'utente

Questa sezione si applica alle app Blazor Web App e ai componenti Blazor WebAssembly che adottano la modalità di rendering Interactive WebAssembly.

Questa sezione si applica alle Blazor WebAssembly app.

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 pacchetto Microsoft.Extensions.Localization all'app.

Nota

Per indicazioni sull'aggiunta di pacchetti alle app .NET, vedere gli articoli in Installare e gestire pacchetti all'indirizzo Package consumption workflow (documentazione 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 delle culture 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 dopo il Blazor<script> tag 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 funzioni 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 file Program:

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 il servizio di localizzazione di Blazor alla raccolta di servizi dell'app tramite AddLocalization e utilizza l'interoperabilità di JS per effettuare chiamate a JS e recuperare la selezione dell'impostazione culturale dell'utente dalla memoria locale. Se l'archiviazione locale non contiene impostazioni cultura per l'utente, il codice imposta un valore predefinito inglese degli Stati Uniti (en-US).

builder.Services.AddLocalization();

var host = builder.Build();

const string defaultCulture = "en-US";

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

if (result == null)
{
    await js.InvokeVoidAsync("blazorCulture.set", defaultCulture);
}

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

await host.RunAsync();

Nota

In .NET 9 o versioni precedenti, le app autonome Blazor WebAssembly caricano le risorse di globalizzazione dell'interfaccia utente in base a CultureInfo.DefaultThreadCurrentCulture. Se desideri caricare anche i dati di globalizzazione per la cultura di localizzazione definita da CultureInfo.DefaultThreadCurrentUICulture, aggiorna l'app a .NET 10 o versione successiva.

Il componente seguente CultureSelector illustra come eseguire le azioni seguenti:

  • Impostare la selezione della cultura utente nell'archiviazione locale del browser tramite JS interop.
  • Ricarica il componente richiesto (forceLoad: true), che utilizza la cultura aggiornata.

CultureSelector.razor:

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

<p>
    <label>
        Select your locale:
        <select @bind="selectedCulture" @bind:after="ApplySelectedCultureAsync">
            @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-CR"),
    };

    private CultureInfo? selectedCulture;

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

    private async Task ApplySelectedCultureAsync()
    {
        if (selectedCulture is not null &&
            CultureInfo.CurrentCulture != selectedCulture)
        {
            await JS.InvokeVoidAsync("blazorCulture.set", selectedCulture.Name);

            Navigation.NavigateTo(Navigation.Uri, forceLoad: true);
        }
    }
}
@using System.Globalization
@inject IJSRuntime JS
@inject NavigationManager Navigation

<p>
    <label>
        Select your locale:
        <select value="@selectedCulture" @onchange="HandleSelectedCultureChanged">
            @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-CR"),
    };

    private CultureInfo? selectedCulture;

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

    private async Task HandleSelectedCultureChanged(ChangeEventArgs args)
    {
        selectedCulture = CultureInfo.GetCultureInfo((string)args.Value!);

        if (selectedCulture is not null &&
            CultureInfo.CurrentCulture != selectedCulture)
        {
            await JS.InvokeVoidAsync("blazorCulture.set", selectedCulture.Name);

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

Nel markup dell'header del componente MainLayout (MainLayout.razor), aggiungi il componente CultureSelector:

<CultureSelector />

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

Impostare dinamicamente la cultura lato server in base alle preferenze dell'utente

Questa sezione si applica a Blazor Web App che adottano la modalità di rendering Interactive Server globale e alle app Blazor Server. Per indicazioni su un Blazor Web App che adotta l'interattività per pagina/componente, vedere la sezione Impostare dinamicamente le impostazioni cultura in un Blazor Web App in base alle preferenze dell'utente.

Questa sezione si applica alle Blazor Server app.

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.

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

Nota

Per indicazioni sull'aggiunta di pacchetti alle app .NET, vedere gli articoli in Installare e gestire pacchetti all'indirizzo Package consumption workflow (documentazione nuGet). Confermare le versioni corrette del pacchetto all'indirizzo NuGet.org.

Le app 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 culture predefinite e supportate dell'app con RequestLocalizationOptions.

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

Dopo l'aggiunta del middleware di routing (UseRouting) alla pipeline di elaborazione delle richieste, inserire il codice seguente:

var supportedCultures = new[] { "en-US", "es-CR" };
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 Core middleware.

L'esempio seguente mostra come impostare la cultura corrente in un cookie che può essere letto dal middleware di localizzazione.

Per il componente App sono richiesti i seguenti namespaces:

Aggiungere i namespace System.Globalization e Microsoft.AspNetCore.Localization all'inizio del file del componente App (Components/App.razor):

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

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

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

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

Le modifiche apportate al Pages/_Host.cshtml file richiedono i namespace seguenti:

Aggiungere il markup seguente Razor al file:

@using System.Globalization
@using Microsoft.AspNetCore.Localization
@{
    this.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 Core middleware.

Per fornire un'interfaccia utente che consenta a un utente di selezionare una cultura, usare un approccio basato sul reindirizzamento con localizzazione . L'app mantiene le impostazioni cultura selezionate dall'utente tramite un reindirizzamento a un endpoint API minimo. L'endpoint imposta la cultura selezionata dall'utente in un cookie e reindirizza l'utente all'URI di origine. 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.

All'inizio del file Program, aggiungere la seguente istruzione using per lo spazio dei nomi richiesto:

using Microsoft.AspNetCore.Localization;

Nella pipeline di elaborazione delle richieste del file Program dell'app dopo la chiamata a UseRequestLocalization:

app.MapGet("/Culture/Set", (string? culture, string redirectUri = "/",
    HttpContext context) =>
{
    if (!string.IsNullOrWhiteSpace(culture))
    {
        context.Response.Cookies.Append(
            CookieRequestCultureProvider.DefaultCookieName,
            CookieRequestCultureProvider.MakeCookieValue(
                new RequestCulture(culture, culture)));
    }

    return Results.LocalRedirect(redirectUri);
});

Avviso

Usare il LocalRedirect risultato, come illustrato nell'esempio precedente, per impedire attacchi di reindirizzamento aperti. Per altre informazioni, vedere Prevent open redirect attacks in ASP.NET 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();
    
  • Aggiungi il routing dell'endpoint del controller nel file Program chiamando MapControllers su IEndpointRouteBuilder (app):

    app.MapControllers();
    

Per fornire un'interfaccia utente che consenta a un utente di selezionare una cultura, usare un approccio basato sul reindirizzamento con localizzazione . L'app conserva le impostazioni culturali selezionate dall'utente tramite un reindirizzamento a un controller. Il controller imposta la cultura selezionata dall'utente nella 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 , come illustrato nell'esempio precedente, per impedire attacchi di reindirizzamento aperti. Per altre informazioni, vedere Prevent open redirect attacks in ASP.NET Core.

Il componente seguente CultureSelector mostra come chiamare l'endpoint Set con la nuova impostazione cultura. Il componente viene inserito nella Components cartella per l'uso in tutta l'app.

Components/CultureSelector.razor:

Il componente seguente CultureSelector mostra come chiamare l'endpoint Set con la nuova impostazione cultura. Il componente viene inserito nella Shared cartella per l'uso in tutta l'app.

Shared/CultureSelector.razor:

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

<p>
    <label>
        Select your locale:
        <select @bind="selectedCulture" @bind:after="ApplySelectedCultureAsync">
            @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-CR"),
    };

    private CultureInfo? selectedCulture;

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

    private async Task ApplySelectedCultureAsync()
    {
        if (selectedCulture is not null &&
            CultureInfo.CurrentCulture != selectedCulture)
        {
            var uri = new Uri(Navigation.Uri)
                .GetComponents(UriComponents.PathAndQuery, UriFormat.Unescaped);
            var cultureEscaped = Uri.EscapeDataString(selectedCulture.Name);
            var uriEscaped = Uri.EscapeDataString(uri);

            Navigation.NavigateTo(
                $"Culture/Set?culture={cultureEscaped}&redirectUri={uriEscaped}",
                forceLoad: true);
        }
    }
}
@using System.Globalization
@inject IJSRuntime JS
@inject NavigationManager Navigation

<p>
    <label>
        Select your locale:
        <select value="@selectedCulture" @onchange="HandleSelectedCultureChanged">
            @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-CR"),
    };

    private CultureInfo? selectedCulture;

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

    private async Task HandleSelectedCultureChanged(ChangeEventArgs args)
    {
        selectedCulture = CultureInfo.GetCultureInfo((string)args.Value!);

        if (selectedCulture is not null &&
            CultureInfo.CurrentCulture != selectedCulture)
        {
            var uri = new Uri(Navigation.Uri)
                .GetComponents(UriComponents.PathAndQuery, UriFormat.Unescaped);
            var cultureEscaped = Uri.EscapeDataString(selectedCulture.Name);
            var uriEscaped = Uri.EscapeDataString(uri);

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

Aggiungere il componente CultureSelector al componente MainLayout.

Nel markup dell'header di Components/Layout/MainLayout.razor:

Nel markup dell'header di Shared/MainLayout.razor:

<CultureSelector />

Usare il CultureExample1 componente mostrato 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 del server interattivo sul componente nel componente (Routes).

<Routes @rendermode="InteractiveServer" />

Se l'app adotta l'interattività per pagina/per componente e solo i componenti sul lato server forniscono l'interfaccia utente per la selezione delle impostazioni cultura, apporta le modifiche seguenti:

  • Aggiungere la modalità di rendering del Server Interattivo all'inizio del file del componente CultureExample1 (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" />
    

Impostare dinamicamente la cultura in un Blazor Web App in base alle preferenze dell'utente

Questa sezione si applica a Blazor Web Apps che adottano interattività per pagina/componente.

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 gli scenari lato server), sia nell'archiviazione locale che in una localizzazione cookie (Blazor Web Apps con componenti server e WebAssembly) 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 per i componenti di cui è stato eseguito il rendering sul lato client e una localizzazione cookie per i componenti di cui è stato eseguito il rendering sul lato server (SSR). Le indicazioni contenute in questa sezione funzionano anche per i componenti nelle app che adottano il rendering per pagina/componente e specificano la modalità di rendering automatico interattivo (@rendermode InteractiveAuto).

Aggiornamenti al .Client progetto

Aggiungere il pacchetto Microsoft.Extensions.Localization al progetto .Client.

Nota

Per indicazioni sull'aggiunta di pacchetti alle app .NET, vedere gli articoli in Installare e gestire pacchetti all'indirizzo Package consumption workflow (documentazione nuGet). Confermare le versioni corrette del pacchetto all'indirizzo NuGet.org.

Impostare la proprietà BlazorWebAssemblyLoadAllGlobalizationData su true nel progetto .Client file.

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

Aggiungere i namespace per System.Globalization e Microsoft.JSInterop all'inizio del file del progetto .Client:

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 il servizio di localizzazione di Blazor alla raccolta di servizi dell'app tramite AddLocalization e utilizza l'interoperabilità di JS per effettuare chiamate a JS e recuperare la selezione dell'impostazione culturale dell'utente dalla memoria locale. Se l'archiviazione locale non contiene impostazioni cultura per l'utente, il codice imposta un valore predefinito inglese degli Stati Uniti (en-US).

builder.Services.AddLocalization();

var host = builder.Build();

const string defaultCulture = "en-US";

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

if (result == null)
{
    await js.InvokeVoidAsync("blazorCulture.set", defaultCulture);
}

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

await host.RunAsync();

Nota

In .NET 9 o versioni precedenti, le app autonome Blazor WebAssembly caricano le risorse di globalizzazione dell'interfaccia utente in base a CultureInfo.DefaultThreadCurrentCulture. Se desideri caricare anche i dati di globalizzazione per la cultura di localizzazione definita da CultureInfo.DefaultThreadCurrentUICulture, aggiorna l'app a .NET 10 o versione successiva.

Aggiungere il seguente componente CultureSelector nel progetto .Client in una cartella Shared. Se nel progetto Shared non esiste una cartella .Client, crearne una per contenere i componenti condivisi.

Quando l'utente cambia le impostazioni cultura, JS interop imposta la cultura nell'archiviazione locale del browser e un endpoint Minimal API aggiorna la localizzazione cookie con la cultura. L'endpoint API minimo viene aggiunto all'app più avanti nella sezione Aggiornamenti del progetto Server .

Shared/CultureSelector.razor:

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

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

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

    private CultureInfo? selectedCulture;

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

    private async Task ApplySelectedCultureAsync()
    {
        if (selectedCulture is not null &&
            CultureInfo.CurrentCulture != selectedCulture)
        {
            await JS.InvokeVoidAsync("blazorCulture.set", selectedCulture.Name);

            var uri = new Uri(Navigation.Uri)
                .GetComponents(UriComponents.PathAndQuery, UriFormat.Unescaped);
            var cultureEscaped = Uri.EscapeDataString(selectedCulture.Name);
            var uriEscaped = Uri.EscapeDataString(uri);

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

Nel file imports del progetto server (_Imports.razor), aggiungi lo spazio dei nomi per la cartella Shared del progetto .Client (aggiorna lo spazio dei nomi in modo che corrisponda alla tua app):

@using BlazorSample.Client.Shared

Inserire il markup seguente nel contenuto dell'intestazione del Components/Layout/MainLayout.razor file:

<CultureSelector @rendermode="InteractiveAuto" />

.Client Nel progetto posizionare il componente seguente CultureClient per studiare il funzionamento della globalizzazione per i componenti CSR.

Pages/CultureClient.razor:

@page "/culture-client"
@rendermode InteractiveWebAssembly
@using System.Globalization

<PageTitle>Culture Client</PageTitle>

<h1>Culture Client</h1>

<ul>
    <li><b>CurrentCulture</b>: @CultureInfo.CurrentCulture</li>
    <li><b>CurrentUICulture</b>: @CultureInfo.CurrentUICulture</li>
</ul>

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

Nel progetto .Client posizionare il componente CultureServer seguente per studiare il funzionamento della globalizzazione per i componenti SSR.

Pages/CultureServer.razor:

@page "/culture-server"
@rendermode InteractiveServer
@using System.Globalization

<PageTitle>Culture Server</PageTitle>

<h1>Culture Server</h1>

<ul>
    <li><b>CurrentCulture</b>: @CultureInfo.CurrentCulture</li>
    <li><b>CurrentUICulture</b>: @CultureInfo.CurrentUICulture</li>
</ul>

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

Usa il componente mostrato nella sezione del componente dimostrativo per studiare come funziona la globalizzazione per un componente che eredita la modalità di rendering automatico globale. Aggiungere il componente CultureExample1 alla cartella .Client del progetto di Pages. Nella parte superiore del componente specificare la modalità di rendering automatico interattivo:

@rendermode InteractiveAuto

Aggiungi i componenti CultureClient, CultureServer e CultureExample1 alla navigazione della barra laterale in Components/Layout/NavMenu.razor del progetto server:

<div class="nav-item px-3">
    <NavLink class="nav-link" href="culture-server">
        <span class="bi bi-list-nested-nav-menu" aria-hidden="true"></span> Culture (Server)
    </NavLink>
</div>
<div class="nav-item px-3">
    <NavLink class="nav-link" href="culture-client">
        <span class="bi bi-list-nested-nav-menu" aria-hidden="true"></span> Culture (Client)
    </NavLink>
</div>
<div class="nav-item px-3">
    <NavLink class="nav-link" href="culture-example-1">
        <span class="bi bi-list-nested-nav-menu" aria-hidden="true"></span> Culture (Auto)
    </NavLink>
</div>

Aggiornamenti del progetto server

Aggiungere il pacchetto Microsoft.Extensions.Localization al progetto server.

Nota

Per indicazioni sull'aggiunta di pacchetti alle app .NET, vedere gli articoli in Installare e gestire pacchetti all'indirizzo Package consumption workflow (documentazione nuGet). Confermare le versioni corrette del pacchetto all'indirizzo NuGet.org.

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

Nel file del progetto server Program in cui sono registrati i servizi:

builder.Services.AddLocalization();

Impostare le culture predefinite e supportate dell'app con RequestLocalizationOptions.

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

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

app.UseRequestLocalization(localizationOptions);

L'esempio seguente mostra come impostare la cultura corrente in un cookie che può essere letto dal middleware di localizzazione.

Aggiungere i namespace System.Globalization e Microsoft.AspNetCore.Localization all'inizio del componente App (Components/App.razor):

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

Le impostazioni delle culture 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 resa persistente nell'archiviazione locale del browser per i componenti CSR.

Dopo il tag Blazor<script>, fornire JS le funzioni per recuperare e impostare la selezione delle impostazioni cultura dell'utente tramite 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 funzioni globali. Per un approccio migliore nelle app di produzione, vedere Isolamento JavaScript nei moduli JavaScript.

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

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

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

Per fornire un'interfaccia utente che consenta a un utente di selezionare una cultura, usare un approccio basato sul reindirizzamento con localizzazione . L'app mantiene le impostazioni cultura selezionate dall'utente tramite un reindirizzamento a un endpoint API minimo. L'endpoint imposta la cultura selezionata dall'utente in un cookie e reindirizza l'utente all'URI di origine. 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.

All'inizio del file Program, aggiungere la seguente istruzione using per lo spazio dei nomi richiesto:

using Microsoft.AspNetCore.Localization;

Nella pipeline di elaborazione delle richieste del file Program dell'app dopo la chiamata a UseRequestLocalization:

app.MapGet("/Culture/Set", (string? culture, string redirectUri = "/",
    HttpContext context) =>
{
    if (!string.IsNullOrWhiteSpace(culture))
    {
        context.Response.Cookies.Append(
            CookieRequestCultureProvider.DefaultCookieName,
            CookieRequestCultureProvider.MakeCookieValue(
                new RequestCulture(culture, culture)));
    }

    return Results.LocalRedirect(redirectUri);
});

Avviso

Usare il LocalRedirect risultato, come illustrato nell'esempio precedente, per impedire attacchi di reindirizzamento aperti. Per altre informazioni, vedere Prevent open redirect attacks in ASP.NET Core.

Localizzazione

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

Nota

Per indicazioni sull'aggiunta di pacchetti alle app .NET, vedere gli articoli in Installare e gestire pacchetti all'indirizzo Package consumption workflow (documentazione 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>

Nel file Program, aggiungere lo spazio dei nomi di 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

Usare il middleware di localizzazione per impostare la cultura dell'app.

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

  • Aggiungere servizi di localizzazione all'app con AddLocalization.
  • Specifica le culture predefinite e supportate dell'app nel file Program. L'esempio seguente configura le impostazioni cultura supportate per inglese degli Stati Uniti e spagnolo della Costa Rica.
builder.Services.AddLocalization();

Inserire il middleware di localizzazione prima di qualsiasi middleware che possa verificare la cultura della richiesta. Il middleware va generalmente posizionato immediatamente prima di chiamare MapRazorComponents:

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

var supportedCultures = new[] { "en-US", "es-CR" };
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 Core middleware.

  • Aggiungere servizi di localizzazione all'app con AddLocalization.
  • Specificare le culture predefinite e supportate dell'app in Startup.Configure (Startup.cs). L'esempio seguente configura le impostazioni cultura supportate per inglese degli Stati Uniti e spagnolo della Costa Rica.

In Startup.ConfigureServices (Startup.cs):

services.AddLocalization();

In Startup.Configure subito dopo aver aggiunto il middleware di routing (UseRouting) alla pipeline di elaborazione:

var supportedCultures = new[] { "en-US", "es-CR" };
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 di Startup.Configure, vedere ASP.NET Core middleware.

Se l'app deve localizzare le risorse in base alle impostazioni della cultura di un utente, usa la cultura di localizzazione cookie. L'uso di un cookie garantisce che la connessione WebSocket possa propagare correttamente le impostazioni della 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 WebSockets, quindi non riuscirà a mantenere persistente la cultura. Pertanto, l'approccio consigliato consiste nell'usare impostazioni culturali di localizzazione cookie. Consultare la sezione sulle impostazioni dinamiche della cultura lato server in base alle preferenze dell'utente di questo articolo per vedere un esempio di espressione Razor che conserva la selezione della 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 un file di risorse per ogni impostazione locale. Nell'esempio seguente vengono create risorse per una Greeting stringa in inglese e spagnolo:

  • Inglese (en): 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 sulla cartella Pages e selezionando Aggiungi>Nuovo elemento>Risorse File. Denominare il file CultureExample2.resx. Quando viene visualizzato l'editor, specificare i dati per una nuova voce. Imposta il Nome su Greeting e il Valore su Hello, World!. Salvare il file.

Se si usa Visual Studio Code, è consigliabile installare Editor e visualizzatore ResX diTim Heuer. Aggiungere un file vuoto CultureExample2.resx alla Pages cartella . L'estensione assume automaticamente la gestione del file nell'interfaccia utente. Selezionare il pulsante Aggiungi nuova risorsa . Segui le istruzioni per aggiungere una voce per Greeting (chiave), Hello, World! (valore) e None (commento). Salvare il file. Se si chiude e si riapri il file, è possibile visualizzare la Greeting risorsa.

Il visualizzatore e editor ResX di Tim Heuer non è di proprietà di Microsoft né gestito da Microsoft e non è coperto da alcun contratto supporto tecnico Microsoft né da alcuna licenza.

Di seguito viene illustrato un file di risorse tipico. È possibile inserire manualmente i file di risorse nella cartella Pages dell'app se si preferisce non usare gli strumenti predefiniti con un ambiente di sviluppo integrato (IDE), ad esempio l'editor di file di risorse predefinito di Visual Studio o Visual Studio Code con un'estensione per la creazione e la modifica di file di risorse.

Pages/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 sulla cartella Pages e selezionando Aggiungi>Nuovo elemento>Risorse File. Denominare il file CultureExample2.es.resx. Quando viene visualizzato l'editor, specificare i dati per una nuova voce. Imposta il Nome su Greeting e il Valore su ¡Hola, Mundo!. Salvare il file.

Se si usa Visual Studio Code, è consigliabile installare Editor e visualizzatore ResX diTim Heuer. Aggiungere un file vuoto CultureExample2.resx alla Pages cartella . L'estensione assume automaticamente la gestione del file nell'interfaccia utente. Selezionare il pulsante Aggiungi nuova risorsa . Segui le istruzioni per aggiungere una voce per Greeting (chiave), ¡Hola, Mundo! (valore) e None (commento). Salvare il file. Se si chiude e si riapri il file, è possibile visualizzare la Greeting risorsa.

Di seguito viene illustrato un file di risorse tipico. È possibile inserire manualmente i file di risorse nella cartella Pages dell'app se si preferisce non usare gli strumenti predefiniti con un ambiente di sviluppo integrato (IDE), ad esempio l'editor di file di risorse predefinito di Visual Studio o Visual Studio Code con un'estensione per la creazione e la modifica di file di risorse.

Pages/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 la chiave associata al Greeting valore impostato nei file di risorse precedenti.

Aggiungere lo spazio dei nomi per Microsoft.Extensions.Localization al file di importazione 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>

<ul>
    <li><b>CurrentCulture</b>: @CultureInfo.CurrentCulture</li>
    <li><b>CurrentUICulture</b>: @CultureInfo.CurrentUICulture</li>
</ul>

<h2>Greeting</h2>

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

<p>
    @greeting
</p>

@code {
    private string? greeting;

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

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

Origine di riferimento del fornitore di cultura WebAssembly

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

Nota

I collegamenti alla documentazione della sorgente di riferimento .NET in genere caricano il branch predefinito del repository, che rappresenta lo sviluppo in corso della versione successiva di .NET. Per selezionare un tag per una versione specifica, usare l'elenco a discesa Passa ai rami o ai tag.

Risorse condivise

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

  • Verificare che il pacchetto Microsoft.Extensions.Localization faccia riferimento al progetto.

    Nota

    Per indicazioni sull'aggiunta di pacchetti alle app .NET, vedere gli articoli in Installare e gestire pacchetti all'indirizzo Package consumption workflow (documentazione nuGet). Confermare le versioni corrette del pacchetto all'indirizzo NuGet.org.

  • Verifica che lo spazio dei nomi Microsoft.Extensions.Localization sia disponibile per i componenti Razor del progetto mediante una voce nel file imports del progetto (_Imports.razor):

    @using Microsoft.Extensions.Localization
    
  • Creare una classe fittizia con un nome di classe arbitrario. Nell'esempio seguente :

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

    Nota

    Non usare un file di progettazione generato automaticamente , ad esempio SharedResources.Designer.cs. La classe fittizia è destinata a fungere da classe di risorse condivise. La presenza di un file di progettazione genera un conflitto tra spazi dei nomi.

    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

    Avviso

    Quando si segue l'approccio in questa sezione, non è possibile impostare LocalizationOptions.ResourcesPath e usare IStringLocalizerFactory.Create contemporaneamente per caricare le risorse.

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

    • Il primo esempio definisce lo spazio dei nomi Localization per la classe fittizia SharedResource con una direttiva @using.
    • 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 Globalization and localization in ASP.NET Core.

Override della posizione usando il pannello "Sensori" negli strumenti di sviluppo

Quando si utilizza la sostituzione della posizione tramite il riquadro Sensors negli strumenti di sviluppo di Google Chrome o Microsoft Edge, la lingua di fallback si resetta dopo il prerendering. Evitare di impostare la lingua usando il riquadro Sensori durante il test. Impostare la lingua usando le impostazioni della lingua del browser.

Per altre informazioni, vedere Blazor Localizzazione non funziona con InteractiveServer (dotnet/aspnetcore #53707)..