Lokalisera HTML-innehåll med AIR HTML-lokaliseringsramverket

Om du vill använda lokaliseringsramverket kopierar du filen AIRLocalizer.js till ditt projekt. Inkludera den sedan i programmets HTML-huvudfil med hjälp av en script-tagg:

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

Efterföljande JavaScript kan anropa air.Localizer.localizer -objektet:

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

Klassen Localizer innehåller följande statiska egenskaper:

Använd elementet <supportedLanguages> i programbeskrivningsfilen för att identifiera de språk som programmet har stöd för. Det här elementet används bara av iOS, låsta Mac-miljöer och Android-program och ignoreras av alla andra programtyper.

Om du inte anger <supportedLanguages> -elementet utförs som standard följande åtgärder baserat på programtyp vid paketering:

Du hittar mer information i supportedLanguages .

HTML-lokaliseringsramverket läser lokaliserade strängversioner från lokaliserings filer. En lokaliseringsfil är en samling nyckelbaserade värden som är serialiserade i en textfil. En lokaliseringsfil kallas ibland för ett paket .

Skapa en underkatalog för programmets projektkatalog med namnet locale. (Du kan även använda ett annat namn, se Anpassa inställningar för HTML-lokalisering i AIR .) I den här katalogen finns lokaliseringsfilerna. Katalogen kallas paketkatalogen .

För varje språkinställning som programmet kan hantera skapar du en underkatalog i paketkatalogen. Namnge varje underkatalog så att den överensstämmer med språkinställningskoden. Kalla till exempel den franska katalogen ”fr” och den engelska katalogen ”en”. Du kan använda ett understreck (_) om du vill definiera en språkinställning som har en språkkod och en landskod. Kalla till exempel katalogen för amerikansk engelska för ”en_us”. (Du kan också använda ett bindestreck i stället för ett understreck, t.ex. ”en-us”. HTML-lokaliseringsramverket kan hantera båda alternativen.)

Du kan lägga till valfritt antal resursfiler i en språkinställningsunderkatalog. Vanligtvis skapar du en lokaliseringsfil för varje språk (och placerar filen i katalogen för det språket). I HTML-lokaliseringsramverket finns en getFile() -metod som gör att du kan läsa innehåll i en fil (se Hämta resurser för en särskild språkinställning .

Filer med filtillägget .properties kallas lokaliseringsegenskapsfiler. Du kan använda dem för att definiera nyckelvärdepar för en språkinställning. En egenskapsfil definierar ett strängvärde på varje rad. Följande definierar till exempel ett strängvärde "Hello in English." för en nyckel med namnet greeting :

greeting=Hello in English.

En egenskapsfil som innehåller följande text definierar sex nyckelvärdepar:

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

I det här exemplet visas en engelsk version av egenskapsfilen som ska sparas i katalogen en.

En fransk version av den här egenskapsfilen är placerad i katalogen fr:

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

Du kan definiera flera resursfiler för olika sorters information. Filen legal.properties kan till exempel innehålla formaterad, juridisk exempeltext (såsom upphovsrättsinformation). Du kan återanvända resursen i flera program. På liknande sätt kan du definiera separata filer som definierar lokaliserat innehåll för olika delar av användargränssnittet.

Använd UTF-8-kodning för de här filerna så att flera språk kan hanteras.

När programmet läser in filen AIRLocalizer.js undersöks de språkinställningar som är definierade i programmet. De här språkinställningarna motsvarar underkatalogerna i paketkatalogen (se Definiera resurspaket ). Den här listan med tillgängliga språkinställningar kallas språkkedja . Filen AIRLocalizer.js sorterar språkkedjan automatiskt utifrån den önskade ordningen som angetts i operativsystemets inställningar. ( Capabilities.languages -egenskapen listar operativsystemets användargränssnittsspråk i önskad ordning.)

Om ett program definierar resurser för språkinställningarna ”en”, ”en_US” och ”en_UK” så sorterar AIR:s HTML-lokaliseringsramverk språkkedjan på rätt sätt. Om ett program startas i ett system som har ”en” som primär språkinställning sorteras språkkedjan så här ["en", "en_US", "en_UK"] . I det här fallet letar programmet först efter resurser i ”en”-paketet och sedan i ”en_US”-paketet.

Om systemet anger ”en-US” som primär språkinställning används dock sorteringsordningen ["en_US", "en", en_UK"] . I det här fallet letar programmet först efter resurser i ”en_US”-paketet och sedan i ”en”-paketet.

Som standard definierar programmet den första språkinställningen i språkkedjan som den inställning som ska användas. Du kan be användaren välja en språkinställning första gången som programmet körs. Du kan sedan välja att spara valet i en inställningsfil och använda den språkinställningen vid efterföljande programstarter.

Programmet kan använda resurssträngar på alla språk i språkkedjan. Om en särskild språkinställning inte definierar en resurssträng använder programmet nästa matchande resurssträng för andra språk som är definierade i språkkedjan.

Du kan anpassa språkkedjan genom att anropa metoden setLocaleChain() för Localizer-objektet. Se Definiera språkkedjan .

Ett element i programmet kan referera till ett nyckelvärde i en lokaliseringsegenskapsfil. title -elementet i följande exempel anger till exempel ett local_innerHTML -attribut. Lokaliseringsramverket använder det här attributet för att leta reda på ett lokaliserat värde. Som standard söker ramverket efter attributnamn som börjar med "local_" . Ramverket uppdaterar de attribut som har namn som matchar texten som följer efter "local_" . I det här fallet ställer ramverket in innerHTML -attributet för title -elementet. innerHTML -attributet använder det värde som definierats för mainWindowTitle -nyckeln i standardegenskapsfilen (default.properties):

<title local_innerHTML="default.mainWindowTitle"/>

Om den aktuella språkinställningen inte definierar något matchande värde söker lokaliseringsramverket igenom resten av språkkedjan. Det använder nästa språkinställning i språkkedjan som ett värde är definierat för.

I följande exempel använder texten ( innerHTML -attribut) i p -elementet värdet för den greeting -nyckel som definierats i standardegenskapsfilen:

<p local_innerHTML="default.greeting" />

I följande exempel använder värdeattributet (och visad text) i input -elementet värdet för den btnBlue -nyckel som definierats i standardegenskapsfilen:

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

Om du vill uppdatera HTML DOM så att de strängar som definierats i den aktuella språkkedjan används, anropar du metoden update() för Localizer-objektet. Anrop av metoden update() gör att Localizer-objektet tolkar DOM och tillämpar förändringar där det finns lokaliseringsattribut ( "local_..." ):

air.Localizer.localizer.update();

Du kan definiera värden för både ett attribut (t.ex. ”innerHTML”) och dess motsvarande lokaliseringsattribut (t.ex. ”local_innerHTML”). I så fall skriver lokaliseringsramverket bara över attributvärdet om det hittar ett matchande värde i lokaliseringskedjan. Följande element definierar till exempel både value - och local_value -attributen:

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

Du kan också uppdatera ett särskilt DOM-element. Se nästa avsnitt, Uppdatera DOM-element så att den aktuella språkinställningen används .

Som standard använder AIR:s HTML-lokaliseringsramverk "local_" som prefix för attribut som definierar lokaliseringsinställningar för ett element. Som standard definierar till exempel ett local_innerHTML -attribut det paket och resursnamn som används för innerHTML -värdet i ett element. Som standard definierar också ett local_value -attribut det paket och resursnamn som används för value -attributet i ett element. Du kan konfigurera Localizer-objektet så att ett annat attributprefix än "local_" används. Se Anpassa inställningar för HTML-lokalisering i AIR .

När Localizer-objektet uppdaterar HTML DOM gör det så att markerade element använder attributvärden som baseras på strängar som är definierade i den aktuella språkkedjan. Om du vill att HTML-lokaliseringen ska uppdatera HTML DOM anropar du metoden update() för Localizer -objektet:

air.Localizer.localizer.update();

Om du bara vill uppdatera ett särskilt DOM-element skickar du det som en parameter till metoden update() . Metoden update() har bara en parameter, parentNode , som är valfri. Om parentNode -parametern är angiven definierar den DOM-elementet så att lokalisering görs. Om du anropar metoden update() och anger en parentNode -parameter ställs lokaliserade värden in för alla underordnade element som anger lokaliseringsattribut.

Här följer ett exempel på ett div -element:

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

Om du vill uppdatera det här elementet så att det använder lokaliserade strängar som definierats i den aktuella språkkedjan använder du följande JavaScript-kod:

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

Om ett nyckelvärde inte hittas i språkkedjan ställer lokaliseringsramverket in attributvärdet som värdet för "local_" -attributet. Anta till exempel att lokaliseringsramverket i föregående exempel inte hittar något värde för lblColors -nyckeln (i någon av default.properties-filerna i språkkedjan). I så fall använder det "default.lblColors" som innerHTML -värde. Om det här värdet används indikerar det (för utvecklaren) att resurser saknas.

Metoden update() skickar en resourceNotFound -händelse om den inte kan hitta en resurs i språkkedjan. Konstanten air.Localizer.RESOURCE_NOT_FOUND definierar strängen "resourceNotFound" . Händelsen har tre egenskaper: bundleName , resourceName och locale . bundleName -egenskapen är namnet på det paket där resursen inte hittas. resourceName -egenskapen är namnet på det paket där resursen inte hittas. locale -egenskapen är namnet på den språkinställning där resursen inte hittas.

Metoden update() skickar en bundleNotFound -händelse när den inte kan hitta det angivna paketet. Konstanten air.Localizer.BUNDLE_NOT_FOUND definierar strängen "bundleNotFound" . Händelsen har två egenskaper: bundleName och locale . bundleName -egenskapen är namnet på det paket där resursen inte hittas. locale -egenskapen är namnet på den språkinställning där resursen inte hittas.

Metoden update() utförs asynkront (och skickar händelserna resourceNotFound och bundleNotFound asynkront). Följande kod anger händelseavlyssnare för händelserna resourceNotFound och 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); 
}

Med hjälp av metoden setBundlesDirectory() i Localizer-objektet kan du anpassa sökvägen till paketkatalogen. Metoden setLocalAttributePrefix() i Localizer-objektet gör att du kan anpassa sökvägen till paketkatalogen och anpassa det attributvärde som används av Localizer-objektet.

Standardpaketkatalogen definieras som språkinställningsunderkatalog för programkatalogen. Du kan ange en annan katalog genom att anropa metoden setBundlesDirectory() för Localizer-objektet. Den här metoden används med en parameter som sträng, path , som är sökvägen till den önskade paketkatalogen. Värdet för path -parametern kan vara något av följande:

Följande kod anger till exempel paketkatalogen till en språkunderkatalog för programlagringskatalogen (inte programkatalogen):

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

Skicka en giltig sökväg som path -parametern. Annars orsakar metoden ett BundlePathNotFoundError-undantag. Det här felet har "BundlePathNotFoundError" som name -egenskap och dess message -egenskap anger den ogiltiga sökvägen.

Som standard använder AIR:s HTML-lokaliseringsramverk "local_" som prefix för attribut som definierar lokaliseringsinställningar för ett element. local_innerHTML -attributet definierar till exempel det paket och resursnamn som används för innerHTML -värdet i följande input -element:

<p local_innerHTML="default.greeting" />

Metoden setLocalAttributePrefix() i Localizer-objektet gör att du kan använda ett annat attributprefix än "local_" . Den här statiska metoden använder en parameter som är den sträng som du vill använda som attributprefix. Följande kod ställer till exempel in så att lokaliseringsramverket använder ”loc_” som attributprefix:

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

Du kan anpassa det attributprefix som lokaliseringsramverket använder. Du vill kanske anpassa prefixet om standardvärdet ( "local_" ) hamnar i konflikt med namnet på ett annat attribut som används av din kod. Var noga med att använda giltiga tecken för HTML-attribut när du anropar den här metoden. (Värdet kan t.ex. inte innehålla ett blanksteg.)

Mer information om hur du använder lokaliseringsattribut i HTML-element finns i Uppdatera DOM-element med lokaliserat innehåll .

Inställningarna för paketkatalogen och attributprefix finns inte kvar vid olika programsessioner. Om du använder en anpassad inställning för paketkatalog eller attributprefix måste du ange den varje gång som programmet startas.

Som standard ställs språkkedjan in när du läser in AIRLocalizer.js-koden. De språkinställningar som finns i paketkatalogen och operativsystemets språkinställningar definierar den här språkkedjan. (Mer information finns i Hantera språkkedjor .)

Du kan ändra språkkedjan genom att anropa metoden setLocaleChain() för Localizer-objektet. Du vill kanske anropa den här metoden om användaren anger en inställning för ett särskilt språk. Metoden setLocaleChain( ) använder en parameter, chain , som är en array med språkinställningar, t.ex. ["fr_FR","fr","fr_CA"] . Språkinställningarnas ordning i arrayen anger den ordning i vilken ramverket söker efter resurser (i efterföljande åtgärder). Om en resurs inte hittas för den första språkinställningen i kedjan fortsätter ramverket att leta i andra språkinställningars resurser. Om chain -argumentet saknas, inte är en array eller är en tom array, så misslyckas funktionen och orsakar ett IllegalArgumentsError-undantag.

Den statiska metoden getLocaleChain() i Localizer-objektet returnerar en array som innehåller de språkinställningar som finns i den aktuella språkkedjan.

Följande kod läser den aktuella språkkedjan och lägger till två franska språkinställningar längst upp i kedjan:

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

Metoden setLocaleChain() skickar en "change" -händelse när den uppdaterar språkkedjan. Konstanten air.Localizer.LOCALE_CHANGE definierar strängen "change" . Händelsen har en egenskap, localeChain , som är en array med språkinställningskoder i den nya språkkedjan. Följande kod anger en händelseavlyssnare för den här händelsen:

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

Den statiska egenskapen air.Localizer.ultimateFallbackLocale representerar den språkinställning som används när programmet inte stöder användarinställningar. Standardvärdet är "en" . Du kan ange en annan språkinställning enligt följande kod:

air.Localizer.ultimateFallbackLocale = "fr";

bundleName

resourceName

templateArgs

locale

Lokaliseringsramverket kan uppdatera markerade HTML DOM-attribut. Du kan dock använda lokaliserade strängar på andra sätt. Du kan till exempel använda en sträng i dynamiskt genererad HTML eller som ett parametervärde i ett funktionsanrop. Följande kod anropar till exempel funktionen alert() med den sträng som är definierad i error114 -resursen i standardegenskapsfilen för språkinställningen fr_FR:

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

Metoden getString() skickar en resourceNotFound -händelse när den inte kan hitta resursen i det angivna paketet. Konstanten air.Localizer.RESOURCE_NOT_FOUND definierar strängen "resourceNotFound" . Händelsen har tre egenskaper: bundleName , resourceName och locale . bundleName -egenskapen är namnet på det paket där resursen inte hittas. resourceName -egenskapen är namnet på det paket där resursen inte hittas. locale -egenskapen är namnet på den språkinställning där resursen inte hittas.

Metoden getString() skickar en bundleNotFound -händelse när den inte kan hitta det angivna paketet. Konstanten air.Localizer.BUNDLE_NOT_FOUND definierar strängen "bundleNotFound" . Händelsen har två egenskaper: bundleName och locale . bundleName -egenskapen är namnet på det paket där resursen inte hittas. locale -egenskapen är namnet på den språkinställning där resursen inte hittas.

Metoden getString() utförs asynkront (och skickar händelserna resourceNotFound och bundleNotFound asynkront). Följande kod anger händelseavlyssnare för händelserna resourceNotFound och 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); 
}

Localizer-objektets getResourceBundle() -metod returnerar angivet paket för en viss språkinställning. Värdet som returneras av metoden är ett objekt med egenskaper som matchar nycklarna i paketet. (Om programmet inte hittar det angivna paketet returnerar metoden ett null -värde.)

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/>");

Metoden getResourceBundle() skickar en bundleNotFound -händelse om det angivna paketet inte kan hittas. Konstanten air.Localizer.BUNDLE_NOT_FOUND definierar strängen "bundleNotFound" . Händelsen har två egenskaper: bundleName och locale . bundleName -egenskapen är namnet på det paket där resursen inte hittas. locale -egenskapen är namnet på den språkinställning där resursen inte hittas.

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

Följande kod anropar till exempel metoden document.write() med hjälp av innehållet i about.html-filen för språkinställningen fr:

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

Metoden getFile() skickar en fileNotFound -händelse när den inte kan hitta en resurs i språkkedjan. Konstanten air.Localizer.FILE_NOT_FOUND definierar strängen "resourceNotFound" . Metoden getFile() utförs asynkront (och skickar händelsen fileNotFound asynkront). Händelsen har två egenskaper: fileName och locale . Egenskapen fileName är namnet på den fil som inte hittas. locale -egenskapen är namnet på den språkinställning där resursen inte hittas. Följande kod anger en händelseavlyssnare för den här händelsen:

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