Lokalizowanie treści HTML w strukturze lokalizowania AIR HTML

W celu użycia struktury lokalizowania należy skopiować do projektu plik AIRLocalizer.js. Następnie należy dołączyć go do głównego pliku HTML aplikacji, stosując znacznik script:

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

Następnie kod JavaScript może wywołać obiekt air.Localizer.localizer:

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

Klasa Localizer zawiera następujące właściwości statyczne:

Struktura lokalizowania HTML odczytuje zlokalizowane wersje ciągów znaków z plików lokalizacji. Plik lokalizacji jest kolekcją wartości opartych na kluczu, serializowanych w pliku tekstowym. Plik lokalizacji jest czasami określany jako pakunek.

Należy utworzyć podkatalog katalogu projektu aplikacji, o nazwie locale. (Można użyć innej nazwy, patrz Dostosowywanie ustawień obiektu Localizer HTML AIR). Ten katalog będzie zawierał pliki lokalizacji. Ten katalog jest określany jako katalog bundles.

Dla każdego ustawienia narodowego obsługiwanego przez aplikację należy utworzyć podkatalog katalogu bundles. Każdy podkatalog należy nazwać zgodnie z kodem ustawień narodowych. Na przykład: katalog języka francuskiego powinien mieć nazwę „fr”, a katalog języka angielskiego nazwę „en”. W celu zdefiniowania ustawień narodowych z kodem języka i kraju można użyć znaku podkreślenia (_). Np. katalog języka angielskiego dla USA powinien mieć nazwę „en_us”. (Zamiast znaku podkreślenia można użyć kreski, np. „en-us”. Struktura lokalizowania HTML obsługuje obydwa te znaki).

Do podkatalogu ustawień narodowych można dodać dowolną liczbę plików zasobów. Zwykle plik lokalizacji jest tworzony dla każdego języka (plik należy umieścić w katalogu dla tego języka). Struktura lokalizowania HTML zawiera metodę getFile(), która umożliwia odczyt treści pliku (patrz Pobieranie zasobów dla określonych ustawień narodowych..

Pliki z rozszerzeniem .properties są plikami właściwości lokalizacji. W tych plikach można zdefiniować wartości klucz-wartość dla ustawień narodowych. Plik właściwości definiuje jedną wartość ciągu znaków w każdej linii. Przykład: poniższy kod definiuje ciąg znaków "Hello in English." dla klucza o nazwie greeting:

greeting=Hello in English.

Plik właściwości definiujący poniższy tekst definiuje sześć par klucz-wartość:

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

Ten przykład prezentuje angielską wersję pliku właściwości, który może być zapisany w katalogu en.

Francuska wersja pliku właściwości zostanie umieszczona w katalogu fr:

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

Dla różnych typów informacji można zdefiniować wiele plików zasobów. Na przykład: plik legal.properties może zawierać szablon tekstu prawnego (np. informacje o prawach autorskich). Zasób taki można wykorzystywać wielokrotnie, w wielu aplikacjach. I podobnie — możliwe jest zdefiniowanie osobnych plików, które będą lokalizowały treść dla różnych części interfejsu użytkownika.

W celu zapewnienia obsługi wielu języków należy dla tych plików stosować kodowanie UTF-8.

Gdy aplikacja ładuje plik AIRLocalizer.js, sprawdza ustawienia narodowe zdefiniowane w aplikacji. Te ustawienia narodowe odpowiadają podkatalogom katalogu bundles (patrz Definiowanie pakunków zasobów). Ta lista dostępnych ustawień narodowych jest znana jako łańcuch ustawień narodowych. Plik AIRLocalizer.js automatycznie sortuje łańcuch ustawień narodowych na podstawie preferowanej kolejności zdefiniowanej w systemie operacyjnym. (Właściwość Capabilities.languages zawiera listę języków interfejsu użytkownika systemu operacyjnego, w preferowanej kolejności).

Dlatego jeśli aplikacja zdefiniuje zasoby dla ustawień narodowych „en”, „en_US” i „en_UK”, wówczas struktura obiektu Localizer AIR HTML sortuje odpowiednio łańcuch ustawień narodowych. Gdy aplikacja uruchomi system, który zgłasza „en” jako podstawowe ustawienie narodowe, wówczas łańcuch ustawień narodowych jest sterowany w taki sposób: ["en", "en_US", "en_UK"]. W takim przypadku aplikacja najpierw wyszukuje zasoby w pakunku „en”, a następnie w pakunku „en_US”.

Jeśli jednak system zgłasza „en-US” jako podstawowe ustawienie narodowe, wówczas sortowanie jest następujące: ["en_US", "en", en_UK"]. W takim przypadku aplikacja najpierw wyszukuje zasoby w pakunku „en_US”, a następnie w pakunku „en”.

Domyślnie aplikacja definiuje pierwsze ustawienie narodowe w łańcuchu lokalizacji jako domyślne ustawienie narodowe do użytku. Użytkownik może wybrać ustawienia narodowe po pierwszym uruchomieniu aplikacji. Następnie możliwe jest zapisanie wybranych ustawień w pliku preferencji i wykorzystanie tych ustawień narodowych przy kolejnym uruchamianiu aplikacji.

Aplikacja może korzystać z ciągów zasobów w dowolnych ustawieniach narodowych z łańcucha ustawień narodowych. Jeśli określone ustawienia narodowe nie zdefiniują ciągu znaków zasobu, aplikacja korzysta z kolejnego zgodnego ciągu zasobu dla innych ustawień narodowych zdefiniowanych w łańcuchu tych ustawień.

Łańcuch ustawień narodowych można dostosować poprzez wywołanie metody setLocaleChain() obiektu Localizer. Patrz Definiowanie łańcucha ustawień narodowych.

Element aplikacji może odwoływać się do wartości klucza w pliku właściwości lokalizacji. Na przykład: element title w poniższym przykładzie określa atrybut local_innerHTML. Struktura lokalizacji korzysta z tego atrybutu w celu wyszukania zlokalizowanej wartości. Domyślnie struktura wyszukuje nazwy atrybutów, które rozpoczynają się od znaków "local_". Struktura aktualizuje atrybuty z nazwami zgodnymi z tekstem za znakami "local_". W takim przypadku struktura ustawia atrybut innerHTML elementu title. Atrybut innerHTML korzysta z wartości zdefiniowanej dla klucza mainWindowTitle w domyślnym pliku właściwości (default.properties):

<title local_innerHTML="default.mainWindowTitle"/>

Jeśli bieżące ustawienia narodowe definiują wartość niezgodną, wówczas struktura obiektu Localizer wyszukuje pozostałą część łańcucha ustawień narodowych. Korzysta z następnych ustawień narodowych z łańcucha ustawień, dla którego zdefiniowano wartość.

W poniższym przykładzie tekst (atrybut innerHTML) elementu p korzysta z wartości klucza greeting zdefiniowanego w domyślnym pliku właściwości:

<p local_innerHTML="default.greeting" />

W poniższym przykładzie atrybut value (i wyświetlony tekst) elementu input korzysta z wartości klucza btnBlue z domyślnego pliku właściwości:

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

W celu zaktualizowania modelu DOM HTML w taki sposób, aby korzystał z ciągów znaków zdefiniowanych w bieżącym łańcuchu ustawień narodowych, należy wywołać metodę update() obiektu Localizer. Wywołanie metody update() powoduje, że obiekt Localizer analizuje model DOM i stosuje manipulowanie w miejscach, w których znajdzie atrybuty lokalizacji ("local_..."):

air.Localizer.localizer.update();

Możliwe jest zdefiniowanie wartości dla atrybutu (takiego jak „innerHTML”) oraz odpowiadającego mu atrybutu lokalizacji (np. „local_innerHTML”). W takim przypadku struktura lokalizowania zastępuje tylko wartość atrybutu, jeśli znajdzie zgodną wartość w łańcuchu lokalizacji. Przykład: poniższy element definiuje atrybuty value i local_value:

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

Możliwe jest również zaktualizowanie wybranego elementu modelu DOM. Informacje zawiera następna sekcja Aktualizowanie elementów DOM w celu użycia bieżących ustawień narodowych.

Domyślnie obiekt Localizer HTML AIR korzysta z"local_" jako z przedrostka dla atrybutów definiujących ustawienia lokalizacji dla elementu. Na przykład: domyślnie atrybut local_innerHTML definiuje nazwę pakunku i zasobu używaną dla wartości innerHTML elementu. Ponadto domyślnie atrybut local_value definiuje pakunek i nazwę zasobu dla atrybutu value elementu. Możliwe jest takie skonfigurowanie obiektu Localizer, aby korzystał on z przedrostka atrybutu innego niż "local_". Patrz Dostosowywanie ustawień obiektu Localizer HTML AIR.

Gdy obiekt Localizer zaktualizuje model DOM HTML, powoduje, że oznaczone elementy korzystają z wartości atrybutów na podstawie ciągów znaków zdefiniowanych w bieżącym łańcuchu ustawień narodowych. Aby obiekt localizer HTML zaktualizował model DOM HTML, należy wywołać metodę update() obiektu Localizer:

air.Localizer.localizer.update();

W celu zaktualizowania tylko określonego elementu DOM należy przekazać ten element jako parametr metody update(). Metoda update() zawiera tylko jeden parametr, parentNode, który jest opcjonalny. Po określeniu parametru parentNode definiuje on element DOM przeznaczony do zlokalizowania. Wywołanie metody update() i określenie parametru parentNode ustawia zlokalizowane wartości jako elementy podrzędne, które określają atrybuty lokalizacji.

Przykładem może być poniższy element 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>

W celu zaktualizowania elementu do użycia zlokalizowanych ciągów znaków zdefiniowanych w bieżącym łańcuchu ustawień narodowych należy użyć poniższego kodu JavaScript:

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

Jeśli wartość klucza nie zostanie znaleziona w łańcuchu ustawień narodowych, wówczas struktura lokalizacji ustawia wartość atrybutu na wartość atrybutu "local_". Przykład: załóżmy, że w poprzednim przykładzie struktura lokalizowania nie może znaleźć wartości dla klucza lblColors (w żadnym z plików default.properties w łańcuchu ustawień narodowych). W takim przypadku użyje "default.lblColors" jako wartości innerHTML. Użycie tej wartości oznacza (dla programisty) brak zasobów.

Metoda update() wywołuje zdarzenie resourceNotFound, nawet jeśli nie może znaleźć zasobu w łańcuchu ustawień narodowych. Stała air.Localizer.RESOURCE_NOT_FOUND definiuje ciąg znaków "resourceNotFound". Zdarzenie ma trzy właściwości: bundleName, resourceName i locale. Właściwość bundleName jest nazwą pakunku, w którym nie można znaleźć zasobu. Właściwość resourceName jest nazwą pakunku, w którym nie można znaleźć zasobu. Właściwość locale jest nazwą ustawień narodowych, w których nie można znaleźć zasobu.

Metoda update() wywołuje zdarzenie bundleNotFound, gdy nie może znaleźć określonego pakunku. Stała air.Localizer.BUNDLE_NOT_FOUND definiuje ciąg znaków "bundleNotFound". Zdarzenie ma dwie właściwości: bundleName i locale. Właściwość bundleName jest nazwą pakunku, w którym nie można znaleźć zasobu. Właściwość locale jest nazwą ustawień narodowych, w których nie można znaleźć zasobu.

Metoda update() działa w sposób asynchroniczny (i wywołuje asynchronicznie zdarzenia resourceNotFound i bundleNotFound). Poniższy kod ustawia detektory zdarzeń dla zdarzeń resourceNotFound i 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); 
}

Metoda setBundlesDirectory() obiektu Localizer umożliwia dostosowanie ścieżki katalogu bundles. Metoda setLocalAttributePrefix() obiektu Localizer umożliwia dostosowanie ścieżki katalogu bundles oraz dostosowanie wartości atrybutu używanego przez obiekt Localizer.

Domyślnie katalog bundles jest zdefiniowany jako podkatalog locale katalogu aplikacji. Za pomocą metody setBundlesDirectory() obiektu Localizer można określić inny katalog. Ta metoda przyjmuje jeden parametr, path, który jest ścieżką żądanego katalogu bundles, w postaci ciągu znaków. Parametr path może mieć jedną z następujących wartości:

Przykład: poniższy kod ustawia katalog bundles jako podkatalog languages katalogu zapisu aplikacji (nie jako katalog aplikacji):

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

Należy przekazać poprawną ścieżkę jako parametr path. W przeciwnym wypadku metoda zwróci wyjątek BundlePathNotFoundError. Właściwość name tego błędu to"BundlePathNotFoundError", a właściwość message określa niepoprawną ścieżkę.

Domyślnie obiekt Localizer HTML AIR korzysta z"local_" jako z przedrostka dla atrybutów definiujących ustawienia lokalizacji dla elementu. Na przykład: atrybut local_innerHTML definiuje nazwę pakunku i nazwę zasobu używaną dla wartości innerHTML poniższego elementu input:

<p local_innerHTML="default.greeting" />

Metoda setLocalAttributePrefix() obiektu Localizer umożliwia korzystanie z przedrostka atrybutu innego niż "local_". Ta statyczna metoda przyjmuje jeden parametr, który jest ciągiem znaków używanym jako przedrostek atrybutu. Przykład: poniższy kod ustawia strukturę lokalizowania w taki sposób, aby użyć „loc_” jako przedrostka aplikacji:

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

Istnieje możliwość dostosowania przedrostka atrybutu, z którego korzysta struktura lokalizowania. Możliwe jest dostosowanie przedrostka, jeśli wartość domyślna ("local_") powoduje konflikt z nazwą innego atrybutu używanego w kodzie. Podczas wywoływania tej metody należy stosować poprawne znaki dla atrybutów HTML. (Na przykład: wartość nie może zawierać znaku spacji).

Więcej informacji na temat korzystania z atrybutów lokalizacji w elementach HTML zawiera sekcja Aktualizowanie elementów DOM za pomocą treści zlokalizowanej.

Ustawienia katalogu bundles i przedrostka aplikacji nie są zachowywane między poszczególnymi sesjami aplikacji. Jeśli używany jest niestandardowy katalog bundles lub niestandardowe ustawienie przedrostka atrybutu, należy określić to ustawienie każdorazowo przy inicjowaniu aplikacji.

Domyślnie załadowanie kodu AIRLocalizer.js powoduje ustawienie domyślnego łańcucha ustawień narodowych. Ustawienia narodowe dostępne w katalogu bundles oraz ustawienia języka systemu operacyjnego definiują ten łańcuch ustawień narodowych. (Szczegółowe informacje zawiera sekcja Zarządzanie łańcuchami ustawień narodowych).

Łańcuch ustawień narodowych można zmodyfikować poprzez wywołanie statycznej metody setLocaleChain() obiektu Localizer. Na przykład: tę metodę można wywołać, jeśli użytkownik preferuje konkretny język. Metoda setLocaleChain() przyjmuje jeden parametr chain, który jest tablicą ustawień narodowych, np. ["fr_FR","fr","fr_CA"]. Kolejność ustawień narodowych w tablicy określa kolejność, w jakiej struktura wyszukuje zasoby (w kolejnych operacjach). Jeśli zasób nie zostanie znaleziony dla pierwszego ustawienia narodowego w łańcuchu, wówczas będzie przeszukiwać zasoby innego ustawienia narodowego. Jeśli argument chain nie jest dostępny, nie jest tablicą lub jest pustą tablicą, wówczas działanie funkcji kończy się niepowodzeniem i następuje wywołanie wyjątku IllegalArgumentsError.

Statyczna metoda getLocaleChain() obiektu Localizer zwraca tablicę zawierającą ustawienia narodowe z bieżącego łańcucha ustawień narodowych.

Poniższy kod odczytuje bieżący łańcuch ustawień narodowych i dodaje dwa francuskie ustawienia do początku łańcucha:

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

Metoda setLocaleChain() wywołuje zdarzenie "change", gdy zakończy aktualizowanie łańcucha ustawień narodowych. Stała air.Localizer.LOCALE_CHANGE definiuje ciąg znaków "change". Zdarzenie ma jedną właściwość localeChain — jest to tablica kodów ustawień narodowych w nowym łańcuchu tych ustawień. Poniższy kod ustawia detektor dla tego zdarzenia:

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

Statyczna właściwość air.Localizer.ultimateFallbackLocale reprezentuje ustawienia narodowe używane wówczas, gdy aplikacja nie obsługuje żadnych preferencji użytkownika. Wartością domyślną jest "en". Można również ustawić inne ustawienia narodowe, co prezentuje poniższy kod:

air.Localizer.ultimateFallbackLocale = "fr";

bundleName

resourceName

templateArgs

locale

Struktura lokalizowania może zaktualizować oznaczone atrybuty modelu DOM HTML. Jednak zlokalizowane ciągi znaków mogą być również używane na inne sposoby. Na przykład: ciąg znaków może być używany w niektórych dynamicznie wygenerowanych kodach HTML lub jako wartość parametru w wywołaniu funkcji. Przykład: poniższy kod wywołuje funkcję alert() z ciągiem znaków zdefiniowanym w zasobie error114 w domyślnym pliku właściwości ustawień narodowych fr_FR:

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

Metoda getString() wywołuje zdarzenie resourceNotFound, jeśli nie może znaleźć zasobu w określonym pakunku. Stała air.Localizer.RESOURCE_NOT_FOUND definiuje ciąg znaków "resourceNotFound". Zdarzenie ma trzy właściwości: bundleName, resourceName i locale. Właściwość bundleName jest nazwą pakunku, w którym nie można znaleźć zasobu. Właściwość resourceName jest nazwą pakunku, w którym nie można znaleźć zasobu. Właściwość locale jest nazwą ustawień narodowych, w których nie można znaleźć zasobu.

Metoda getString() wywołuje zdarzenie bundleNotFound, gdy nie może znaleźć określonego pakunku. Stała air.Localizer.BUNDLE_NOT_FOUND definiuje ciąg znaków "bundleNotFound". Zdarzenie ma dwie właściwości: bundleName i locale. Właściwość bundleName jest nazwą pakunku, w którym nie można znaleźć zasobu. Właściwość locale jest nazwą ustawień narodowych, w których nie można znaleźć zasobu.

Metoda getString() działa asynchronicznie (i wywołuje zdarzenia resourceNotFound oraz bundleNotFound w sposób asynchroniczny). Poniższy kod ustawia detektory zdarzeń dla zdarzeń resourceNotFound i 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); 
}

Metoda getResourceBundle() obiektu Localizer zwraca określony pakunek dla danego ustawienia narodowego. Wartość zwracana przez metodę jest obiektem z właściwościami zgodnymi z kluczami w pakunku. (Jeśli aplikacja nie może odnaleźć określonego pakunku, metoda zwraca wartość 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/>");

Metoda getResourceBundle() wywołuje zdarzenie bundleNotFound, gdy nie może znaleźć określonego pakunku. Stała air.Localizer.BUNDLE_NOT_FOUND definiuje ciąg znaków "bundleNotFound". Zdarzenie ma dwie właściwości: bundleName i locale. Właściwość bundleName jest nazwą pakunku, w którym nie można znaleźć zasobu. Właściwość locale jest nazwą ustawień narodowych, w których nie można znaleźć zasobu.

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

Na przykład: poniższy kod wywołuje metodę document.write() za pomocą treści pliku about.html ustawień narodowych fr:

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

Metoda getFile() wywołuje zdarzenie fileNotFound, nawet jeśli nie może znaleźć zasobu w łańcuchu ustawień narodowych. Stała air.Localizer.FILE_NOT_FOUND definiuje ciąg znaków "resourceNotFound". Metoda getFile() działa asynchronicznie (i wywołuje zdarzenie fileNotFound w sposób asynchroniczny). Zdarzenie ma dwie właściwości: fileName i locale. Właściwość fileName jest nazwą nieznalezionego pliku. Właściwość locale jest nazwą ustawień narodowych, w których nie można znaleźć zasobu. Poniższy kod ustawia detektor dla tego zdarzenia:

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