Локализация HTML-содержимого с помощью инфраструктуры локализации AIR HTML

Чтобы воспользоваться многоязычной функциональностью, скопируйте файл AIRLocalizer.js в своей проект. Затем включите его в основной HTML-файл приложения, заключив в тег script:

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

Код JavaScript может вызвать объект air.Localizer.localizer:

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

Класс Localizer содержит ряд статичных свойств.

Инфраструктура локализации HTML считывает локализованные строки из файлов локализации. Файл локализации — это набор значений, привязанных к ключам и последовательно собранных в текстовый файл. Файл локализации иногда называют пакетом.

Создайте в каталоге приложения подкаталог с названием locale. (Можно использовать другое имя, см. раздел «Изменение параметров Localizer в AIR HTML».) Здесь будут храниться файлы локализации. Этот каталог известен как каталог пакетов.

Для каждой локали, которая поддерживается приложением, создайте подкаталог каталога пакетов. Назовите каждый подкаталог в соответствии с кодом локали. Например, для французского каталога используйте имя «fr», а для английского — «en». С помощью знака подчеркивания (_) можно определить локаль, содержащую язык и код страны. Например, каталог для английского (США) может называться «en_us». (Также можно использовать дефис, в этом случае каталог будет называться «en-us». Инфраструктура локализации распознает оба варианта.)

В подкаталог locale можно добавить сколь угодно много файлов ресурсов. Как правило, файл локализации создается для каждого языка (и помещается в каталог соответствующего языка). Инфраструктура локализации HTML содержит метод getFile(), позволяющий считывать содержимое файла (см. раздел «Получение ресурсов для определенной локали»).

Файлы с расширением .properties называются файлами свойств локализации. Они используются для определения пар «ключ-значение» той или иной локали. Файл свойств задает строковое значение на каждой строке. Например, ниже показано, как задать строковое значение "Hello in English." для ключа с именем greeting:

greeting=Hello in English.

В файле свойств содержится следующий текст и задаются шесть пар «ключ-значение»:

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

Этом примере показана английская версия файла свойств из каталога en.

Французская версия этого файла будет помещена в каталог fr:

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

Для разных типов информации можно задать разные файлы ресурсов. Скажем, в файле legal.properties может храниться какой-нибудь шаблонный юридический документ (к примеру, информация об авторских правах). Эти ресурсы можно повторно использовать в различных приложения Точно так же можно задать файлы для определения локализованного содержимого разных частей пользовательского интерфейса.

В этих файлах следует использовать кодировку UTF-8, чтобы языки отображались корректно.

Когда приложение загружает файл AIRLocalizer.js, оно исследует доступные локали. Эти локали соответствуют подкаталогам каталога пакетов (см. раздел «Определение пакетов ресурсов»). Список поддерживаемых локалей называется цепочкой локалей. Файл AIRLocalizer.js автоматически определяет порядок локалей в цепочке на основании соответствующих параметров операционной системы. (Свойство Capabilities.languages содержит список языков пользовательского интерфейса операционной системы, в порядке предпочтения.)

Поэтому, если в приложении определены ресурсы для локалей «en», «en_US» и «en_UK», инфраструктура Localizer AIR HTML упорядочивает цепочку локалей соответственно. Если приложение запускается в системе, где основной локалью является «en», цепочка локалей будет иметь порядок ["en", "en_US", "en_UK"]. В этом случае приложение сначала будет искать ресурсы в пакете «en», потом в «en_US».

Однако, если основной локалью в системе является «en-US», то порядок будет таков: ["en_US", "en", en_UK"]. В этом случае приложение сперва обратится к пакету «en_US», а потом к «en».

По умолчанию, первая локаль в цепочке считается стандартом по умолчанию. Можно попросить пользователя выбрать локаль при первом запуске приложения. Затем можно сохранить этот выбор в файле настроек и при последующих запусках сразу включать эту локаль.

Могут использоваться строки ресурсов любой локали из цепочки. Если в какой-то из локалей строка ресурсов не задана, приложение обратится к следующей подходящей строке из другой локали.

Для изменения настроек цепочки локалей вызовите метод setLocaleChain() объекта Localizer. См. раздел «Определение цепочки локалей».

Элемент приложения может обращаться к ключу в файле свойств локализации. Например, элемент title в примере ниже задает атрибут local_innerHTML. Инфраструктура локализации использует этот атрибут для нахождения локализованного значения. По умолчанию, инфраструктура ищет атрибуты, имена которых начинаются с "local_". Она обновляет атрибуты с совпадающей частью имени после "local_". В этом случае инфраструктура задает атрибут innerHTML элемента title. Атрибут innerHTML использует значение, заданное для ключа mainWindowTitle в файле свойств по умолчанию (default.properties):

<title local_innerHTML="default.mainWindowTitle"/>

Если в текущей локали нет подходящего значения, тогда инфраструктура локализации просматривает остальные локали цепочки. Используется ближайшая локаль в цепочке, в которой значение определено.

В примере ниже в тексте (атрибут innerHTML attribute) элемента p используется значение ключа greeting, заданное в файле свойств по умолчанию:

<p local_innerHTML="default.greeting" />

В примере ниже в атрибуте value (и отображаемом тексте) элемента input используется значение ключа btnBlue из файла свойств по умолчанию:

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

Чтобы обновить модель DOM HTML и использовать строки, заданные в текущей цепочке ключей, вызовите метод update() объекта Localizer. Вызов метода update() позволяет объекту Localizer разобрать DOM и выполнить необходимые действия над найденными атрибутами локализации ("local_..."):

air.Localizer.localizer.update();

Можно задать значения для атрибута (например, «innerHTML») и соответствующего ему атрибута локализации (например, «local_innerHTML»). В этом случае инфраструктура локализации перепишет значение атрибута, только если найдет совпадающее значение в цепочке. Например, следующий элемент задает атрибуты value и local_value:

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

Можно обновить и отдельный элемент DOM. См. следующий раздел «Обновление элементов DOM для использования текущей локали».

По умолчанию Localizer AIR HTML использует "local_" в качестве префикса для атрибутов, определяющий параметры локализации элемента. Например, по умолчанию атрибут local_innerHTML определяет имя пакета и ресурса для значения innerHTML элемента. Кроме того, по умолчанию атрибут local_value определяет имя пакета и ресурса для значения value элемента. Localizer можно изменить, чтобы использовать другой префикс атрибута (не "local_"). См. раздел «Изменение параметров Localizer в AIR HTML».

Когда объект Localizer обновляет модель DOM HTML, помеченные элементы вынуждены использовать значения атрибутов, основанные на строках, которые заданы в текущей цепочке локалей. Чтобы Localizer HTML обновил DOM HTML, вызовите метод update() объекта Localizer:

air.Localizer.localizer.update();

Чтобы обновить только отдельный элемент DOM, передайте его в качестве параметра методу update(). Метод update() имеет только один параметр, parentNode, и тот не обязателен. Если параметр parentNode задан, он определяет локализуемый элемент DOM. При вызове метода update() и указании параметра parentNode задаются локализованные значения для всех дочерних элементов, которые указывают атрибуты локализации.

Рассмотрим элемент 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>

Чтобы обновить этот элемент и использовать локализованные строки, заданные в цепочке локалей, воспользуйтесь следующим кодом JavaScript:

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

Если значение ключа не найдено в цепочке локалей, инфраструктура использует значение атрибута "local_". Положим, в предыдущем примере инфраструктуре не удалось найти значение для ключа lblColors (ни в одном из файлов default.properties в цепочке локалей). Тогда в качестве значения innerHTML будет использоваться "default.lblColors". Использование этого значения сообщает разработчику, что каких-то ресурсов недостает.

Метод update() отправляет событие resourceNotFound, когда не может найти ресурс в цепочке локалей. Константа air.Localizer.RESOURCE_NOT_FOUND задает строку "resourceNotFound". У этого события есть три свойства: bundleName, resourceName и locale. Свойство bundleName — это имя пакета, в котором не удалось обнаружить ресурс. Свойство resourceName — это имя ресурса, который не удалось обнаружить. Свойство locale — это имя локали, в которой не удалось обнаружить ресурс.

Метод update() отправляет событие bundleNotFound, когда не может найти указанный пакет. Константа air.Localizer.BUNDLE_NOT_FOUND задает строку "bundleNotFound". У события есть два свойства: bundleName и locale. Свойство bundleName — это имя пакета, в котором не удалось обнаружить ресурс. Свойство locale — это имя локали, в которой не удалось обнаружить ресурс.

Метод update() работает асинхронно (и асинхронно отправляет события resourceNotFound и bundleNotFound). Следующий код задает прослушиватели для событий resourceNotFound и 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); 
}

Метод setBundlesDirectory() объекта Localizer позволят изменить путь к каталогу пакетов. Метод setLocalAttributePrefix() объекта Localizer позволяет изменить путь к каталогу пакетов и значения атрибутов, используемых объектом Localizer.

Каталог пакетов по умолчанию определен как подкаталог locale в каталоге приложения. Можно задать другой каталог, вызвав метод setBundlesDirectory() объекта Localizer. Этот метод принимает один параметр, path, задающий в виде строки путь к нужному каталогу пакетов. Значением параметра path может быть одно из следующих:

Например, в коде ниже в качестве каталога пакетов задается подкаталог languages каталога хранилища приложения (не каталога приложения):

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

В качестве параметра path должен передаваться действительный путь. В противном случае метод генерирует исключение BundlePathNotFoundError. "BundlePathNotFoundError" является значением свойства name этой ошибки, а свойство message указывает недействительный путь.

По умолчанию Localizer AIR HTML использует "local_" в качестве префикса для атрибутов, определяющий параметры локализации элемента. Например, атрибут local_innerHTML определяет имена пакета и ресурса в значении innerHTML следующего элемента input:

<p local_innerHTML="default.greeting" />

Метод setLocalAttributePrefix() объекта Localizer позволяет использовать префикс атрибута, отличный от "local_". Статический метод принимает один параметр — строку, которая используется в качестве префикса атрибута. Например, в коде ниже инфраструктура локализации использует в качестве префикса атрибута «loc_»:

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

Этот префикс можно изменять. Например, это может потребоваться, если префикс по умолчанию ("local_") приводит к конфликту с именем другого атрибута в коде. При вызове этого метода используйте допустимые символы для HTML-атрибутов. (Например, знак пробела использовать нельзя.)

Дополнительные сведения об использовании атрибутов локализации в HTML-элементах см. в разделе «Обновление элементов DOM с использованием локализованного содержимого».

Параметры каталога пакетов и префикса атрибута не сохраняются между разными сеансами приложения. Если вы используете собственный каталог пакетов или префикс атрибута, его потребуется задавать каждый раз при запуске приложения.

По умолчанию, когда загружается файл AIRLocalizer.js, он задает цепочку локалей. Эту цепочку определяют локали, доступные в каталоге пакетов и параметры языка пользовательского интерфейса системы. (Дополнительные сведения см. в разделе «Управление цепочками локалей».)

Для изменения настроек цепочки локалей вызовите статический метод setLocaleChain() объекта Localizer. Например, этот метод можно вызвать, если пользователь указал, какой язык предпочитает. Метод setLocaleChain() принимает один параметр, chain, представляющий собой массив локалей, например ["fr_FR","fr","fr_CA"]. Инфраструктура ищет ресурсы (в последовательности операций) в том порядке, в каком идут локали в массиве. Если ресурс не удается найти в первой локали, то поиск продолжается в ресурсах других локалей. Если аргумент chain отсутствует, не является массивом или является пустым массивом, то функция дает сбой и генерирует исключение IllegalArgumentsError.

Статический метод getLocaleChain() объекта Localizer возвращает объект Array со списком локалей в текущей цепочке.

Приведенный ниже код читает текущую цепочку локалей и добавляет в начало две французских локали:

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

При обновлении цепочки локалей метод setLocaleChain() отправляет событие "change". Константа air.Localizer.LOCALE_CHANGE определяет строку "change". Событие имеет единственное свойство, localeChain, представляющее собой массив кодов локалей в новой цепочке. В коде ниже задается прослушиватель для этого события:

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

Статическое свойство air.Localizer.ultimateFallbackLocale представляет локаль, которая используется, если приложение не поддерживает пользовательские установки. Значение по умолчанию равно "en". Можно задать и другую локаль, как показано ниже:

air.Localizer.ultimateFallbackLocale = "fr";

bundleName

resourceName

templateArgs

locale

Инфраструктура локализации может обновлять отмеченные атрибуты DOM HTML. Однако локализованные строки могут использоваться иными способами. Например, можно использовать строку в каком-нибудь динамически создаваемом HTML-файле или в качестве значения параметра при вызове функции. В приведенном ниже коде в вызове функции alert() участвует строка, определенная в ресурсе error114 в файле свойств по умолчанию для локали fr_FR:

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

Когда метод getString() не может найти ресурс в определенном пакете, он отправляет событие resourceNotFound. Константа air.Localizer.RESOURCE_NOT_FOUND задает строку "resourceNotFound". У этого события есть три свойства: bundleName, resourceName и locale. Свойство bundleName — это имя пакета, в котором не удалось обнаружить ресурс. Свойство resourceName — это имя ресурса, который не удалось обнаружить. Свойство locale — это имя локали, в которой не удалось обнаружить ресурс.

Метод getString() отправляет событие bundleNotFound, когда не может найти указанный пакет. Константа air.Localizer.BUNDLE_NOT_FOUND задает строку "bundleNotFound". У события есть два свойства: bundleName и locale. Свойство bundleName — это имя пакета, в котором не удалось обнаружить ресурс. Свойство locale — это имя локали, в которой не удалось обнаружить ресурс.

Метод getString() работает асинхронно (и асинхронно отправляет события resourceNotFound и bundleNotFound). Следующий код задает прослушиватели для событий resourceNotFound и 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); 
}

Метод getResourceBundle() объекта Localizer возвращает указанный пакет для заданного языка (параметр locale). Возвращаемое методом значение является объектом со свойствами, соответствующими ключам в пакете. (Если приложение не может найти указанный пакет, метод возвращает значение 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/>");

Метод getResourceBundle() отправляет событие bundleNotFound, когда не может найти указанный пакет. Константа air.Localizer.BUNDLE_NOT_FOUND задает строку "bundleNotFound". У события есть два свойства: bundleName и locale. Свойство bundleName — это имя пакета, в котором не удалось обнаружить ресурс. Свойство locale — это имя локали, в которой не удалось обнаружить ресурс.

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

Например, в коде ниже метод document.write() вызывается с помощью содержимого файла about.html локали fr:

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

Метод getFile() отправляет событие fileNotFound, когда не может найти ресурс в цепочке локалей. Константа air.Localizer.FILE_NOT_FOUND определяет строку "resourceNotFound". Метод getFile() работает асинхронно (и асинхронно отправляет событие fileNotFound). У события есть два свойства: fileName и locale. Свойство fileName — это имя файла, который не удалось найти. Свойство locale — это имя локали, в которой не удалось обнаружить ресурс. В коде ниже задается прослушиватель для этого события:

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