Cenni preliminari sulla localizzazione delle risorse per le librerie di componenti

Articolo
10/22/2014

Aggiornamento: novembre 2007

La localizzazione è il processo di adattamento di un'applicazione a determinate impostazioni cultura e linguistiche. La funzionalità AJAX di ASP.NET supporta i modelli seguenti di localizzazione da utilizzare nello script client:

Il modello di risorse di .NET Framework, con supporto espanso per le risorse localizzate associate ai componenti ECMAScript (JavaScript). In questo modello i file di script e le risorse di script localizzate vengono incorporati in un'organizzazione di assembly di tipo hub-and-spoke (ossia, si utilizzano assembly satellite). È quindi possibile utilizzare selettivamente gli script client incorporati e le risorse per lingue e regioni specifiche. Questo modello consente a una sola codebase di supportare più impostazioni cultura.
File JavaScript statici (autonomi) su disco. In questo modello, i file localizzati sono raggruppati in una sola directory come file js anziché incorporati in un assembly.
Aggiornamento degli script e delle risorse di script incorporate in un assembly utilizzando file JavaScript statici. Questo modello consente di fornire supporto aggiuntivo per la localizzazione di script incorporati e risorse incorporate senza richiedere alcuna modifica dell'assembly originale.

Di seguito sono riportate le informazioni contenute nel presente argomento:

Scenari
Informazioni di supporto
Localizzazione degli script client e delle risorse di script negli assembly
Localizzazione di file di script statici e delle relative risorse
Utilizzo di ScriptManager per gestire gli script in una posizione principale
Esempi di codice
Riferimento alle classi

Scenari

Le funzionalità AJAX di ASP.NET favoriscono la localizzazione client sia per gli sviluppatori di pagine che per gli sviluppatori di componenti. Gli sviluppatori di pagine localizzano in genere gli elementi seguenti:

Messaggi di eccezione generati da ASP.NET AJAX o dalle librerie dei componenti, a seconda dell'impostazione della lingua del browser.
Interfaccia utente per i controlli, ad esempio le stringhe per la proprietà Text di un controllo Button.
Valori per le proprietà pubbliche dei controlli server ASP.NET AJAX.
Valori per le proprietà di oggetti e componenti degli script client, ad esempio i componenti non visivi, i comportamenti e i controlli.

Gli sviluppatori di componenti utilizzano in genere le funzionalità di localizzazione per gli elementi seguenti:

Localizzazione di risorse alle quali si fa riferimento nel codice nelle librerie JavaScript (file js). Le risorse localizzate possono essere distribuite in installazioni separate, senza ricompilare l'assembly principale o la libreria di script.
Esposizione delle proprietà localizzabili dei controlli server mappate alle proprietà degli oggetti client.

Informazioni di supporto

Le funzionalità AJAX di ASP.NET si basano sul modello di localizzazione di ASP.NET 2.0 e forniscono supporto aggiuntivo per i file di script localizzati che sono incorporati in un assembly o che sono file js statici su disco.

Se non si ha familiarità con il modello di localizzazione di ASP.NET, è possibile reperire informazioni su di esso negli argomenti seguenti:

Localizzazione dei file di script client e delle risorse di script negli assembly

Le funzionalità ASP.NET AJAX sfruttano il modello di risorse di .NET Framework per la localizzazione. Questo modello utilizza una disposizione di tipo hub-and-spoke per assemblare e distribuire le risorse localizzate che possono essere aggiornate incrementalmente. L'hub è l'assembly principale che contiene il codice eseguibile non localizzato. Include sia il codice lato server di .NET Framework sia il codice JavaScript dei file js incorporati come risorsa nell'assembly.

L'assembly principale può inoltre contenere le risorse per singole impostazioni cultura, a cui si fa riferimento come impostazioni cultura neutre o predefinite. Le impostazioni cultura neutre sono le impostazioni cultura di fallback dell'applicazione. Vengono utilizzate se non ne sono specificate di diverse o se non esistono risorse per le impostazioni cultura specificate.

Le risorse localizzate per le impostazioni cultura vengono di solito create come coppie nome/valore nei file resx. Questi file resx possono essere compilati in file con estensione resources. Il nome fornisce accesso alle informazioni nel codice, mentre il valore è il termine, l'immagine o un altro elemento localizzato (tradotto) relativo al nome. Quando viene compilato un assembly, per il file resx viene generato un tipo nel quale i nomi sono esposti come campi che forniscono accesso a livello di codice ai valori. Il nome di questo tipo generato viene specificato nell'ambito delle proprietà dell'assembly, come descritto più avanti.

Nel modello hub-and-spoke, ogni spoke si collega a un assembly satellite che contiene le risorse relative a singole impostazioni cultura. L'assembly satellite non contiene codice eseguito dal server. Contiene solo il tipo generato che fornisce accesso a livello di codice ai valori delle risorse per tali impostazioni cultura.

Questo modello offre le funzionalità seguenti:

È possibile aggiungere risorse per nuove impostazioni cultura distribuendo nuovi assembly satellite dopo avere già distribuito un assembly. Lo sviluppo di risorse specifiche delle impostazioni cultura può richiedere ulteriore tempo. Questo modello consente pertanto di rilasciare prima l'applicazione principale e di fornire le ulteriori risorse specifiche delle impostazioni cultura in un secondo momento.
È possibile aggiornare gli assembly satellite di un'applicazione senza ricompilare l'assembly principale.
Un'applicazione deve caricare solo l'assembly satellite per particolari impostazioni cultura anziché scaricare e ricaricare l'assembly principale. In tal modo è possibile ridurre notevolmente l'utilizzo delle risorse di sistema.

Per ulteriori informazioni su come creare i file di risorse per ASP.NET, vedere Procedura: creare file di risorse per i siti Web ASP.NET (Visual Studio) e Localizzazione di pagine Web ASP.NET tramite risorse.

Per informazioni su come utilizzare lo strumento di generazione dei file di risorse (Resgen.exe) di°.NET Framework, vedere Generatore di file di risorse (Resgen.exe). Questo strumento converte i file txt e resx in file binari con estensione resources°che possono essere collegati ad assembly.

Organizzazione degli assembly principale e satellite localizzati

È possibile utilizzare il modello hub-and-spoke quando si desidera localizzare un'applicazione che include file JavaScript (con estensione js). In generale, si organizza l'assembly come qualsiasi applicazione ASP.NET localizzata.

Per gestire i file JavaScript per un'applicazione Web ASP.NET con supporto AJAX, si scrive il codice JavaScript in modo che le stringhe o gli altri elementi da localizzare non vengano impostati come hardcoded. Invece, in qualsiasi punto in cui il codice JavaScript deve utilizzare i valori localizzati, si ottiene un campo dal tipo generato dal file di risorse.

L'assembly principale include in genere gli elementi seguenti:

File JavaScript che eseguono le attività dell'applicazione e che sono scritti per utilizzare le risorse localizzate anziché quelle hardcoded. L'assembly può includere facoltativamente versioni di debug di tali file JavaScript.
Facoltativamente, risorse (file con estensione resx o resources) per singole impostazioni cultura, che fungono da impostazioni cultura di fallback per l'applicazione.
Facoltativamente, qualsiasi versione di debug di risorse delle impostazioni cultura neutre. La versione di debug di un file di risorse include le eventuali coppie aggiuntive nome/valore necessarie per le versioni di debug dei file JavaScript.

Un assembly satellite include in genere le risorse localizzate per singole impostazioni cultura per l'applicazione ASP.NET. Non occorre alcun assembly satellite per le impostazioni cultura di fallback. Le risorse per singole impostazioni cultura vengono create in un file di risorse separato (file con estensione resx o resources) e quindi compilate in un unico assembly satellite.

Nota:
ASP.NET consente di creare impostazioni cultura dell'interfaccia utente personalizzate e un nome di impostazioni cultura personalizzate. Tuttavia i nomi delle impostazioni cultura sono in genere basati su un codice lingua ISO, che è costituito da due lettere per la lingua e da due lettere maiuscole per il paese o la regione. Tra gli esempi, es-MX per lo spagnolo (Messico), es-CO per lo spagnolo (Colombia) e fr-CA per il francese (Canada). Per un elenco completo dei nomi delle impostazioni cultura, vedere i cenni preliminari sulla classe System.Globalization.CultureInfo.

ASP.NET consente di creare impostazioni cultura dell'interfaccia utente personalizzate e un nome di impostazioni cultura personalizzate. Tuttavia i nomi delle impostazioni cultura sono in genere basati su un codice lingua ISO, che è costituito da due lettere per la lingua e da due lettere maiuscole per il paese o la regione. Tra gli esempi, es-MX per lo spagnolo (Messico), es-CO per lo spagnolo (Colombia) e fr-CA per il francese (Canada). Per un elenco completo dei nomi delle impostazioni cultura, vedere i cenni preliminari sulla classe System.Globalization.CultureInfo.

Nomi per i file di script incorporati localizzati

Per i file di script localizzati incorporati come risorse è consigliabile utilizzare le seguenti convenzioni di denominazione:

scriptname_noextension.[debug].[UI culture identifier].[resources|resx]

La versione di debug di un nome di file include ".debug" nel nome. La versione finale no.

Nella tabella seguente vengono riportati alcuni esempi di tali convenzioni di denominazione. Negli esempi vengono mostrate una versione finale e una versione di debug di un file di script incorporato. Vengono inoltre mostrare la versione finale associata e la versione di debug associata delle risorse di tali file di script.

Sample.js
Una versione finale di un file di script delle impostazioni cultura neutre, incorporata nell'assembly principale.
Sample.debug.js
Una versione di debug di un file di script delle impostazioni cultura neutre, anch'essa incorporata nell'assembly principale.
Sample.fr-FR.resources
Una versione finale di risorse associate al file di script Sample.js, localizzate per specifiche impostazioni cultura dell'interfaccia utente. Queste risorse diventano parte dell'assembly satellite.
Sample.debug.fr-FR.resources
Risorse specifiche del debug associate al file di script Sample.debug.js, localizzate per specifiche impostazioni cultura dell'interfaccia utente. Queste risorse divengono parte dell'assembly satellite che include anche il file Sample.fr-FR.resources.

Queste convenzioni di denominazione non sono strettamente necessarie per i file di script incorporati negli assembly o per i file di risorse, poiché il mapping tra il tipo generato per la risorsa e il nome della risorsa viene eseguito utilizzando un attributo dell'assembly.

Localizzazione delle risorse degli script di debug

Se si sta utilizzando la modalità di debug, in fase di esecuzione ASP.NET combina la versione finale delle risorse per i file di script con le risorse aggiuntive di debug. Invia quindi la combinazione risultante al browser. Pertanto, quando si creano file di risorse per versioni di debug degli script, è necessario definire solo le coppie nome/valore che non sono già incluse nei file finali di risorse degli script. Per convenzione, le versioni di debug degli script e delle risorse degli script utilizzano lo stesso nome della relative controparte finale ma includono ".debug" dopo il nome del file di script.

Specifica degli attributi dell'assembly per gli script localizzati e le risorse localizzate associate agli script

Per specificare come i file di risorse devono essere gestiti quando viene compilato un assembly, si includono gli attributi nel file AssemblyInfo (AssemblyInfo.vb o AssemblyInfo.cs).

Nota:
In Visual Studio, per i progetti scritti in Visual Basic il file AssemblyInfo.vb si trova nel nodo Progetto di Esplora soluzioni. Se non sono presenti file nel nodo Progetto, scegliere Mostra tutti i file dal menu Progetto. Per i progetti scritti in C#, il file AssemblyInfo.cs si trova nel nodo Proprietà di Esplora soluzioni.

In ASP.NET, si contrassegnano le risorse per l'applicazione utilizzando la classe WebResourceAttribute. Per incorporare i file JavaScript in un assembly, si utilizza questo attributo per specificare i file js come risorsa Web.

Per includere i file di risorse per i file JavaScript incorporati, si utilizza la classe ScriptResourceAttribute. Questo attributo identifica le risorse basate su testo specificamente come risorse per i file JavaScript.

Nota:
La classe ScriptResourceAttribute può essere utilizzata per identificare solo le risorse basate su testo per i file JavaScript. Per associare un file di immagine localizzato (binario) alle impostazioni cultura, memorizzarne l'URL come risorsa localizzata che lo script può risolvere e caricare.

Nell'esempio seguente viene mostrato come utilizzare gli attributi dell'assembly per identificare gli script incorporati e le risorse degli script associate.

' Indicates that neutral fallback resources are retrieved from 
' the main assembly named MainAssembly.
<assembly: NeutralResourcesLanguageAttribute("en-US",
  UltimateResourceFallbackLocation.MainAssembly)>

' Defines embedded scripts as Web resources.
<assembly:WebResource("Sample.js", "text/javascript")>
<assembly:WebResource("Sample.debug.js", "text/javascript")>

' Defines the script resources for the scripts and their types.
<assembly:ScriptResource("Sample.js", "Sample.resources", 
  "Sample.Res")>
<assembly:ScriptResource("Sample.debug.js", "Sample.debug.resources", 
  "Sample.Res")>

// Indicates that neutral fallback resources are retrieved from 
// the main assembly named MainAssembly.

[assembly: NeutralResourcesLanguageAttribute("en-US",
  UltimateResourceFallbackLocation.MainAssembly)]

// Defines embedded scripts as Web resources.
[assembly:WebResource("Sample.js", "text/javascript")]
[assembly:WebResource("Sample.debug.js", "text/javascript")]

// Defines the script resources for the scripts and their types.
[assembly:ScriptResource("Sample.js", "Sample.resources", 
  "Sample.Res")]
[assembly:ScriptResource("Sample.debug.js", "Sample.debug.resources", 
  "Sample.Res")]

In questo esempio, un assembly denominato MainAssembly contiene una versione finale incorporata di un file di script client denominato Sample.js. L'assembly contiene inoltre la versione di debug corrispondente denominata Sample.debug.js. I file js sono identificati come risorse dall'attributo WebResourceAttribute.

L'attributo NeutralResourcesLanguageAttribute dell'assembly viene utilizzato per specificare l'assembly principale come impostazioni cultura di fallback. Per ulteriori informazioni, vedere Linguaggi di risorse non associate ad alcun paese per la localizzazione e i cenni preliminari sulla classe System.Resources.NeutralResourcesLanguageAttribute.

Le risorse utilizzate dai file di script sono identificate mediante l'attributo ScriptResourceAttribute. I file Sample.resources e Sample.debug.resources contengono i valori delle risorse rispettivamente per i file Sample.js e Sample.debug.js.

Un tipo denominato Sample.Res viene generato per la versione finale e per la versione di debug delle risorse degli script. Si tratta del tipo che il codice JavaScript utilizza per accedere ai valori localizzati. Per la modalità finale e per quella di debug, il processo di compilazione crea un solo tipo. Nella modalità di debug le risorse per la versione finale vengono combinate con le risorse aggiuntive per la versione di debug.

Per ulteriori informazioni sulla creazione di file di informazioni sull'assembly e dei metadati dell'assembly necessari per gli assembly con versione, vedere Procedura: creare assembly con versione per siti Web precompilati.

Localizzazione di file di script statici e delle relative risorse

È possibile organizzare una libreria di script come file di script statici localizzati (file con estensione js) su disco anziché incorporare i file di script negli assembly. Gli sviluppatori di pagine possono fare riferimento ai file di script tramite la classe ScriptReferenceCollection.

Nel modello di file di script statico, non vi sono file con estensione resx o resources distinti che possono essere gestiti automaticamente come risorse per i file JavaScript. Vi sono invece solo file con estensione js, uno per ogni combinazione di impostazioni cultura dell'interfaccia utente e impostazioni locali. In effetti, ogni file js rappresenta una versione specifica delle impostazioni locali del codice JavaScript completo. Una modalità tipica di questo modello per gestire i file di script localizzati consiste nell'utilizzare la stessa logica JavaScript in ogni file js. Come nel modello di assembly incorporato, il codice JavaScript richiama un tipo per recuperare i valori localizzati delle risorse. La differenza sta nel fatto che è necessario fornire il tipo che contiene i valori localizzati in quanto non viene generato automaticamente. Ad esempio, il file js per le singole impostazioni locali può includere il codice dell'applicazione e una classe che definisce i campi che contengono i valori localizzati. In ogni file js, questa classe contiene i valori in una lingua diversa.

Nota:
Nel modello di file di script statici, il codice JavaScript dell'applicazione presente nei file js può cessare di essere sincronizzato con il codice di un file JavaScript incorporato. Ciò è dovuto al fatto che ogni file di script include una copia del codice. Per evitare problemi di controllo della versione con il codice duplicato, è possibile gestire una sola copia dei file di origine JavaScript e creare tipi di risorsa localizzati in file separati. È quindi possibile generare i file combinati finali durante il processo di compilazione dell'applicazione.

Nel modello di file di script statici, il codice JavaScript dell'applicazione presente nei file js può cessare di essere sincronizzato con il codice di un file JavaScript incorporato. Ciò è dovuto al fatto che ogni file di script include una copia del codice. Per evitare problemi di controllo della versione con il codice duplicato, è possibile gestire una sola copia dei file di origine JavaScript e creare tipi di risorsa localizzati in file separati. È quindi possibile generare i file combinati finali durante il processo di compilazione dell'applicazione.

I file di script statici localizzati vengono mappati alle rispettive impostazioni cultura dell'interfaccia utente includendo il nome delle impostazioni cultura dell'interfaccia utente nel nome file, come avviene con le risorse incorporate in un assembly. Ad esempio, un file di script client incorporato culturalmente neutro per il francese sarebbe denominato Sample.fr.js e una risorsa JavaScript specifica delle impostazioni cultura per il francese (Canada) sarebbe denominato Sample.fr-CA.js.

Script di debug localizzati nel modello di file di script statici

Nel modello di file di script statici, le risorse localizzate alle quali uno script fa riferimento sono definite in genere come tipo in un solo file js. Una versione di debug di un file di script è organizzata allo stesso modo, con risorse della versione finale localizzate e risorse aggiuntive della versione di debug definite come tipo in un singolo file. Le versioni di debug degli script utilizzano lo stesso nome della versione finale corrispondente, ma includono ".debug" dopo il nome.

Utilizzo di ScriptManager per gestire gli script

È possibile utilizzare il controllo ScriptManager per gestire gli script statici situati in una directory centrale su disco. A tale scopo, inserire tutte le versioni dei file di script in un'unica cartella che includa le versioni finali e di debug di tutti i file localizzati. Nell'esempio seguente viene mostrato il layout di una struttura di directory per una libreria di file di script statici:

SampleNamespace/

1.0.0.0/

Sample.js

Sample.debug.js

Sample.de-DE.js

Sample.debug.de-DE.js

Sample.fr-FR.js

Sample.debug.fr-FR.js

In questo esempio tutti i file script si trovano in una cartella denominata con la versione della libreria di script (1.0.0.0). Questa cartella specifica della versione si trova a sua volta in una cartella il cui nome deriva dallo spazio dei nomi della libreria. L'organizzazione di una libreria di script all'interno di cartelle in base allo spazio dei nomi e alla versione consente di controllare in parte le versioni della libreria. Può inoltre consentire di evitare conflitti tra i nomi degli script delle librerie. Consente altresì agli utenti della libreria di identificare a quale libreria e a quale versione della libreria i file appartengono.

Informazioni sul ruolo del controllo ScriptManager nella localizzazione

Il controllo ScriptManager fornisce le funzionalità seguenti per l'utilizzo di script localizzati e di risorse di script localizzate:

Consente di definire quali impostazioni cultura dell'interfaccia utente sono supportate, incluse le impostazioni cultura dell'interfaccia utente personalizzate.
Interpreta l'attributo dell'assembly specifico delle impostazioni cultura e rileva automaticamente le impostazioni cultura dell'interfaccia utente del browser (se presenti). Legge quindi le risorse e gli script localizzati o di fallback dall'assembly. Nella modalità di debug, tenta di caricare una risorsa di script che contiene il nome delle impostazioni cultura dell'interfaccia utente appropriate e la stringa ".debug" nel nome file, ad esempio Sample.debug.fr-FR.resources.
Genera gli URL che puntano agli script appropriati e alle relative risorse localizzate. Per una maggiore sicurezza, crittografa gli URL.
Determina se uno script o una risorsa di script sarà compressa, in base a un parametro incluso nell'URL generato.
Aggiunge un timestamp all'assembly che contiene script incorporati così che il browser non memorizzi indefinitamente nella cache gli script.

Per ulteriori informazioni, vedere i cenni preliminari sulla classe ScriptManager.

Nell'esempio seguente viene mostrata una parte di una pagina Web che utilizza il controllo ScriptManager per registrare un controllo client che si trova in un assembly. Lo script incorporato viene registrato utilizzando le proprietà Assembly e Name.

<%@ Register TagPrefix="Samples" Namespace="DemoControls" 
  Assembly=" SampleAssembly" %>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" 
  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<html xmlns="http://www.w3.org/1999/xhtml">
<head >
  <title>ScriptReference</title>
</head>
<body>
  <form id="form1" >
    <div>
      <asp:ScriptManager ID="ScriptManager1" >
        <Scripts>
          <asp:ScriptReference Assembly="SampleAssembly"
              Name="DemoControls.SampleControl.js" />
        </Scripts>
      </asp:ScriptManager>

      <!-- Additional markup here. -->

    </div>
  </form>
</body>

Esempi di codice

Nelle sezioni seguenti sono inclusi esempi di codice che mostrano come utilizzare i file e le risorse JavaScript.

Procedure e procedure dettagliate

Riferimento alle classi

Nella tabella seguente sono elencate le classi principali utilizzate per localizzare le librerie dei componenti.

ScriptManager
Gestisce i componenti AJAX, il rendering a pagina parziale, le richieste dei client e le risposte del server nelle pagine server ASP.NET.
ScriptReference
Fornisce le API per registrare i file JavaScript per l'utilizzo in una pagina Web, sia che si tratti di file incorporati in un assembly sia che si tratti di file su disco.
ScriptReferenceCollection
Fornisce l'accesso agli oggetti ScriptReference che rappresentano i file di script client.

Vedere anche

Condividi tramite