HTML içeriğini AIR HTML yerelleştirme çerçevesiyle yerelleştirme

Yerelleştirme çerçevesini kullanmak için, AIRLocalizer.js dosyasını projenize kopyalayın. Ardından bu dosyayı bir komut dosyası etiketi kullanarak uygulamanın ana HTML dosyasına ekleyin:

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

Sonraki JavaScript air.Localizer.localizer nesnesini çağırabilir:

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

Localizer sınıfı aşağıdaki statik özellikleri içerir:

Uygulama tarafından desteklenen dilleri tanımlamak için uygulama tanımlayıcı dosyasındaki <supportedLanguages> öğesini kullanın. Bu öğe yalnızca iOS, Mac sabit çalışma zamanı ve Android uygulamaları tarafından kullanılır ve diğer tüm uygulama türleri tarafından yoksayılır.

<supportedLanguages> öğesini belirtmezseniz, varsayılan olarak paketleyici, uygulama türüne bağlı olarak aşağıdaki eylemleri gerçekleştirir:

Daha fazla bilgi için bkz. supportedLanguages .

HTML yerelleştirme çerçevesi yerelleştirme dosyalarından dizelerin yerelleştirilmiş sürümlerini okur. Yerelleştirme dosyası, bir metin dosyasında serileştirilmiş anahtar tabanlı değerlerin bir koleksiyonudur. Yerelleştirme dosyasına bazen paket de denir.

Uygulama projesi dizininizin locale (yerel ayar) adlı bir alt dizinini oluşturun. (Farklı bir ad da kullanabilirsiniz, bkz. AIR HTML Localizer ayarlarını özelleştirme ). Bu dizin yerelleştirme dosyalarını içerir. Bu dizin paketler dizini olarak bilinir.

Uygulamanızın desteklediği her yerel ayar için, paketler dizininin bir alt dizinini oluşturun. Her alt dizini yerel ayar koduyla eşleşecek şekilde adlandırın. Örneğin French (Fransız) alt dizinini “fr” ve English (İngiliz) alt dizinini “en” olarak adlandırın. Dil ve ülke kodu olan bir yerel ayarı tanımlamak için alt çizgi (_) karakterini kullanabilirsiniz. Örneğin U.S. English (Amerikan İngilizcesi) dizinini “en_us” olarak adlandırın. (Alternatif olarak alt çizgi yerine, “en-us” örneğinde olduğu gibi tire de kullanabilirsiniz. HTML yerelleştirme çerçevesi her ikisini de destekler.)

Bir yerel ayar alt dizinine istediğiniz sayıda kaynak dosya ekleyebilirsiniz. Genellikle her dil için bir yerelleştirme dosyası oluşturursunuz (ve dosyayı ilgili dilin dizinine yerleştirirsiniz). HTML yerelleştirme çerçevesi, bir dosyanın içeriğini okumanızı sağlayan bir getFile() yöntemi içerir (bkz. Belirli yerel ayarlar için kaynak alma .

.properties dosya uzantısına sahip dosyalar, yerelleştirme özellik dosyaları olarak bilinir. Bir yerel ayar için anahtar değer çiftleri tanımlamak üzere onları kullanabilirsiniz. Özellikler dosyası, her satırda bir dize değeri tanımlar. Örneğin aşağıdaki örnekte dize değeri "Hello in English." greeting adlı anahtar için tanımlanır:

greeting=Hello in English.

Aşağıdaki metni içeren bir özellikler dosyası, altı anahtar değer çifti tanımlar:

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

Bu örnek özellikler dosyasının, en dizininde saklanacak olan İngilizce sürümünü gösterir.

Bu Özellikler dosyasının Fransızca sürümü fr dizinine konur.

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

Farklı bilgi türleri için birden fazla kaynak dosya tanımlayabilirsiniz. Örneğin bir legal.properties dosyası yasal standart metin (telif hakkı bilgileri gibi) içerebilir. Bu kaynağı bir çok uygulamada tekrardan kullanabilirsiniz. Benzer şekilde, kullanıcı arabiriminin farklı kısımları için yerelleştirilmiş içerik tanımlayan ayrı dosyalar tanımlayabilirsiniz.

Bu dosyalarda, birden fazla dili desteklemek için UTF-8 kodlaması kullanın.

Uygulamanız AIRLocalizer.js dosyasını yüklediğinde, uygulamanızda tanımlı olan yerel ayarları inceler. Bu yerel ayarlar, paketler dizininin alt dizinlerine karşılık gelir (bkz. Kaynak paketlerini tanımlama ). Kullanılabilir yerel ayarların listesi yerel ayar zinciri olarak bilinir. AIRLocalizer.js dosyası yerel ayar zincirini, işletim sistemi ayarları tarafından tanımlanmış tercih edilen sırayı temel alarak sıralar. ( Capabilities.languages özelliği, işletim sistemi kullanıcı arabirimi dillerini tercih edilen sırada listeler.)

Dolayısıyla bir uygulama "en", "en_US" ve "en_UK" yerel ayarları için kaynak tanımlarsa, AIR HTML Localizer çerçevesi yerel ayar zincirini uygun şekilde sıralar. Bir uygulama "en" öğesini birincil yerel ayar olarak bildiren bir sistemde başladığında, yerel ayar zinciri ["en", "en_US", "en_UK"] şeklinde sıralanır. Bu durumda uygulama kaynakları önce "en" paketinde, sonra "en_US" paketinde arar.

Ancak sistem "en-US" öğesini birincil yerel ayar olarak bildirirse, sıralama ["en_US", "en", en_UK"] şeklindedir. Bu durumda uygulama kaynakları önce "en_US" paketinde, sonra "en" paketinde arar.

Varsayılan olarak uygulama yerel ayar zincirindeki ilk yerel ayarı, kullanılacak varsayılan yerel ayar olarak tanımlar. Uygulamayı ilk kez çalıştırdıktan sonra kullanıcıdan bir yerel ayar seçmesini isteyebilirsiniz. Ardından seçimi bir tercihler dosyasında saklamayı ve uygulamanın bir sonraki başlatılışında bu yerel ayarı kullanmayı seçebilirsiniz.

Uygulamanız kaynak dizeleri yerel ayar zincirindeki herhangi bir yerel ayarda kullanabilir. Belirli bir yerel ayar bir kaynak dize tanımlamazsa, uygulama, yerel ayar zincirinde tanımlı olan diğer yerel ayarlar için bir sonraki eşleşen kaynak dizeyi kullanır.

Localizer nesnesinin setLocaleChain() yöntemini çağırarak yerel ayar zincirini özelleştirebilirsiniz. Bkz. Yerel ayar zincirini tanımlama .

Uygulamadaki bir öğe, yerelleştirme özellikleri dosyasındaki bir anahtar değere başvurabilir. Örneğin aşağıdaki örnekte bulunan title öğesi, bir local_innerHTML niteliğini belirtir. Yerelleştirme çerçevesi, yerelleştirilen bir değeri aramak için bu niteliği kullanır. Çerçeve varsayılan olarak "local_" ile başlayan nitelik adları arar. Çerçeve, "local_" ifadesinin arkasından gelen metinle eşleşen adlara sahip nitelikleri günceller. Bu durumda çerçeve, title öğesinin innerHTML niteliğini ayarlar. innerHTML niteliği, varsayılan özellikler dosyasındaki (default.properties) mainWindowTitle anahtarı için tanımlı olan değeri kullanır:

<title local_innerHTML="default.mainWindowTitle"/>

Geçerli yerel ayar eşleşen bir değer tanımlamazsa, yerelleştirici çerçevesi yerel ayar zincirinin kalanını arar. Yerel ayar zincirinde bir değerin tanımlı olduğu bir sonraki yerel ayarı kullanır.

Aşağıdaki örnekte p öğesinin metni ( innerHTML niteliği), varsayılan özellikler dosyasında tanımlanan greeting anahtarının değerini kullanır:

<p local_innerHTML="default.greeting" />

Aşağıdaki örnekte, input öğesinin değer niteliği (ve görüntülenen metin), varsayılan özellikler dosyasında tanımlanan btnBlue anahtarının değerini kullanır:

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

HTML DOM'yi geçerli yerel ayar zincirinde tanımlı olan dizeleri kullanmak üzere güncellemek için, Localizer nesnesinin update() yöntemini çağırın. update() yöntemini çağırmak Localizer nesnesinin DOM'yi ayrıştırmasına ve yerelleştirme ( "local_..." ) niteliklerini bulduğu konumda işlemeleri uygulamasına neden olur:

air.Localizer.localizer.update();

Hem bir nitelik ("innerHTML" gibi) hem de karşılık gelen yerelleştirme niteliği için ("local_innerHTML" gibi) değer tanımlayabilirsiniz. Bu durumda yerelleştirme çerçevesi, yerelleştirme zincirinde karşılık gelen bir değer bulursa, yalnızca nitelik değerinin üzerine yazar. Örneğin aşağıdaki öğe hem value hem de local_value niteliklerini tanımlar:

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

Yalnızca belirli bir DOM öğesini de güncelleyebilirsiniz. Bir sonraki bölüm olan DOM öğelerini geçerli yerel ayarı kullanmak üzere güncelleme bölümüne bakın.

AIR HTML Localizer "local_" ifadesini varsayılan olarak bir öğenin yerelleştirme ayarlarını tanımlayan nitelikler için önek olarak kullanır. Örneğin local_innerHTML niteliği varsayılan olarak bir öğenin innerHTML değeri için kullanılan paket ve kaynak adını tanımlar. Ayrıca local_value niteliği varsayılan olarak bir öğenin value niteliği için kullanılan paket ve kaynak adını da tanımlar. Localizer öğesini "local_" dışında bir nitelik öneki kullanmak üzere yapılandırabilirsiniz. Bkz. AIR HTML Localizer ayarlarını özelleştirme .

Localizer nesnesi HTML DOM'yi güncellediğinde, işaretli öğelerin, geçerli yerel ayar zincirinde tanımlı dizelere dayalı olan nitelik değerlerini kullanmasına neden olur. HTML yerelleştiricisinin HTML DOM'yi güncellemesi için, Localizer nesnesinin update() yöntemini çağırın:

air.Localizer.localizer.update();

Yalnızca belirtilen bir DOM öğesini güncellemek için, update() yöntemine bir parametre olarak iletin. update() yöntemi yalnızca parentNode adlı, isteğe bağlı bir parametreye sahiptir. parentNode parametresi belirtildiğinde, yerelleştirilecek DOM öğesini tanımlar. update() yöntemini çağırmak ve bir parentNode parametresi belirtmek, yerelleştirme niteliklerini belirten tüm alt öğeler için yerelleştirilen değerleri ayarlar.

Örneğin aşağıdaki div öğesine bakın:

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

Bu öğeyi geçerli yerel ayar zincirinde tanımlı yerelleştirilmiş dizeleri kullanmak üzere güncellemek için, aşağıdaki JavaScript kodunu kullanın:

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

Yerel ayar zincirinde bir anahtar değer bulunmazsa, yerelleştirme çerçevesi nitelik değerini "local_" niteliğinin değerine ayarlar. Örneğin bir önceki örnekte, yerelleştirme çerçevesinin lblColors anahtarı için bir değer bulamadığını varsayın (yerel ayar zincirindeki hiçbir default.properties dosyasında). Bu durumda innerHTML değeri olarak "default.lblColors" öğesini kullanır. Bu değeri kullanmak eksik kaynaklar olduğunu (geliştiriciye) belirtir.

update() yöntemi, yerel ayar zincirinde kaynak bulamadığında bir resourceNotFound olayı gönderir. air.Localizer.RESOURCE_NOT_FOUND sabiti, "resourceNotFound" dizesini tanımlar. Olayın üç özelliği vardır: bundleName , resourceName ve locale . bundleName özelliği, kaynak bulunamayan paketin adıdır. resourceName özelliği, kaynak bulunamayan paketin adıdır. locale özelliği, kaynak bulunamayan yerel ayarın adıdır.

update() yöntemi, belirtilen paketi bulamadığında bir bundleNotFound olayı gönderir. air.Localizer.BUNDLE_NOT_FOUND sabiti, "bundleNotFound" dizesini tanımlar. Olayın iki özelliği vardır: bundleName ve locale . bundleName özelliği, kaynak bulunamayan paketin adıdır. locale özelliği, kaynak bulunamayan yerel ayarın adıdır.

update() yöntemi senkronize olmayan bir şekilde çalışır (ve resourceNotFound ve bundleNotFound olaylarını senkronize olmayan bir şekilde gönderir). Aşağıdaki kod resourceNotFound ve bundleNotFound olayları için olay dinleyicilerini ayarlar:

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

Localizer nesnesinin setBundlesDirectory() yöntemi sayesinde paketlerin dizin yolunu özelleştirebilirsiniz. Localizer nesnesinin setLocalAttributePrefix() yöntemi sayesinde paketlerin dizin yolunu ve Localizer tarafından kullanılan nitelik değerini özelleştirebilirsiniz.

Varsayılan paketler dizini, uygulama dizininin yerel ayar alt dizini olarak tanımlanır. Localizer nesnesinin setBundlesDirectory() yöntemini çağırarak başka bir dizin de belirtebilirsiniz. Bu yöntem için path adlı bir parametre gereklidir, bu parametre, bir dize olarak istenilen paketler dizinine giden yoldur. path parametresinin değeri şunlardan biri olabilir:

Örneğin aşağıdaki kod paketler dizinini, uygulama depolama dizininin (uygulama dizininin değil) diller alt dizinine ayarlar:

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

path parametresi olarak geçerli bir yol iletin. Aksi takdirde yöntem bir BundlePathNotFoundError istisnası atar. Hatanın name özelliği "BundlePathNotFoundError" öğesidir ve message özelliği geçersiz yolu belirtir.

AIR HTML Localizer "local_" ifadesini varsayılan olarak bir öğenin yerelleştirme ayarlarını tanımlayan nitelikler için önek olarak kullanır. Örneğin local_innerHTML niteliği, aşağıdaki input öğesinin innerHTML değeri için kullanılan paket ve kaynak adını tanımlar:

<p local_innerHTML="default.greeting" />

Localizer nesnesinin setLocalAttributePrefix() yöntemi sayesinde, "local_" dışında bir nitelik öneki kullanabilirsiniz. Bu statik yöntem için, nitelik öneki olarak kullanmak istediğiniz dize olan bir parametre gereklidir. Örneğin aşağıdaki kod, yerelleştirme çerçevesini, "loc_" ifadesini nitelik öneki olarak kullanmak üzere ayarlar:

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

Yerelleştirme çerçevesinin kullandığı nitelik önekini özelleştirebilirsiniz. Varsayılan değer ( "local_" ), kodunuzun kullandığı başka bir nitelikle çakışıyorsa, öneki özelleştirmek isteyebilirsiniz. Bu yöntemi çağırırken, HTML nitelikleri için geçerli karakterler kullandığınızdan emin olun. (Örneğin değer boşluk karakteri içermemelidir.)

Yerelleştirme niteliklerini HTML öğelerinde kullanma hakkında bilgi için, bkz. DOM öğelerini yerelleştirilmiş içerikle güncelleme .

Paketler dizini ve nitelik öneki ayarları, farklı uygulama oturumları arasında kalıcı değildir. Özel paketler dizini veya nitelik öneki ayarı kullanıyorsanız, uygulama her başladığında ayarı yeniden yaptığınızdan emin olun.

AIRLocalizer.js kodunu yüklediğinizde, varsayılan olarak varsayılan yerel ayar zincirini ayarlar. Paketler dizininde ve işletim sistemi dil ayarlarında bulunan yerel ayarlar, bu yerel ayar zincirini tanımlar. (Ayrıntılar için bkz. Yerel ayar zincirlerini yönetme .)

Localizer nesnesinin statik setLocaleChain( ) yöntemini çağırarak, yerel ayar zincirini değiştirebilirsiniz. Örneğin, kullanıcı belirli bir dil için bir tercih belirtirse, bu yöntemi çağırmak isteyebilirsiniz. setLocaleChain( ) yöntemi için chain adlı bir parametre gereklidir, bu parametre ["fr_FR","fr","fr_CA"] gibi bir yerel ayarlar dizisidir. Yerel ayarların dizideki sırası, çerçevenin kaynak arama sırasını belirler (sonraki işlemlerde). Zincirdeki ilk yerel ayar için kaynak bulunmazsa, diğer yerel ayarların kaynaklarına bakmaya devam eder. chain argümanı eksikse, bir dizi değilse veya boş bir diziyse, işlev başarısız olur ve bir IllegalArgumentsError istisnası atar.

Localizer nesnesinin statik getLocaleChain() yöntemi, geçerli yerel ayar zincirindeki yerel ayarları listeleyen bir Dizi döndürür.

Aşağıdaki kod geçerli yerel ayar zincirini okur ve zincirin başına iki Fransız yerel ayar ekler:

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

setLocaleChain() yöntemi yerel ayar zincirini güncellediğinde bir "change" olayı gönderir. air.Localizer.LOCALE_CHANGE sabiti, "change" dizesini tanımlar. Olayın localeChain adlı bir özelliği vardır, bu, yeni yerel ayar zincirindeki yerel ayar kodlarının bir dizisidir. Aşağıdaki kod bu olay için bir olay dinleyicisi ayarlar:

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

Statik air.Localizer.ultimateFallbackLocale özelliği, uygulama hiçbir kullanıcı tercihini desteklemediğinde kullanılan yerel ayarı temsil eder. Varsayılan olarak "en" değerindedir. Aşağıdaki kodda gösterildiği gibi, başka bir yerel ayara ayarlayabilirsiniz:

air.Localizer.ultimateFallbackLocale = "fr";

bundleName

resourceName

templateArgs

locale

Yerelleştirme çerçevesi işaretli HTML DOM niteliklerini güncelleyebilir. Ancak yerelleştirilmiş dizeleri başka şekillerde kullanabilirsiniz. Örneğin bir dizeyi dinamik olarak oluşturulmuş bir HTML'de veya bir işlev çağrısında parametre değeri olarak kullanabilirsiniz. Örneğin aşağıdaki kod alert() işlevini, fr_FR yerel ayarının varsayılan özellikler dosyasındaki error114 kaynağında tanımlı olan dizeyle çağırır:

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

getString() yöntemi, kaynağı belirtilen pakette bulamadığında bir resourceNotFound olayı gönderir. air.Localizer.RESOURCE_NOT_FOUND sabiti, "resourceNotFound" dizesini tanımlar. Olayın üç özelliği vardır: bundleName , resourceName ve locale . bundleName özelliği, kaynak bulunamayan paketin adıdır. resourceName özelliği, kaynak bulunamayan paketin adıdır. locale özelliği, kaynak bulunamayan yerel ayarın adıdır.

getString() yöntemi, belirtilen paketi bulamadığında bir bundleNotFound olayı gönderir. air.Localizer.BUNDLE_NOT_FOUND sabiti, "bundleNotFound" dizesini tanımlar. Olayın iki özelliği vardır: bundleName ve locale . bundleName özelliği, kaynak bulunamayan paketin adıdır. locale özelliği, kaynak bulunamayan yerel ayarın adıdır.

getString() yöntemi senkronize olmayan bir şekilde çalışır (ve resourceNotFound ve bundleNotFound olaylarını senkronize olmayan bir şekilde gönderir). Aşağıdaki kod resourceNotFound ve bundleNotFound olayları için olay dinleyicilerini ayarlar:

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 nesnesinin getResourceBundle() yöntemi, belirli bir yerel ayar için belirli bir paket döndürür. Yöntemin dönüş değeri, paketteki anahtarlarla eşleşen özelliklere sahip bir nesnedir. (Uygulama belirtilen paketi bulamazsa, yöntem null değerini döndürür.)

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

getResourceBundle() yöntemi, belirtilen paketi bulamadığında bir bundleNotFound olayı gönderir. air.Localizer.BUNDLE_NOT_FOUND sabiti, "bundleNotFound" dizesini tanımlar. Olayın iki özelliği vardır: bundleName ve locale . bundleName özelliği, kaynak bulunamayan paketin adıdır. locale özelliği, kaynak bulunamayan yerel ayarın adıdır.

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

Örneğin aşağıdaki kod, fr yerel ayarının about.html dosyasının içeriğini kullanarak document.write() yöntemini çağırır:

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

getFile() yöntemi, yerel ayar zincirinde kaynak bulamadığında bir fileNotFound olayı gönderir. air.Localizer.FILE_NOT_FOUND sabiti, "resourceNotFound" dizesini tanımlar. getFile() yöntemi senkronize olmayan bir şekilde çalışır (ve fileNotFound olayını senkronize olmayan bir şekilde gönderir). Olayın iki özelliği vardır: fileName ve locale . fileName özelliği, bulunamayan dosyanın adıdır. locale özelliği, kaynak bulunamayan yerel ayarın adıdır. Aşağıdaki kod bu olay için bir olay dinleyicisi ayarlar:

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