HTML-inhoud lokaliseren met het AIR HTML-lokalisatieframework

Als u het lokalisatieframework wilt gebruiken, kopieert u het bestand AIRLocalizer.js naar uw project. Neem het vervolgens met behulp van een scripttag op in het HTML-hoofdbestand van de toepassing.

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

JavaScript kan dan in het vervolg het air.Localizer.localizer -object oproepen:

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

De klasse Localizer bevat de volgende statische eigenschappen:

Met het element <supportedLanguages> in het descriptorbestand van de toepassing kunt u aangeven welke talen worden ondersteund door de toepassing. Dit element wordt alleen gebruikt door iOS-, Mac captive runtime- en Android-toepassingen. Het element wordt genegeerd door alle overige toepassingstypen.

Als u het element <supportedLanguages> niet opgeeft, worden standaard de volgende acties uitgevoerd door de pakketsoftware, afhankelijk van het toepassingstype:

Zie supportedLanguages voor meer informatie.

Het HTML-lokalisatieframework leest gelokaliseerde versies van tekenreeksen uit lokalisatie bestanden. Een lokalisatiebestand is een verzameling op sleutels gebaseerde waarden die serieel worden opgeslagen in een tekstbestand. Een lokalisatiebestand wordt ook wel een bundel genoemd.

Maak in de toepassingsprojectmap een submap met de naam locale. (U kunt ook een andere naam gebruiken. Zie AIR HTML Localizer-instellingen aanpassen .) Deze map zal de lokalisatiebestanden bevatten. Deze map wordt de bundelmap genoemd.

Voor iedere landinstelling die uw toepassing ondersteunt, maakt u een submap van de bundelmap. Geef iedere submap een naam die overeenkomt met de landinstellingscode. De map voor Frankrijk noemt u bijvoorbeeld “fr” en de map voor Engeland “en”. U kunt een onderstrepingsteken (_) gebruiken om een landinstelling te definiëren die een taal- en een landcode heeft. De map voor Amerikaans Engels noemt u bijvoorbeeld “en_us”. (U kunt ook een koppelteken gebruiken in plaats van een onderstrepingsteken, bijvoorbeeld “en-us”. Beide worden ondersteund door het HTML-lokalisatieframework.)

U kunt elk willekeurig aantal resourcebestanden toevoegen aan een submap locale. In het algemeen maakt u een lokalisatiebestand voor iedere taal (en zet u dat bestand in de map voor die taal). Het HTML-lokalisatieframework biedt de methode getFile() , waarmee u de inhoud van een bestand kunt lezen (zie Resources ophalen voor een specifieke landinstelling .

Bestanden met de extensie .properties staan bekend als lokalisatie-eigenschappenbestanden. U kunt deze gebruiken om sleutelwaardeparen voor een landinstelling te definiëren. In een eigenschappenbestand wordt op iedere regel één tekenreekswaarde gedefinieerd. Het volgende definieert bijvoorbeeld de tekenreekswaarde "Hello in English." voor de sleute greeting :

greeting=Hello in English.

Een eigenschappenbestand met de volgende tekst definieert zes sleutelwaardeparen:

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

Dit voorbeeld toont een Engelse versie van het eigenschappenbestand, die moet worden opgeslagen in de map en.

Een Franse versie van dit eigenschappenbestand wordt opgeslagen in de map fr:

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

U kunt meerdere resourcebestanden definiëren voor verschillende soorten informatie. Zo zou het bestand legal.properties juridische standaardteksten met bijvoorbeeld copyrightgegevens kunnen bevatten. U kunt deze bron in meerdere toepassingen hergebruiken. Ook kunt u eventueel afzonderlijke bestanden definiëren die gelokaliseerde inhoud definiëren voor verschillende onderdelen van de gebruikersinterface.

Gebruik UTF-8-codering voor deze bestanden voor de ondersteuning van meerdere talen.

Wanneer uw toepassing het bestand AIRLocalizer.js laadt, onderzoekt het bestand de landinstellingen die in de toepassing zijn gedefinieerd. Deze landinstellingen corresponderen met de submappen van de bundelmap (zie Resourcebundels definiëren ). Dit is de keten van landinstellingen . Het bestand AIRLocalizer.js sorteert automatisch de keten van landinstellingen op basis van de voorkeursvolgorde die is gedefinieerd in het besturingssysteem. (De eigenschap Capabilities.languages geeft een lijst weer van de gebruikersinterfacetalen van het besturingssysteem, op volgorde van voorkeur.)

Als dus een toepassing resources definieert voor de landinstellingen "en", "en_US" en "en_UK", sorteert het AIR HTML Localizer-framework de keten van landinstellingen op de correcte manier. Wanneer een toepassing wordt gestart op een systeem waarop "en" wordt gerapporteerd als de primaire landcode, wordt de keten van landinstellingen gesorteerd als ["en", "en_US", "en_UK"] . In dat geval zoekt de toepassing eerst naar resources in de bundel "en", en vervolgens in de bundel "en_US".

Als het systeem echter "en-US" rapporteert als de primaire landinstelling, wordt bij de sortering gebruikgemaakt van ["en_US", "en", en_UK"] . In dat geval zoekt de toepassing eerst naar resources in de bundel "en_US", en vervolgens in de bundel "en".

Standaard definieert de toepassing de eerste landinstelling in de keten als de standaard landinstelling die moet worden gebruikt. U kunt de gebruiker vragen een landinstelling te selecteren wanneer deze de toepassing voor het eerst uitvoert. Vervolgens kunt u ervoor kiezen de selectie op te slaan in een voorkeurenbestand en die landinstelling te gebruiken wanneer de toepassing in het vervolg wordt opgestart.

Uw toepassing kan resourcetekenreeksen gebruiken in een willekeurige landinstelling van de keten. Als een bepaalde landinstelling geen resourcetekenreeks definieert, gebruikt de toepassing de volgende overeenkomende resourcetekenreeks voor andere landinstellingen die is gedefinieerd in de keten.

U kunt de keten van landinstellingen aanpassen door de methode setLocaleChain() van het Localizer-object op te roepen. Zie De keten van landinstellingen definiëren .

Een element in de toepassing kan verwijzen naar een sleutelwaarde in een lokalisatie-eigenschappenbestand. Zo geeft het element title in het volgende voorbeeld het kenmerk local_innerHTML op. Het lokalisatieframework gebruikt dit kenmerk om een gelokaliseerde waarde op te zoeken. Standaard zoekt het framework naar kenmerknamen die beginnen met "local_" . Het framework werkt de kenmerken bij die een naam hebben die overeenkomt met de tekst na "local_" . In dit geval stelt het framework het kenmerk innerHTML van het element title in. Het kenmerk innerHTML gebruikt de waarde die is gedefinieerd voor de sleutel mainWindowTitle in het standaard eigenschappenbestand (default.properties):

<title local_innerHTML="default.mainWindowTitle"/>

Als de huidige landinstelling geen overeenkomende waarde definieert, doorzoekt het Localizer-framework de rest van de keten van landinstellingen. De volgende landinstelling in de keten waarvoor een waarde is gedefinieerd, wordt dan gebruikt.

In het volgende voorbeeld gebruikt de tekst (kenmerk innerHTML ) van het element p de waarde van de sleutel greeting die is gedefinieerd in het standaard eigenschappenbestand:

<p local_innerHTML="default.greeting" />

In het volgende voorbeeld gebruikt het kenmerk value (en weergegeven tekst) van het element input de waarde van de sleutel btnBlue die is gedefinieerd in het standaard eigenschappenbestand:

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

Om het HTML DOM zodanig bij te werken dat de tekenreeksen worden gebruikt die zijn gedefinieerd in de huidige keten van landinstellingen, roept u de methode update() van het Localizer-object op. Het oproepen van de methode update() zorgt ervoor dat het Localizer-object het DOM parseert en manipulaties toepast waar het lokalisatiekenmerken ( "local_..." ) aantreft:

air.Localizer.localizer.update();

U kunt waarden definiëren voor zowel een kenmerk (zoals "innerHTML") als het corresponderende lokalisatiekenmerk (zoals "local_innerHTML"). In dat geval overschrijft het Localizer-framework alleen de waarde van het kenmerk als er een corresponderende waarde wordt aangetroffen in de lokalisatieketen. Het volgende element definieert bijvoorbeeld zowel kenmerken van het type value als van het type local_value :

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

U kunt ook alleen een specifiek DOM-element bijwerken. Zie de volgende sectie, DOM-elementen bijwerken voor het gebruik van de huidige landinstelling .

Standaard gebruikt de AIR HTML Localizer "local_" als voorvoegsel voor kenmerken die lokalisatie-instellingen voor een element definiëren. Standaard definieert bijvoorbeeld het kenmerk local_innerHTML de bundel- en resourcenaam die worden gebruikt voor de waarde innerHTML van een element. Verder definieert het kenmerk local_value standaard de bundel- en resourcenaam die worden gebruikt voor het kenmerk value van een element. U kunt de Localizer zodanig configureren dat een ander kenmerkvoorvoegsel wordt gebruikt dan "local_" . Zie AIR HTML Localizer-instellingen aanpassen .

Wanneer het Localizer-object het HTML DOM bijwerkt, maken gemarkeerde elementen gebruik van kenmerkwaarden op basis van tekenreeksen die zijn gedefinieerd in de huidige keten van landinstellingen. Als de HTML Localizer het HTML DOM moet bijwerken, roept u de methode update() van het Localizer -object op:

air.Localizer.localizer.update();

Als u alleen een specifiek DOM-element wilt bijwerken, geeft u dat element als parameter door aan de methode update() . De methode update() heeft maar één parameter, parentNode , die optioneel is. Wanneer de parameter parentNode wordt opgegeven, definieert deze het DOM-element dat moet worden gelokaliseerd. Als de methode update() wordt opgeroepen en de parameter parentNode wordt opgegeven, worden gelokaliseerde waarden ingesteld voor alle onderliggende elementen die lokalisatiekenmerken opgeven.

Kijk bijvoorbeeld naar het volgende 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>

Als u dit element wilt bijwerken zodat gelokaliseerde tekenreeksen worden gebruikt, gebruikt u de volgende JavaScript-code:

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

Als een sleutelwaarde niet wordt gevonden in de keten van landinstellingen, stelt het Localizer-framework de kenmerkwaarde in op de waarde van het kenmerk "local_" . Stel dat in het vorige voorbeeld het Localizer-framework in geen enkel standaard eigenschappenbestand in de keten van tekenreeksen een waarde kan vinden voor de sleutel lblColors . In dat geval wordt "default.lblColors" gebruikt als waarde voor innerHTML . Het gebruik van deze waarde geeft (voor de ontwikkelaar) aan dat er resources ontbreken.

De methode update() verzendt de gebeurtenis resourceNotFound wanneer een resource niet kan worden gevonden in de keten van landinstellingen. De constante air.Localizer.RESOURCE_NOT_FOUND definieert de tekenreeks "resourceNotFound" . De gebeurtenis heeft drie eigenschappen: bundleName , resourceName en locale . De eigenschap bundleName is de naam van de bundel waarin de resource niet is gevonden. De eigenschap resourceName is de resource die niet is gevonden. De eigenschap locale is de naam van de landinstelling waarin de resource niet is gevonden.

De methode update() verzendt de gebeurtenis bundleNotFound wanneer de opgegeven bundel niet kan worden gevonden. De constante air.Localizer.BUNDLE_NOT_FOUND definieert de tekenreeks "bundleNotFound" . De gebeurtenis heeft twee eigenschappen: bundleName en locale . De eigenschap bundleName is de naam van de bundel waarin de resource niet is gevonden. De eigenschap locale is de naam van de landinstelling waarin de resource niet is gevonden.

De methode update() werkt asynchroon (en verzendt de gebeurtenissen resourceNotFound en bundleNotFound asynchroon). Met de volgende code stelt u gebeurtenislisteners in voor de gebeurtenissen resourceNotFound en 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); 
}

Met de methode setBundlesDirectory() van het Localizer-object kunt u het pad van de bundelmap aanpassen. Met de methode setLocalAttributePrefix() van het Localizer-object kunt u het pad van de bundelmap aanpassen, evenals de waarde van het kenmerk dat wordt gebruikt door de Localizer.

Het standaard bundelpad wordt gedefinieerd als de submap met landinstellingen van de toepassingsmap. U kunt een andere map opgeven door de methode setBundlesDirectory() van het Localizer-object op te roepen. Deze methode maakt gebruik van één parameter, path . Dit is het pad naar de gewenste bundelmap. Het is een tekenreeks. De parameter path kan een van de volgende waarden hebben:

Met de volgende code stelt u bijvoorbeeld de bundelmap in op de submap languages van de opslagmap van de toepassing (en niet de toepassingsmap):

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

Geef een geldig pad op voor de parameter path . Bij een ongeldig pad wordt de uitzondering BundlePathNotFoundError gegenereerd. Deze fout heeft "BundlePathNotFoundError" voor de eigenschap name . De eigenschap message geeft het ongeldige pad aan.

Standaard gebruikt de AIR HTML Localizer "local_" als voorvoegsel voor kenmerken die lokalisatie-instellingen voor een element definiëren. Het kenmerk local_innerHTML definieert bijvoorbeeld de bundel- en resourcenaam die worden gebruikt voor de waarde innerHTML van het volgende input -element:

<p local_innerHTML="default.greeting" />

Met de methode setLocalAttributePrefix() van het Localizer-object kunt u een ander kenmerkvoorvoegsel gebruiken dan "local_" . Deze statische methode maakt gebruik van één parameter, die bestaat uit de tekenreeks die u wilt gebruiken als kenmerkvoorvoegsel. Met de volgende code stelt u het Localizer-framework zo in dat "loc_" wordt gebruikt als kenmerkvoorvoegsel:

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

U kunt het kenmerkvoorvoegsel aanpassen dat door het Localizer-framework wordt gebruikt. U kunt het voorvoegsel bijvoorbeeld aanpassen als de standaardwaarde ( "local_" ) een conflict veroorzaakt met de naam van een ander kenmerk dat door uw code wordt gebruikt. Gebruik bij het oproepen van deze methode alleen geldige tekens voor HTML-kenmerken. (De waarde mag bijvoorbeeld geen spatie bevatten.)

Zie DOM-elementen bijwerken met gelokaliseerde inhoud voor meer informatie over het gebruik van lokalisatiekenmerken in HTML-elementen.

De instellingen voor bundelmap en kenmerkvoorvoegsel blijven niet bewaard als een nieuwe sessie van de toepassing wordt opgestart. Als u een aangepaste instelling voor bundelmap of kenmerkvoorvoegsel gebruikt, moet u deze opnieuw instellen iedere keer dat de toepassing opnieuw wordt opgestart.

Wanneer u de AIRLocalizer.js-code laadt, wordt standaard de standaardketen voor landinstellingen ingesteld. Deze keten van landinstellingen wordt gedefinieerd door de landinstellingen die beschikbaar zijn in de bundelmap en de taalinstellingen van het besturingssysteem. (Zie Landinstellingen beheren voor meer informatie.)

U kunt de keten van landinstellingen wijzigen door de statische methode setLocaleChain( ) van het Localizer-object op te roepen. U kunt deze methode bijvoorbeeld oproepen als de gebruiker een voorkeur voor een bepaalde taal opgeeft. De methode setLocaleChain( ) maakt gebruik van één parameter, chain , die bestaat uit een array van landinstellingen, bijvoorbeeld ["fr_FR","fr","fr_CA"] . De volgorde van de landinstellingen in deze array bepaalt de volgorde waarin het framework (in daaropvolgende bewerkingen) zoekt naar resources. Als een resource niet wordt aangetroffen in de eerste landinstelling van de keten, wordt verder gezocht in de resources van de andere landinstellingen. Als het argument chain ontbreekt, geen array is of een lege array is, treedt er een fout op en wordt de uitzondering IllegalArgumentsError gegenereerd.

De statische methode getLocaleChain() van het Localizer-object retourneert een array met alle landinstellingen in de huidige keten.

De volgende code leest de huidige keten van landinstellingen en voegt boven aan de keten twee Franse landinstellingen toe:

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

De methode setLocaleChain() verzendt de gebeurtenis "change" wanneer de keten van landinstellingen wordt bijgewerkt. De constante air.Localizer.LOCALE_CHANGE definieert de tekenreeks "change" . Deze gebeurtenis heeft één eigenschap, localeChain , een array van landinstellingscodes in de nieuwe keten van landinstellingen. De volgende code stelt een gebeurtenislistener in voor deze gebeurtenis:

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

De statische eigenschap air.Localizer.ultimateFallbackLocale vertegenwoordigt de landinstelling die wordt gebruikt wanneer de toepassing geen gebruikersvoorkeuren ondersteunt. De standaardwaarde is "en" . Met de volgende code kunt u een andere landinstelling instellen:

air.Localizer.ultimateFallbackLocale = "fr";

bundleName

resourceName

templateArgs

locale

Het Localizer-framework kan gemarkeerde HTML DOM-kenmerken bijwerken. U kunt gelokaliseerde tekenreeksen echter ook op andere manieren gebruiken. U kunt een tekenreeks bijvoorbeeld gebruiken in dynamisch gegenereerde HTML, of als parameterwaarde in een functieoproep. De volgende code roept bijvoorbeeld de functie alert() op met de tekenreeks die is gedefinieerd in de resource error114 in het standaard eigenschappenbestand van de landinstelling fr_FR:

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

De methode getString() verzendt de gebeurtenis resourceNotFound wanneer de resource niet kan worden gevonden in de opgegeven bundel. De constante air.Localizer.RESOURCE_NOT_FOUND definieert de tekenreeks "resourceNotFound" . De gebeurtenis heeft drie eigenschappen: bundleName , resourceName en locale . De eigenschap bundleName is de naam van de bundel waarin de resource niet is gevonden. De eigenschap resourceName is de resource die niet is gevonden. De eigenschap locale is de naam van de landinstelling waarin de resource niet is gevonden.

De methode getString() verzendt de gebeurtenis bundleNotFound wanneer de opgegeven bundel niet kan worden gevonden. De constante air.Localizer.BUNDLE_NOT_FOUND definieert de tekenreeks "bundleNotFound" . De gebeurtenis heeft twee eigenschappen: bundleName en locale . De eigenschap bundleName is de naam van de bundel waarin de resource niet is gevonden. De eigenschap locale is de naam van de landinstelling waarin de resource niet is gevonden.

De methode getString() wordt asynchroon uitgevoerd (en verzendt de gebeurtenissen resourceNotFound en bundleNotFound asynchroon). Met de volgende code stelt u gebeurtenislisteners in voor de gebeurtenissen resourceNotFound en 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); 
}

De methode getResourceBundle() van het Localizer-object retourneert een specifieke bundel voor een bepaalde landinstelling. De geretourneerde waarde van de methode is een object waarvan de eigenschappen overeenstemmen met de sleutels in de bundel. (Als de toepassing de gespecificeerde bundel niet kan vinden, geeft deze methode de waarde null als resultaat.)

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

De methode getResourceBundle() verzendt de gebeurtenis bundleNotFound wanneer de opgegeven bundel niet kan worden gevonden. De constante air.Localizer.BUNDLE_NOT_FOUND definieert de tekenreeks "bundleNotFound" . De gebeurtenis heeft twee eigenschappen: bundleName en locale . De eigenschap bundleName is de naam van de bundel waarin de resource niet is gevonden. De eigenschap locale is de naam van de landinstelling waarin de resource niet is gevonden.

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

De volgende code roept bijvoorbeeld de methode document.write() op met gebruikmaking van de inhoud van het bestand about.html van de landinstelling fr:

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

De methode getFile() verzendt de gebeurtenis fileNotFound wanneer er geen resource kan worden gevonden in de keten van landinstellingen. De constante air.Localizer.FILE_NOT_FOUND definieert de tekenreeks "resourceNotFound" . De methode getFile() werkt asynchroon (en verzendt de gebeurtenis fileNotFound asynchroon). De gebeurtenis heeft twee eigenschappen: fileName en locale . De eigenschap fileName is de naam van het bestand dat niet kan worden gevonden. De eigenschap locale is de naam van de landinstelling waarin de resource niet is gevonden. De volgende code stelt een gebeurtenislistener in voor deze gebeurtenis:

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