Localizzazione di contenuto HTML con il framework di localizzazione AIR HTML

Per utilizzare il framework di localizzazione, copiate il file AIRLocalizer.js nel progetto. Inseritelo quindi nel file HTML principale dell'applicazione utilizzando un tag script:

<script src="AIRLocalizer.js" type="text/javascript" charset="utf-8"></script>

Il codice JavaScript successivo può chiamare l'oggetto air.Localizer.localizer:

<script> 
    var localizer = air.Localizer.localizer; 
</script>

La classe Localizer comprende le seguenti proprietà statiche:

Il framework di localizzazione HTML legge le versioni localizzate delle stringhe dai file di localizzazione. Un file di localizzazione è una raccolta di valori basati su chiave, serializzati in un file di testo. Un file di localizzazione viene anche detto pacchetto.

Create una sottodirectory della directory di progetto dell'applicazione, denominata "locale". Potete anche utilizzare un nome diverso: consultate Personalizzazione delle impostazioni di AIR HTML Localizer. Questa directory comprenderà i file di localizzazione ed è detta anche directory dei pacchetti.

Create una sottodirectory della directory dei pacchetti per ogni impostazione locale supportata dall'applicazione. Denominate ogni sottodirectory in base al codice delle impostazioni locali, ad esempio assegnate alla directory del francese il codice "fr" e a quella dell'inglese il codice "en". Potete utilizzare un carattere di sottolineatura (_) per definire un'impostazione locale che comprenda una lingua e un codice di paese. Assegnate ad esempio alla directory dell'inglese americano il codice "en_us". In alternativa, potete utilizzare il trattino al posto del carattere di sottolineatura, come in "en-us". Il framework di localizzazione HTML supporta entrambi.

Potete aggiungere alla sottodirectory di un'impostazione locale il numero di file di risorse che desiderate. In genere si crea un file di localizzazione per ogni lingua (e lo si inserisce nella directory relativa alla lingua). Il framework di localizzazione HTML comprende un metodo getFile() che consente di leggere il contenuto di un file (consultate Ottenere risorse per impostazioni locali specifiche).

I file che hanno l'estensione .properties sono detti file di proprietà della localizzazione. Potete utilizzarli per specificare coppie chiave-valore per un'impostazione locale. Un file properties definisce un valore stringa per ogni riga. L'esempio seguente definisce un valore stringa "Hello in English." per una chiave denominata greeting:

greeting=Hello in English.

Un file properties contenente il testo seguente definisce sei coppie chiave-valore:

title=Sample Application 
greeting=Hello in English. 
exitMessage=Thank you for using the application. 
color1=Red 
color2=Green 
color3=Blue

L'esempio mostra una versione inglese del file properties da inserire nella directory en.

La versione francese di questo file properties si trova nella directory fr:

title=Application Example 
greeting=Bonjour en français. 
exitMessage=Merci d'avoir utilisé cette application. 
color1=Rouge 
color2=Vert 
color3=Bleu

Potete definire più file di risorse per diversi tipi di informazioni. Un file legal.properties può ad esempio contenere testo legale standard (come le informazioni di copyright). Potete riutilizzare la stessa risorsa in più applicazioni. Analogamente, potete definire file distinti che specifichino contenuto localizzato per parti differenti dell'interfaccia utente.

Per supportare più lingue, utilizzate la codifica UTF-8 per questi file.

Quando l'applicazione carica il file AIRLocalizer.js, esegue l'esame delle impostazioni locali specificate nell'applicazione. Queste impostazioni locali corrispondono alle sottodirectory della directory dei pacchetti (consultate Definizione di pacchetti di risorse). Questo elenco di impostazioni locali disponibili è detto anche catena di impostazioni locali. Il file AIRLocalizer.js ordina automaticamente la catena di impostazioni locali in base all'ordine preferito definito nelle impostazioni del sistema operativo. La proprietà Capabilities.languages elenca le lingue dell'interfaccia utente del sistema operativo nell'ordine preferito.

In tal modo, se un'applicazione definisce risorse per le impostazioni locali "en", "en_US" ed "en_UK", il framework di AIR HTML Localizer ordina la catena di impostazioni locali in modo corretto. Quando viene avviata un'applicazione in un sistema in cui "en" rappresenta l'impostazione locale principale, la catena delle impostazioni locali viene così ordinata: ["en", "en_US", "en_UK"]. In tal caso, l'applicazione cerca le risorse prima nel pacchetto "en", poi in quello "en_US".

Se invece in un sistema "en_US" rappresenta l'impostazione locale principale, l'ordinamento corrisponde a ["en_US", "en", en_UK"]. In tal caso, l'applicazione cerca le risorse prima nel pacchetto "en_US" e poi in quello "en".

Per impostazione predefinita, l'applicazione definisce le prime impostazioni locali della catena come impostazioni locali predefinite da utilizzare. Potete chiedere all'utente di selezionare le impostazioni locali alla prima esecuzione dell'applicazione e quindi memorizzare la selezione in un file di preferenze e utilizzare tali impostazioni locali al successivo avvio dell'applicazione.

L'applicazione può utilizzare stringhe delle risorse di qualunque impostazione locale della catena. Se per un'impostazione locale non è definita alcuna stringa di risorse, l'applicazione utilizzerà la successiva stringa di risorse corrispondente per altre impostazioni locali definite nella catena.

Potete personalizzare la catena di impostazioni locali chiamando il metodo setLocaleChain() dell'oggetto Localizer. Consultate Definizione della catena di impostazioni locali.

Un elemento dell'applicazione può fare riferimento al valore di una chiave di un file di proprietà di localizzazione. Ad esempio, l'elemento title dell'esempio seguente specifica un attributo local_innerHTML. Il framework di localizzazione utilizza questo attributo per cercare un valore localizzato. Per impostazione predefinita, il framework cerca i nomi degli attributi che iniziano con "local_". Il framework aggiorna gli attributi con nomi che corrispondono al testo successivo a "local_". In tal caso, il framework imposta l'attributo innerHTML dell'elemento title. L'attributo innerHTML utilizza il valore definito per la chiave mainWindowTitle nel file delle proprietà predefinite (default.properties):

<title local_innerHTML="default.mainWindowTitle"/>

Se per l'impostazione locale corrente non è definito alcun valore corrispondente, il framework di localizer cerca nel resto della catena di impostazioni locali. Utilizza l'impostazione locale successiva nella catena di impostazioni locali per cui è definito un valore.

Nell'esempio seguente, il testo (attributo innerHTML) dell'elemento p utilizza il valore della chiave greeting definito nel file delle proprietà predefinite:

<p local_innerHTML="default.greeting" />

Nell'esempio seguente, l'attributo value (e il testo visualizzato) dell'elemento input utilizza il valore della chiave btnBlue definita nel file delle proprietà predefinite:

<input type="button" local_value="default.btnBlue" />

Per aggiornare l'HTML DOM affinché vengano utilizzate le stringhe definite nella catena di impostazioni locali corrente, chiamate il metodo update() dell'oggetto Localizer. Se chiamate il metodo update(), l'oggetto Localizer analizza il DOM e applica modifiche se trova attributi di localizzazione ("local_..."):

air.Localizer.localizer.update();

Potete definire valori sia per un attributo (come "innerHTML") che per il corrispondente attributo di localizzazione (come "local_innerHTML"). In tal caso, il framework di localizzazione sovrascrive solo il valore dell'attributo se trova un valore corrispondente nella catena di localizzazione. Ad esempio, l'elemento seguente definisce gli attributi value e local_value:

<input type="text" value="Blue" local_value="default.btnBlue"/>

Potete anche aggiornare solamente un elemento DOM specifico. Consultate la sezione successiva, Aggiornamento degli elementi DOM per l'uso dell'impostazione locale corrente.

Per impostazione predefinita, AIR HTML Localizer utilizza "local_" come prefisso degli attributi che definiscono le impostazioni di localizzazione di un elemento. Ad esempio, per impostazione predefinita un attributo local_innerHTML definisce il pacchetto e il nome della risorsa utilizzati per il valore innerHTML di un elemento. Inoltre, per impostazione predefinita un attributo local_value definisce il pacchetto e il nome della risorsa utilizzati per l'attributo value di un elemento. È possibile configurare Localizer per utilizzare un prefisso di attributo diverso da "local_". Consultate Personalizzazione delle impostazioni di AIR HTML Localizer.

Quando l'oggetto Localizer aggiorna l'HTML DOM, gli elementi contrassegnati utilizzano i valori degli attributi in base a stringhe definite nella catena corrente delle impostazioni locali. Affinché il localizer HTML aggiorni l'HTML DOM, chiamate il metodo update() dell'oggetto Localizer:

air.Localizer.localizer.update();

Per aggiornare solamente un elemento DOM specificato, passatelo come parametro al metodo update(). Il metodo update() dispone di un solo parametro, parentNode, che è opzionale. Se specificato, il parametro parentNode definisce l'elemento DOM da localizzare. Quando chiamate il metodo update() e specificate un parametro parentNode, vengono impostati i valori localizzati per tutti gli elementi secondari che specificano attributi di localizzazione.

Ad esempio, considerate il seguente elemento div:

<div id="colorsDiv"> 
    <h1 local_innerHTML="default.lblColors" ></h1> 
    <p><input type="button" local_value="default.btnBlue" /></p> 
    <p><input type="button" local_value="default.btnRed" /></p> 
    <p><input type="button" local_value="default.btnGreen" /></p> 
</div>

Per aggiornare questo elemento affinché vengano utilizzate le stringhe localizzate specificate nella catena corrente di impostazioni locali, utilizzate il codice JavaScript seguente:

var divElement = window.document.getElementById("colorsDiv"); 
air.Localizer.localizer.update(divElement);

Se nella catena delle impostazioni locali non viene trovato alcun valore chiave, il framework di localizzazione imposta il valore dell'attributo sul valore dell'attributo "local_". Ad esempio, nell'esempio precedente, supponete che il framework di localizzazione non riesca a trovare un valore per la chiave lblColors (in qualsiasi file default.properties della catena di impostazioni locali). In tal caso, utilizza "default.lblColors" come valore innerHTML. L'uso di questo valore consente di indicare (allo sviluppatore) risorse mancanti.

Il metodo update() invia un evento resourceNotFound quando non riesce a trovare una risorsa nella catena di impostazioni locali. La costante air.Localizer.RESOURCE_NOT_FOUND definisce la stringa "resourceNotFound". L'evento dispone di tre proprietà: bundleName, resourceName e locale. La proprietà bundleName corrisponde al nome del pacchetto in cui non si trova la risorsa. La proprietà resourceName corrisponde al nome del pacchetto in cui non si trova la risorsa. La proprietà locale corrisponde al nome dell'impostazione locale in cui non si trova la risorsa.

Il metodo update() invia un evento bundleNotFound quando non riesce a trovare un pacchetto specificato. La costante air.Localizer.BUNDLE_NOT_FOUND definisce la stringa "bundleNotFound". L'evento dispone di due proprietà: bundleName e locale. La proprietà bundleName corrisponde al nome del pacchetto in cui non si trova la risorsa. La proprietà locale corrisponde al nome dell'impostazione locale in cui non si trova la risorsa.

Il metodo update() opera in modo asincrono (e invia gli eventi resourceNotFound e bundleNotFound in modo asincrono). Il codice seguente imposta i listener di eventi per gli eventi resourceNotFound e bundleNotFound:

air.Localizer.localizer.addEventListener(air.Localizer.RESOURCE_NOT_FOUND, rnfHandler); 
air.Localizer.localizer.addEventListener(air.Localizer.BUNDLE_NOT_FOUND, rnfHandler); 
air.Localizer.localizer.update(); 
function rnfHandler(event) 
{ 
    alert(event.bundleName + ": " + event.resourceName + ":." + event.locale); 
} 
function bnfHandler(event) 
{ 
    alert(event.bundleName + ":." + event.locale); 
}

Il metodo setBundlesDirectory() dell'oggetto Localizer consente di personalizzare il percorso della directory dei pacchetti. Il metodo setLocalAttributePrefix() dell'oggetto Localizer consente di personalizzare il percorso della directory dei pacchetti e il valore dell'attributo utilizzato da Localizer.

La directory dei pacchetti predefinita corrisponde alla sottodirectory delle impostazioni locali della directory dell'applicazione. Potete specificare un'altra directory chiamando il metodo setBundlesDirectory() dell'oggetto Localizer. Questo metodo accetta un parametro, path, che corrisponde al percorso della directory dei pacchetti predefinita in formato stringa. Il valore del parametro path può corrispondere a uno dei seguenti:

Ad esempio, il codice seguente imposta la directory dei pacchetti su una sottodirectory denominata "languages" nella directory di memorizzazione dell'applicazione (non della directory dell'applicazione):

air.Localizer.localizer.setBundlesDirectory("languages");

Se per il parametro path non viene passato un percorso valido, il metodo genera un'eccezione BundlePathNotFoundError. Questo errore ha "BundlePathNotFoundError" come proprietà name e la relativa proprietà message specifica il percorso non valido.

Per impostazione predefinita, AIR HTML Localizer utilizza "local_" come prefisso per gli attributi che definiscono le impostazioni di localizzazione di un elemento. Ad esempio, l'attributo local_innerHTML definisce il pacchetto e il nome della risorsa utilizzati per il valore innerHTML del seguente elemento input:

<p local_innerHTML="default.greeting" />

Il metodo setLocalAttributePrefix() dell'oggetto Localizer consente di utilizzare un prefisso dell'attributo diverso da "local_". Questo metodo statico accetta un parametro, ovvero la stringa che desiderate utilizzare come prefisso dell'attributo. Ad esempio, il codice seguente imposta il framework di localizzazione affinché venga utilizzato "loc_" come prefisso dell'attributo:

air.Localizer.localizer.setLocalAttributePrefix("loc_");

Potete personalizzare il prefisso dell'attributo utilizzato dal framework di localizzazione. Questa operazione può essere utile se il valore predefinito ("local_") entra in conflitto con il nome di un altro attributo che avete utilizzato nel codice. Assicuratevi di utilizzare caratteri validi per gli attributi HTML quando chiamate questo metodo (ad esempio, il valore non può contenere un carattere di spazio vuoto).

Per ulteriori informazioni sull'uso degli attributi di localizzazione negli elementi HTML, consultate Aggiornamento di elementi DOM con contenuto localizzato.

Le impostazioni relative alla directory dei pacchetti e al prefisso degli attributi non persistono tra le diverse sessioni dell'applicazione. Se utilizzate impostazioni personalizzate per la directory dei pacchetti o il prefisso degli attributi, assicuratevi di configurarle a ogni inizializzazione dell'applicazione.

Per impostazione predefinita, quando caricate il codice di AIRLocalizer.js, viene impostata la catena di impostazioni locali predefinita. Le impostazioni locali disponibili nella directory dei pacchetti e nelle impostazioni della lingua del sistema operativo definiscono questa catena di impostazioni locali. Per informazioni dettagliate, vedete Gestione di catene di impostazioni locali.

È possibile modificare la catena delle impostazioni locali chiamando il metodo statico setLocaleChain() dell'oggetto Localizer. Ad esempio, potete chiamare questo metodo se l'utente indica una preferenza per una lingua specifica. Il metodo setLocaleChain() accetta un parametro, chain, che è un array di impostazioni locali, ad esempio ["fr_FR","fr","fr_CA"]. L'ordine delle impostazioni locali nell'array imposta l'ordine in cui il framework cerca le risorse (nelle operazioni successive). Se non si trova una risorsa per la prima impostazione locale della catena, si continua a cercare nelle risorse di un'altra impostazione locale. Se l'argomento chain non è presente, non è un array oppure è un array vuoto, la funzione non viene eseguita e viene generata un'eccezione IllegalArgumentsError.

Il metodo statico getLocaleChain() dell'oggetto Localizer restituisce un array che elenca le impostazioni locali della catena di impostazioni locali corrente.

Il codice seguente legge la catena di impostazioni locali corrente e aggiunge due impostazioni locali per il francese all'inizio della catena:

var currentChain = air.Localizer.localizer.getLocaleChain(); 
newLocales = ["fr_FR", "fr"]; 
air.Localizer.localizer.setLocaleChain(newLocales.concat(currentChain));

Il metodo setLocaleChain() invia un evento "change" quando aggiorna la catena di impostazioni locali. La costante air.Localizer.LOCALE_CHANGE definisce la stringa "change". L'evento dispone di una proprietà, localeChain, un array di codici di impostazioni locali nella nuova catena di impostazioni locali. Il codice seguente imposta un listener di eventi per questo evento:

var currentChain = air.Localizer.localizer.getLocaleChain(); 
newLocales = ["fr_FR", "fr"]; 
localizer.addEventListener(air.Localizer.LOCALE_CHANGE, changeHandler); 
air.Localizer.localizer.setLocaleChain(newLocales.concat(currentChain)); 
function changeHandler(event) 
{ 
    alert(event.localeChain); 
}

La proprietà statica air.Localizer.ultimateFallbackLocale rappresenta l'impostazione locale utilizzata quando l'applicazione non supporta alcuna preferenza dell'utente. Il valore predefinito è "en". Potete impostarlo su un'altra impostazione locale, come illustrato nel codice seguente:

air.Localizer.ultimateFallbackLocale = "fr";

bundleName

resourceName

templateArgs

locale

Il framework di localizzazione può aggiornare attributi HTML DOM contrassegnati. Tuttavia, è possibile utilizzare le stringhe localizzate in altri modi. Ad esempio, è possibile utilizzare una stringa in codice HTML generato dinamicamente o come valore di parametro in una chiamata di funzione. Ad esempio, il codice seguente chiama la funzione alert() con la stringa definita nella risorsa error114 del file delle proprietà predefinito dell'impostazione locale fr_FR:

alert(air.Localizer.localizer.getString("default", "error114", null, "fr_FR"));

Il metodo getString() invia un evento resourceNotFound quando non riesce a trovare una risorsa nel pacchetto specificato. La costante air.Localizer.RESOURCE_NOT_FOUND definisce la stringa "resourceNotFound". L'evento dispone di tre proprietà: bundleName, resourceName e locale. La proprietà bundleName corrisponde al nome del pacchetto in cui non si trova la risorsa. La proprietà resourceName corrisponde al nome del pacchetto in cui non si trova la risorsa. La proprietà locale corrisponde al nome dell'impostazione locale in cui non si trova la risorsa.

Il metodo getString() invia un evento bundleNotFound quando non riesce a trovare il pacchetto specificato. La costante air.Localizer.BUNDLE_NOT_FOUND definisce la stringa "bundleNotFound". L'evento dispone di due proprietà: bundleName e locale. La proprietà bundleName corrisponde al nome del pacchetto in cui non si trova la risorsa. La proprietà locale corrisponde al nome dell'impostazione locale in cui non si trova la risorsa.

Il metodo getString() opera in modo asincrono (e invia gli eventi resourceNotFound e bundleNotFound in modo asincrono). Il codice seguente imposta listener di eventi per gli eventi resourceNotFound e bundleNotFound:

air.Localizerlocalizer.addEventListener(air.Localizer.RESOURCE_NOT_FOUND, rnfHandler); 
air.Localizerlocalizer.addEventListener(air.Localizer.BUNDLE_NOT_FOUND, bnfHandler); 
var str = air.Localizer.localizer.getString("default", "error114", null, "fr_FR"); 
function rnfHandler(event) 
{ 
    alert(event.bundleName + ": " + event.resourceName + ":." + event.locale); 
} 
function bnfHandler(event) 
{ 
    alert(event.bundleName + ":." + event.locale); 
}

Il metodo getResourceBundle() dell'oggetto Localizer restituisce un pacchetto specifico per una determinata impostazione locale. Il valore restituito del metodo è un oggetto le cui proprietà corrispondono alle chiavi nel pacchetto. Se l'applicazione non è in grado di trovare il pacchetto specificato, il metodo restituisce null.

locale

bundleName

var aboutWin = window.open(); 
var bundle = localizer.getResourceBundle("fr", "default"); 
aboutWin.document.write(bundle.str1); 
aboutWin.document.write("<br/>"); 
aboutWin.document.write(bundle.str2); 
aboutWin.document.write("<br/>");

Il metodo getResourceBundle() invia un evento bundleNotFound quando non riesce a trovare il pacchetto specificato. La costante air.Localizer.BUNDLE_NOT_FOUND definisce la stringa "bundleNotFound". L'evento dispone di due proprietà: bundleName e locale. La proprietà bundleName corrisponde al nome del pacchetto in cui non si trova la risorsa. La proprietà locale corrisponde al nome dell'impostazione locale in cui non si trova la risorsa.

resourceFileName

templateArgs

<html> 
<body>Hello, {0}. You have {1} new messages.</body> 
</html> 

<html> 
<body>Hello, Raúl. You have 4 new messages. </body> 
</html> 

locale

Ad esempio, il codice seguente chiama il metodo document.write() utilizzando il contenuto del file about.html dell'impostazione locale fr:

var aboutWin = window.open(); 
var aboutHtml = localizer.getFile("about.html", null, "fr"); 
aboutWin.document.close(); 
aboutWin.document.write(aboutHtml);

Il metodo getFile() invia un evento fileNotFound se non riesce a trovare una risorsa nella catena di impostazioni locali. La costante air.Localizer.FILE_NOT_FOUND definisce la stringa "resourceNotFound". Il metodo getFile() opera in modo asincrono (e invia l'evento fileNotFound in modo asincrono). L'evento ha due proprietà: fileName e locale. La proprietà fileName corrisponde al nome del file non trovato. La proprietà locale corrisponde al nome dell'impostazione locale in cui non si trova la risorsa. Il codice seguente imposta i listener di eventi per questo evento:

air.Localizer.localizer.addEventListener(air.Localizer.FILE_NOT_FOUND, fnfHandler); 
air.Localizer.localizer.getFile("missing.html", null, "fr"); 
function fnfHandler(event) 
{ 
    alert(event.fileName + ": " + event.locale); 
}