ASP.NET Globalizzazione e localizzazione di base Blazor

Articolo
11/12/2024

Nota

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

Avviso

Questa versione di ASP.NET Core non è più supportata. Per altre informazioni, vedere i criteri di supporto di .NET e .NET Core. Per la versione corrente, vedere la versione .NET 9 di questo articolo.

Importante

Queste informazioni si riferiscono a un prodotto non definitive che può essere modificato in modo sostanziale prima che venga rilasciato commercialmente. Microsoft non riconosce alcuna garanzia, espressa o implicita, in merito alle informazioni qui fornite.

Per la versione corrente, vedere la versione .NET 9 di questo articolo.

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

Globalizzazione e localizzazione

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:

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

Non supportato:IHtmlLocalizerla localizzazioneIViewLocalizer, 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:

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.

Le indicazioni contenute in questo articolo non illustrano l'impostazione dell'attributo del linguaggio HTML (<html lang="...">) della pagina, che usa gli strumenti di accessoblità. È 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 interoperabilità.

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 in .NET 6 o versione successiva. Quando la destinazione è ASP.NET Core 5.0 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 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.

Blazor fornisce il supporto predefinito per il rendering dei valori nelle impostazioni cultura correnti. Pertanto, la specifica di impostazioni cultura con @bind:culture non è consigliata quando si usano i date tipi di campo 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 È 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 10 a novembre 2025.

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 8.0 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 le impostazioni cultura invarianti, in genere basate su Stati Uniti inglese (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 altre informazioni, vedere Opzioni di configurazione del runtime per la globalizzazione (documentazione di .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> esegue l'override di un'impostazione precedente <InvariantTimezone> . È 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>

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 () 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 costaricano con una preferenza per Stati Uniti inglese o inglese:

Accept-Language: en-US,en; q=0.9,es-CR; 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>

Nello sviluppo lato client, l'impostazione dinamica delle impostazioni cultura dell'intestazione Accept-Language non è supportata.

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 sul lato server specificare le impostazioni cultura supportate dell'app prima di qualsiasi middleware che possa controllare le impostazioni cultura della richiesta. In genere, posizionare il middleware di localizzazione della richiesta immediatamente prima di chiamare MapRazorComponents. L'esempio seguente configura le impostazioni cultura supportate per Stati Uniti inglese e spagnolo costaricano:

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

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

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 costa ricano (es-CR) 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 (AM/PM) 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 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: 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>

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

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 <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 Blazor del progetto Core.

Aggiungere il blocco seguente <script> dopo <script> 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 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");

Nota

Attualmente, Blazor WebAssembly le app caricano solo le risorse in base a DefaultThreadCurrentCulture. Per altre informazioni, vedere Blazor WASM si basa solo sulle impostazioni cultura correnti (le impostazioni cultura correnti dell'interfaccia utente non sono rispettate) (dotnet/aspnetcore #56824).

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 prima di qualsiasi middleware che potrebbe controllare le impostazioni cultura della richiesta. In genere, posizionare il middleware di localizzazione della richiesta immediatamente prima di MapRazorComponents. L'esempio seguente configura Stati Uniti inglese:

Specificare le impostazioni cultura statiche nel Program file immediatamente dopo l'aggiunta del middleware di routing (UseRouting) 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.

Le app sul 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 le impostazioni cultura statiche in Startup.Configure (Startup.cs) 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 di Startup.Configure, vedere ASP.NET middleware principale.

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

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 dopo <script> 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 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();

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

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="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 (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 (CultureInfo.CurrentCulture != selectedCulture)
        {
            await JS.InvokeVoidAsync("blazorCulture.set", selectedCulture!.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

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

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

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

Le modifiche apportate al Pages/_Host.cshtml file richiedono gli spazi dei nomi seguenti:

Aggiungere il testo seguente 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 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 ProgramMapControllers controller nel file chiamando IEndpointRouteBuilder 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 , come illustrato nell'esempio precedente, 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 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 (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 (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 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à globaleComponents/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" />
```

Impostare dinamicamente le impostazioni cultura in base Blazor Web App alle preferenze utente

Questa sezione si applica a Blazor Web Apps che adottano l'interattività Auto (Server e WebAssembly).

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

Aggiornamenti al `.Client` progetto

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

Nota

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

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

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

using System.Globalization;
using Microsoft.JSInterop;

Rimuovere la riga seguente:

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

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

Aggiungere il componente seguente CultureSelector al .Client progetto.

Il componente adotta gli approcci seguenti per lavorare per i componenti SSR o CSR:

Il nome visualizzato di ogni lingua disponibile nell'elenco a discesa viene fornito da un dizionario perché i dati di globalizzazione sul lato client includono testo localizzato di nomi visualizzati delle impostazioni cultura forniti dai dati di globalizzazione lato server. Ad esempio, la localizzazione lato server viene visualizzata English (United States) quando en-US sono le impostazioni cultura e Ingles () quando vengono usate impostazioni cultura diverse. Poiché la localizzazione dei nomi visualizzati delle impostazioni cultura non è disponibile con Blazor WebAssembly la globalizzazione, il nome visualizzato per Stati Uniti inglese nel client per le impostazioni cultura caricate è solo en-US. L'uso di un dizionario personalizzato consente al componente di visualizzare almeno i nomi delle impostazioni cultura inglesi completi.
Quando l'utente modifica le impostazioni cultura, JS l'interoperabilità imposta le impostazioni cultura nell'archiviazione del browser locale e un'azione del controller aggiorna la localizzazione cookie con le impostazioni cultura. Il controller viene aggiunto all'app più avanti nella sezione Aggiornamenti del progetto Server.

Pages/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">@cultureDict[culture.Name]</option>
            }
        </select>
    </label>
</p>

@code
{
    private Dictionary<string, string> cultureDict = 
        new()
        {
            { "en-US", "English (United States)" },
            { "es-CR", "Spanish (Costa Rica)" }
        };

    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 (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 .Client (_Imports.razor), aggiungere il namespace dei componenti nella cartella Pages, aggiornandolo in modo che corrisponda al namespace del progetto .Client.

@using BlazorSample.Client.Pages

Nota

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

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

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

.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 seguente componente CultureServer per studiare come funziona la 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;
}

Usare il componente CultureExample1 mostrato nella sezione del componente di dimostrazione per studiare come funziona la globalizzazione per un componente che eredita la modalità di rendering automatico globale. Aggiungere il componente CultureExample1 alla cartella Pages del progetto di .Client.

Aggiungi i componenti CultureClient, CultureServere CultureExample1 al riquadro di spostamento laterale in Layout/NavMenu.razor:

<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 Microsoft.Extensions.Localization pacchetto al progetto server.

Nota

Le app sul 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 impostazioni cultura 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);

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:

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

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

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

Dopo il <script> , fornire JS le 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 funzioni globali. Per un approccio migliore nelle app di produzione, vedere Isolamento JavaScript nei moduli JavaScript.

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

Se il progetto server non è configurato 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 ProgramMapControllers controller nel file chiamando IEndpointRouteBuilder su (app):
```
app.MapControllers();
```

Per consentire a un utente di selezionare impostazioni cultura per i componenti SSR, 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

Componenti interattivi auto

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

Localizzazione

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

Nota

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. L'esempio seguente configura le impostazioni cultura supportate per Stati Uniti inglese e spagnolo costaricano.

builder.Services.AddLocalization();

Posizionare il middleware di localizzazione delle richieste prima di qualsiasi middleware che potrebbe controllare le impostazioni cultura della richiesta. In genere, posizionare il middleware 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 Middleware core.

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

In Startup.ConfigureServices (Startup.cs):

services.AddLocalization();

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

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 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 Pages cartella 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!. Salvare il file.

Se si usa Visual Studio Code, è consigliabile installare Il visualizzatore e l'editor ResX di Tim 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 . Seguire 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 l'editor ResX di Tim Heuer non sono di proprietà o gestiti da Microsoft e non sono coperti da alcun contratto o licenza supporto tecnico Microsoft.

Di seguito viene illustrato un file di risorse tipico. È possibile inserire manualmente i file di risorse nella cartella 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 Pages 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 Pages cartella 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!. Salvare il file.

Se si usa Visual Studio Code, è consigliabile installare Il visualizzatore e l'editor ResX di Tim 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 . Seguire 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.

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

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

Conferma che il pacchetto Microsoft.Extensions.Localization è referenziato dal progetto.

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.
Verificare che lo spazio dei nomi Microsoft.Extensions.Localization sia disponibile per i componenti Razor del progetto tramite una voce nel file _Imports del progetto:
```
@using Microsoft.Extensions.Localization
```
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.
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 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.

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

Quando si usa l'override della posizione usando il riquadro Sensori in Google Chrome o negli strumenti di sviluppo di Microsoft Edge, il linguaggio di fallback viene reimpostato dopo la prerisorsa. 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)..

Condividi tramite

ASP.NET Globalizzazione e localizzazione di base Blazor

Globalizzazione e localizzazione

Globalizzazione

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

Globalizzazione invariante

Informazioni sul fuso orario

Componente dimostrativo

Impostare dinamicamente le impostazioni cultura dall'intestazione `Accept-Language`

Impostare in modo statico le impostazioni cultura lato client

Impostare in modo statico le impostazioni cultura lato server

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

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

Impostare dinamicamente le impostazioni cultura in base Blazor Web App alle preferenze utente

Aggiornamenti al `.Client` progetto

Aggiornamenti del progetto server

Componenti interattivi auto

Localizzazione

Localizzazione lato client

Localizzazione lato server

Esempio di risorse localizzate

Origine di riferimento del provider delle impostazioni cultura WebAssembly

Risorse condivise

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

Risorse aggiuntive

Risorse aggiuntive

Condividi tramite

ASP.NET Globalizzazione e localizzazione di base Blazor

Globalizzazione e localizzazione

Globalizzazione

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

Globalizzazione invariante

Informazioni sul fuso orario

Componente dimostrativo

Impostare dinamicamente le impostazioni cultura dall'intestazione Accept-Language

Impostare in modo statico le impostazioni cultura lato client

Impostare in modo statico le impostazioni cultura lato server

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

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

Impostare dinamicamente le impostazioni cultura in base Blazor Web App alle preferenze utente

Aggiornamenti al .Client progetto

Aggiornamenti del progetto server

Componenti interattivi auto

Localizzazione

Localizzazione lato client

Localizzazione lato server

Esempio di risorse localizzate

Origine di riferimento del provider delle impostazioni cultura WebAssembly

Risorse condivise

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

Risorse aggiuntive

Risorse aggiuntive

Impostare dinamicamente le impostazioni cultura dall'intestazione `Accept-Language`

Aggiornamenti al `.Client` progetto