Fornire risorse localizzate per lingue e impostazioni cultura in un'app core ASP.NET
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.
Rick Anderson, Damien Bowden, Bart Calixto, Nadeem Afana e Hisham Bin Ateya
Un'attività per la localizzazione di un'app consiste nel fornire stringhe localizzate nei file di risorse. Questo articolo illustra l'uso dei file di risorse.
SupportedCultures e SupportedUICultures
ASP.NET Core include due raccolte di valori delle impostazioni cultura e SupportedCultures SupportedUICultures. L'oggetto CultureInfo per SupportedCultures determina i risultati delle funzioni dipendenti dalle impostazioni cultura, ad esempio data, ora, numero e formattazione della valuta. SupportedCultures determina anche l'ordinamento del testo, le convenzioni di maiuscole e minuscole e i confronti di stringhe. Per StringComparer.CurrentCulture altre informazioni su come il server ottiene le impostazioni cultura. Determina SupportedUICultures quali stringhe tradotte (da file con estensione resx ) vengono cercate dall'oggetto ResourceManager. Cerca ResourceManager semplicemente stringhe specifiche delle impostazioni cultura determinate da CurrentUICulture. Ogni thread in .NET include oggetti CurrentCulture e CurrentUICulture. ASP.NET Core controlla questi valori quando viene eseguito il rendering delle funzioni dipendenti dalle impostazioni cultura. Ad esempio, se le impostazioni cultura del thread corrente sono impostate su "en-US" (inglese, Stati Uniti), DateTime.Now.ToLongDateString() visualizza "Thursday, February 18, 2016". Se invece CurrentCulture è impostato su "es-ES" (spagnolo, Spagna) l'output sarà "jueves, 18 de febrero de 2016".
File di risorse
NOTA: Il visualizzatore ResX e l'editor forniscono un meccanismo alternativo per lavorare con i file di risorse usando Visual Studio Code.
Un file di risorse è un meccanismo utile per la separazione delle stringhe localizzabili dal codice. Le stringhe tradotte per la lingua non predefinita sono isolate nei file di risorse resx . Ad esempio, è possibile creare un file di risorse spagnolo denominato Welcome.es.resx contenente stringhe tradotte. "es" è il codice di lingua per lo spagnolo. Per creare questo file di risorse in Visual Studio:
In Esplora soluzioni fare clic con il pulsante destro del mouse sulla cartella che conterrà il file di risorse e quindi scegliere Aggiungi>nuovo elemento.
Nella casella Cerca modelli installati immettere "risorse" e assegnare un nome al file.
Immettere il valore della chiave (stringa nativa) nella colonna Nome e la stringa tradotta nella colonna Valore.
Visual Studio visualizza il file Welcome.es.resx.
Denominazione dei file di risorse
Le risorse sono denominate con il nome completo del tipo della relativa classe meno il nome dell'assembly. Ad esempio, una risorsa francese di un progetto il cui assembly principale è LocalizationWebsite.Web.dll per la classe LocalizationWebsite.Web.Startup viene denominata Startup.fr.resx. Una risorsa per la classe LocalizationWebsite.Web.Controllers.HomeController viene denominata Controllers.HomeController.fr.resx. Se lo spazio dei nomi della classe di destinazione non corrisponde al nome dell'assembly è necessario specificare il nome completo del tipo. Ad esempio, nel progetto di esempio una risorsa per il tipo ExtraNamespace.Tools verrebbe denominata ExtraNamespace.Tools.fr.resx.
Nel progetto di esempio il ConfigureServices metodo imposta su ResourcesPath "Resources", quindi il percorso relativo del progetto per il home file di risorse francese del controller è Resources/Controllers.HomeController.fr.resx. In alternativa, è possibile usare le cartelle per organizzare i file di risorse. Per il home controller, il percorso sarà Resources/Controllers/HomeController.fr.resx. Se non si usa l'opzione ResourcesPath, il file con estensione resx viene memorizzato nella directory di base del progetto. Il file di risorse per HomeController sarà denominato Controllers.HomeController.fr.resx. La scelta di usare la convenzione di denominazione con il punto o il percorso dipende da come si vuole organizzare i file di risorse.
| Nome risorsa | Denominazione con il punto o il percorso |
|---|---|
| Resources/Controllers.HomeController.fr.resx | Punto |
| Resources/Controllers/HomeController.fr.resx | Percorso |
I file di risorse che usano @inject IViewLocalizer nelle Razor visualizzazioni seguono un modello simile. Il file di risorse per una visualizzazione può essere denominato usando la denominazione con il punto o con il percorso. Razor visualizzare i file di risorse simulare il percorso del file di visualizzazione associato. Supponendo di impostare su ResourcesPath "Resources", il file di risorse francese associato alla Views/Home/About.cshtml vista potrebbe essere uno dei seguenti:
Resources/Views/Home/About.fr.resx
Resources/Views.Home. About.fr.resx
Se non si usa l'opzione ResourcesPath, il file con estensione resx per una visualizzazione viene inserito nella stessa cartella della visualizzazione.
RootNamespaceAttribute
L'attributo RootNamespaceAttribute fornisce lo spazio dei nomi radice di un assembly quando lo spazio dei nomi radice di un assembly è diverso dal nome dell'assembly.
Avviso
Ciò può verificarsi quando il nome di un progetto non è un identificatore .NET valido. Ad esempio my-project-name.csproj , userà lo spazio dei nomi my_project_name radice e il nome my-project-name dell'assembly che genera questo errore.
Se lo spazio dei nomi radice di un assembly è diverso dal nome dell'assembly:
- Per impostazione predefinita, la localizzazione non funziona.
- Le risorse vengono cercate all'interno dell'assembly in un modo che impedisce la localizzazione.
RootNamespaceè un valore necessario in fase di compilazione che non è disponibile per il processo in esecuzione.
Se è RootNamespace diverso da AssemblyName, includere quanto segue in AssemblyInfo.cs (con i valori dei parametri sostituiti con i valori effettivi):
using System.Reflection;
using Microsoft.Extensions.Localization;
[assembly: ResourceLocation("Resource Folder Name")]
[assembly: RootNamespace("App Root Namespace")]
Il codice precedente consente di risolvere correttamente i file resx.
Comportamento di fallback delle impostazioni cultura
Durante la ricerca di una risorsa, la localizzazione esegue un "fallback delle impostazioni cultura". A partire dalle impostazioni cultura richieste, se queste non vengono trovate, il codice adotta le impostazioni cultura padre di quelle richieste. Da parte, la CultureInfo.Parent proprietà rappresenta le impostazioni cultura padre. Questo significa in genere (ma non sempre) rimuovere il significato nazionale dal codice lingua e cultura. Ad esempio la versione della lingua spagnola parlata in Messico è "es-MX". Ha il padre "es" - spagnolo non specifico di qualsiasi paese.
Si supponga che il sito riceva una richiesta di una risorsa "Welcome" che usa le impostazioni cultura "fr-CA". Il sistema di localizzazione cerca le risorse seguenti nell'ordine elencato e seleziona la prima corrispondenza:
- Welcome.fr-CA.resx
- Welcome.fr.resx
- Welcome.resx (se
NeutralResourcesLanguageè "fr-CA")
Ad esempio, se si rimuove l'indicatore delle impostazioni cultura ".fr" e le impostazioni cultura sono impostate sul francese, viene letto il file di risorse predefinito e vengono localizzate le stringhe. Lo strumento di gestione delle risorse imposta una risorsa predefinita o di fallback per i casi in cui nessun elemento soddisfa le impostazioni cultura richieste. Per restituire solo la chiave in caso di mancanza di una risorsa per le impostazioni cultura richieste è necessario che non sia specificato un file di risorse predefinito.
Generare file di risorse con Visual Studio
Se si crea un file di risorse in Visual Studio senza le impostazioni cultura nel nome del file (ad esempio, Welcome.resx), Visual Studio crea una classe C# con una proprietà per ogni stringa. In genere questo non è il risultato desiderato quando si usa ASP.NET Core. Solitamente non è presente un file di risorse con estensione resx predefinito (un file con estensione resx senza nome delle impostazioni cultura). Si consiglia di creare il file con estensione resx con un nome delle impostazioni cultura, ad esempio Welcome.fr.resx. Quando si crea un file con estensione resx con un nome delle impostazioni cultura, Visual Studio non genera il file di classe.
Aggiungere altre impostazioni cultura
Ogni combinazione di lingua e impostazioni cultura (diversa dalla lingua predefinita) richiede un file di risorse univoco. È possibile creare file di risorse per impostazioni cultura e impostazioni locali diverse creando nuovi file di risorse in cui i codici di lingua fanno parte del nome del file , ad esempio en-us, fr-ca e en-gb. Questi codici vengono inseriti tra il nome del file e l'estensione di file resx , come in Welcome.es-MX.resx (spagnolo/Messico).
Passaggi successivi
La localizzazione di un'app comporta anche le attività seguenti:
- Rendere localizzabile il contenuto dell'app.
- Implementare una strategia per selezionare la lingua/le impostazioni cultura per ogni richiesta
Risorse aggiuntive
- Provider di impostazioni cultura url che usano il middleware come filtri in ASP.NET Core
- Applicazione globale di RouteDataRequest CultureProvider con middleware come filtri
- Globalizzazione e localizzazione in ASP.NET Core
- Rendere localizzabile il contenuto di un'app ASP.NET Core
- Strategie per la selezione di lingua e impostazioni cultura in un'app ASP.NET Core localizzata
- Risolvere i problemi di localizzazione di ASP.NET Core
- Globalizzazione e localizzazione di applicazioni .NET
- Progetto Localization.StarterWeb usato nell'articolo.
- Uso dei file RESX a livello di codice
- Microsoft Multilingual App Toolkit
- Localizzazione e generics
Rick Anderson, Damien Bowden, Bart Calixto, Nadeem Afana e Hisham Bin Ateya
Un'attività per la localizzazione di un'app consiste nel fornire stringhe localizzate nei file di risorse. Questo articolo illustra l'uso dei file di risorse.
SupportedCultures e SupportedUICultures
ASP.NET Core include due raccolte di valori delle impostazioni cultura e SupportedCultures SupportedUICultures. L'oggetto CultureInfo per SupportedCultures determina i risultati delle funzioni dipendenti dalle impostazioni cultura, ad esempio data, ora, numero e formattazione della valuta. SupportedCultures determina anche l'ordinamento del testo, le convenzioni di maiuscole e minuscole e i confronti di stringhe. Per StringComparer.CurrentCulture altre informazioni su come il server ottiene le impostazioni cultura. Determina SupportedUICultures quali stringhe tradotte (da file con estensione resx ) vengono cercate dall'oggetto ResourceManager. Cerca ResourceManager semplicemente stringhe specifiche delle impostazioni cultura determinate da CurrentUICulture. Ogni thread in .NET include oggetti CurrentCulture e CurrentUICulture. ASP.NET Core controlla questi valori quando viene eseguito il rendering delle funzioni dipendenti dalle impostazioni cultura. Ad esempio, se le impostazioni cultura del thread corrente sono impostate su "en-US" (inglese, Stati Uniti), DateTime.Now.ToLongDateString() visualizza "Thursday, February 18, 2016". Se invece CurrentCulture è impostato su "es-ES" (spagnolo, Spagna) l'output sarà "jueves, 18 de febrero de 2016".
File di risorse
Un file di risorse è un meccanismo utile per la separazione delle stringhe localizzabili dal codice. Le stringhe tradotte per la lingua non predefinita sono isolate nei file di risorse resx . Ad esempio, è possibile creare un file di risorse spagnolo denominato Welcome.es.resx contenente stringhe tradotte. "es" è il codice di lingua per lo spagnolo. Per creare questo file di risorse in Visual Studio:
In Esplora soluzioni fare clic con il pulsante destro del mouse sulla cartella che conterrà il file di risorse e quindi scegliere Aggiungi>nuovo elemento.
Nella casella Cerca modelli installati immettere "risorse" e assegnare un nome al file.
Immettere il valore della chiave (stringa nativa) nella colonna Nome e la stringa tradotta nella colonna Valore.
Visual Studio visualizza il file Welcome.es.resx.
Denominazione dei file di risorse
Le risorse sono denominate con il nome completo del tipo della relativa classe meno il nome dell'assembly. Ad esempio, una risorsa francese di un progetto il cui assembly principale è LocalizationWebsite.Web.dll per la classe LocalizationWebsite.Web.Startup viene denominata Startup.fr.resx. Una risorsa per la classe LocalizationWebsite.Web.Controllers.HomeController viene denominata Controllers.HomeController.fr.resx. Se lo spazio dei nomi della classe di destinazione non corrisponde al nome dell'assembly è necessario specificare il nome completo del tipo. Ad esempio, nel progetto di esempio una risorsa per il tipo ExtraNamespace.Tools verrebbe denominata ExtraNamespace.Tools.fr.resx.
Nel progetto di esempio il ConfigureServices metodo imposta su ResourcesPath "Resources", quindi il percorso relativo del progetto per il home file di risorse francese del controller è Resources/Controllers.HomeController.fr.resx. In alternativa, è possibile usare le cartelle per organizzare i file di risorse. Per il home controller, il percorso sarà Resources/Controllers/HomeController.fr.resx. Se non si usa l'opzione ResourcesPath, il file con estensione resx viene memorizzato nella directory di base del progetto. Il file di risorse per HomeController sarà denominato Controllers.HomeController.fr.resx. La scelta di usare la convenzione di denominazione con il punto o il percorso dipende da come si vuole organizzare i file di risorse.
| Nome risorsa | Denominazione con il punto o il percorso |
|---|---|
| Resources/Controllers.HomeController.fr.resx | Punto |
| Resources/Controllers/HomeController.fr.resx | Percorso |
I file di risorse che usano @inject IViewLocalizer nelle Razor visualizzazioni seguono un modello simile. Il file di risorse per una visualizzazione può essere denominato usando la denominazione con il punto o con il percorso. Razor visualizzare i file di risorse simulare il percorso del file di visualizzazione associato. Supponendo di impostare su ResourcesPath "Resources", il file di risorse francese associato alla Views/Home/About.cshtml vista potrebbe essere uno dei seguenti:
Resources/Views/Home/About.fr.resx
Resources/Views.Home. About.fr.resx
Se non si usa l'opzione ResourcesPath, il file con estensione resx per una visualizzazione viene inserito nella stessa cartella della visualizzazione.
RootNamespaceAttribute
L'attributo RootNamespaceAttribute fornisce lo spazio dei nomi radice di un assembly quando lo spazio dei nomi radice di un assembly è diverso dal nome dell'assembly.
Avviso
Ciò può verificarsi quando il nome di un progetto non è un identificatore .NET valido. Ad esempio my-project-name.csproj , userà lo spazio dei nomi my_project_name radice e il nome my-project-name dell'assembly che genera questo errore.
Se lo spazio dei nomi radice di un assembly è diverso dal nome dell'assembly:
- Per impostazione predefinita, la localizzazione non funziona.
- Le risorse vengono cercate all'interno dell'assembly in un modo che impedisce la localizzazione.
RootNamespaceè un valore necessario in fase di compilazione che non è disponibile per il processo in esecuzione.
Se è RootNamespace diverso da AssemblyName, includere quanto segue in AssemblyInfo.cs (con i valori dei parametri sostituiti con i valori effettivi):
using System.Reflection;
using Microsoft.Extensions.Localization;
[assembly: ResourceLocation("Resource Folder Name")]
[assembly: RootNamespace("App Root Namespace")]
Il codice precedente consente di risolvere correttamente i file resx.
Comportamento di fallback delle impostazioni cultura
Durante la ricerca di una risorsa, la localizzazione esegue un "fallback delle impostazioni cultura". A partire dalle impostazioni cultura richieste, se queste non vengono trovate, il codice adotta le impostazioni cultura padre di quelle richieste. Da parte, la CultureInfo.Parent proprietà rappresenta le impostazioni cultura padre. Questo significa in genere (ma non sempre) rimuovere il significato nazionale dal codice lingua e cultura. Ad esempio la versione della lingua spagnola parlata in Messico è "es-MX". Ha il padre "es" - spagnolo non specifico di qualsiasi paese.
Si supponga che il sito riceva una richiesta di una risorsa "Welcome" che usa le impostazioni cultura "fr-CA". Il sistema di localizzazione cerca le risorse seguenti nell'ordine elencato e seleziona la prima corrispondenza:
- Welcome.fr-CA.resx
- Welcome.fr.resx
- Welcome.resx (se
NeutralResourcesLanguageè "fr-CA")
Ad esempio, se si rimuove l'indicatore delle impostazioni cultura ".fr" e le impostazioni cultura sono impostate sul francese, viene letto il file di risorse predefinito e vengono localizzate le stringhe. Lo strumento di gestione delle risorse imposta una risorsa predefinita o di fallback per i casi in cui nessun elemento soddisfa le impostazioni cultura richieste. Per restituire solo la chiave in caso di mancanza di una risorsa per le impostazioni cultura richieste è necessario che non sia specificato un file di risorse predefinito.
Generare file di risorse con Visual Studio
Se si crea un file di risorse in Visual Studio senza le impostazioni cultura nel nome del file (ad esempio, Welcome.resx), Visual Studio crea una classe C# con una proprietà per ogni stringa. In genere questo non è il risultato desiderato quando si usa ASP.NET Core. Solitamente non è presente un file di risorse con estensione resx predefinito (un file con estensione resx senza nome delle impostazioni cultura). Si consiglia di creare il file con estensione resx con un nome delle impostazioni cultura, ad esempio Welcome.fr.resx. Quando si crea un file con estensione resx con un nome delle impostazioni cultura, Visual Studio non genera il file di classe.
Aggiungere altre impostazioni cultura
Ogni combinazione di lingua e impostazioni cultura (diversa dalla lingua predefinita) richiede un file di risorse univoco. È possibile creare file di risorse per impostazioni cultura e impostazioni locali diverse creando nuovi file di risorse in cui i codici di lingua fanno parte del nome del file , ad esempio en-us, fr-ca e en-gb. Questi codici vengono inseriti tra il nome del file e l'estensione di file resx , come in Welcome.es-MX.resx (spagnolo/Messico).
Passaggi successivi
La localizzazione di un'app comporta anche le attività seguenti:
- Rendere localizzabile il contenuto dell'app.
- Implementare una strategia per selezionare la lingua/le impostazioni cultura per ogni richiesta
Risorse aggiuntive
- Globalizzazione e localizzazione in ASP.NET Core
- Rendere localizzabile il contenuto di un'app ASP.NET Core
- Strategie per la selezione di lingua e impostazioni cultura in un'app ASP.NET Core localizzata
- Risolvere i problemi di localizzazione di ASP.NET Core
- Globalizzazione e localizzazione di applicazioni .NET
- Progetto Localization.StarterWeb usato nell'articolo.
- Uso dei file RESX a livello di codice
- Microsoft Multilingual App Toolkit
- Localizzazione e generics
