Localização de conteúdo HTML com a estrutura de localização de HTML do AIR

Para usar a estrutura de localização, copie o arquivo AIRLocalizer.js em seu projeto. Em seguida, inclua-a no arquivo HTML principal do aplicativo, usando uma tag de script:

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

Em seguida, o JavaScript pode chamar o objeto air.Localizer.localizer :

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

A classe Localizer inclui as seguintes propriedades estáticas:

Use o elemento <supportedLanguages> no descritor do aplicativo para identificar os idiomas suportados pelo aplicativo. Esse elemento é usado apenas pelo iOS, runtime cativo do Mac e aplicativos Android e é ignorado por todos os outros tipos de aplicativo.

Se você não especificar esse elemento <supportedLanguages> , por padrão o empacotador realiza as seguintes ações com base no tipo de aplicativo:

Para obter mais informações, consulte supportedLanguages .

A estrutura de localização HTML faz a leitura de versões localizadas de sequências de arquivos de localização . O arquivo de localização é um conjunto de valores baseados em chaves, serializados em um arquivo de texto. O arquivo de localização é algumas vezes tratado como um compactado .

Crie um subdiretório do diretório de projeto do aplicativo, chamado código de idiomas. (Você também pode usar um nome diferente; consulte Personalização de configurações HTML Localizer do AIR .) Esse diretório incluirá os arquivos de localização. Esse diretório é conhecido como o diretório de compactações .

Para cada código de idiomas a que seu aplicativo oferece suporte, crie um subdiretório do diretório de compactações. Nomeie cada subdiretório para corresponder ao código de idiomas. Por exemplo, nomeie o diretório French como "fr" e o diretório English como "en". Você pode usar o caractere sublinhado (_) para definir o código de idiomas que tenha um código de país e idioma. Por exemplo, nomeie o diretório U.S. English como “en_us”. (Como alternativa, você pode usar um hífen, em vez de um sublinhado, como em “en-us.” A estrutura de localização HTML oferece suporte às duas opções).

Você pode adicionar qualquer número de arquivos de recursos a um subdiretório código de idiomas. Normalmente, você cria um arquivo de localização para cada idioma (e coloca o arquivo no diretório desse idioma). A estrutura de localização HTML inclui o método getFile() que permite ler o conteúdo de um arquivo (consulte Obtenção de recursos para um código de idiomas específico .

Arquivos com a extensão de arquivo .properties são conhecidos como arquivos de propriedades de localização. Você pode usá-los para definir pares de valores chave para um código de idiomas. O arquivo de propriedade define um valor de sequência em cada linha. Por exemplo, o seguinte define o valor de sequência "Oi em inglês". para uma chave de nome greeting :

greeting=Hello in English.

O arquivo de propriedades contendo o texto a seguir define seis pares de valores chave:

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

Este exemplo mostra uma versão em inglês do arquivo de propriedades que deve ser armazenado no diretório en.

A versão francesa desse arquivo de propriedades é colocada no diretório fr:

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

Você pode definir vários arquivos de recursos para diferentes tipos de informações. Por exemplo, o arquivo legal.properties pode conter texto de padrão legal (como informações de direitos autorais). Você pode usar novamente esse recurso em diversos aplicativos. De modo semelhante, você pode definir arquivos separados que definem conteúdo localizado para diferentes partes da interface do usuário.

Use a codificação UTF-8 para esses arquivos, para oferecer suporte a vários idiomas.

Quando o aplicativo carrega o arquivo AIRLocalizer.js, ele examina os códigos de idiomas definidos no aplicativo. Esses códigos de idiomas correspondem aos subdiretórios do diretório de compactações (consulte Definição de grupos de recursos ). Essa lista de códigos de idiomas disponíveis é conhecida como a cadeia de código de idiomas . O arquivo AIRLocalizer.js classifica automaticamente a cadeia de código de idiomas com base na ordem de preferência definida pelas configurações do sistema operacional. (A propriedade Capabilities.languages lista os idiomas da interface do usuário do sistema operacional, por ordem de preferência).

Portanto, se um aplicativo define recursos para os códigos de idiomas "en", "en_US" e "en_UK", a estrutura HTML Localizer do AIR classifica a cadeia de código de idiomas de maneira apropriada. Quando o aplicativo é iniciado em um sistema que informa "en" como código de idiomas principal, a cadeia de código de idiomas é classificada como ["en", "en_US", "en_UK"] . Nesse caso o aplicativo procura primeiramente por recursos no grupo "en" e, em seguida, no grupo "en_US".

No entanto, se o sistema informar "en-US" como código de idiomas principal, a classificação usará ["en_US", "en", en_UK"] . Nesse caso, o aplicativo procura primeiramente recursos no grupo "en_US" e, em seguida, no grupo "en".

Por padrão, o aplicativo define o primeiro código de idiomas na cadeia de código de idiomas como o código de idiomas padrão para usar. Você pode solicitar que o usuário selecione um código de idiomas na primeira execução do aplicativo. Em seguida, você pode optar por armazenar a seleção em um arquivo de preferências e usar esse código de idiomas na inicialização subsequente do aplicativo.

O aplicativo pode usar as sequências de recursos em qualquer código de idiomas da cadeia de código de idiomas. Se um código de idiomas específico não definir uma sequência de recursos, o aplicativo usará a próxima sequência de recursos correspondente em outros códigos de idiomas definidos na cadeia de código de idiomas.

Você pode personalizar a cadeia de código de idiomas chamando o método setLocaleChain() do objeto Localizer. Consulte Definição da cadeia de código de idiomas .

O elemento no aplicativo pode fazer referência a um valor chave em um arquivo de propriedades de localização. Por exemplo, o elemento title no exemplo a seguir especifica um atributo local_innerHTML . A estrutura de localização usa esse atributo para pesquisar um valor localizado. Por padrão, a estrutura pesquisa nomes de atributos que iniciam com "local_" . A estrutura atualiza os atributos com nomes que correspondem ao texto em seguida a "local_" . Nesse caso, a estrutura define o atributo innerHTML do elemento title . O atributo innerHTML usa o valor definido para a chave mainWindowTitle no arquivo de propriedades padrão (default.properties):

<title local_innerHTML="default.mainWindowTitle"/>

Se o código de idiomas atual não definir nenhum valor correspondente, a estrutura do localizador procura o restante da cadeia de códigos de idiomas. Ele usa o próximo código de idiomas na cadeia de código de idiomas para o qual um valor está definido.

No exemplo a seguir, o texto (atributo innerHTML ) do elemento p usa o valor da chave greeting definido no arquivo de propriedades padrão:

<p local_innerHTML="default.greeting" />

No exemplo a seguir, o atributo de valor (e texto exibido) do elemento input usa o valor da chave btnBlue definido no arquivo de propriedades padrão:

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

Para atualizar o HTML DOM para usar as sequências definidas na cadeia de código de idiomas atual, chame o método update() do objeto Localizer. Chamar o método update() faz com que o objeto Localizer analise o DOM e aplique manipulações onde encontrar atributos de localização ( "local_..." ):

air.Localizer.localizer.update();

Você pode definir valores tanto para um atributo (como "innerHTML") quanto para o respectivo atributo de localização correspondente (como "local_innerHTML"). Nesse caso, a estrutura de localização só sobrescreve o valor de atributo se ela encontrar um valor correspondente na cadeia de localização. Por exemplo, o elemento a seguir define os atributos value e local_value :

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

Você também pode atualizar apenas um elemento DOM específico Consulte a próxima seção, Atualização de elementos DOM para uso de código de idiomas atual .

Por padrão, o HTML Localizer do AIR usa "local_" como o prefixo de atributos que definem as configurações de localização do elemento. Por exemplo, por padrão, o atributo local_innerHTML define o nome do grupo e recurso usados no valor innerHTML do elemento. Além disso, por padrão, o atributo local_value define o nome do grupo e recurso usados no atributo value do elemento. Você pode configurar o Localizer para usar um prefixo de atributo além de "local_" . Consulte Personalização de configurações HTML Localizer do AIR

Quando o objeto Localizer atualiza o HTML DOM, isso faz com que elementos marcados usem valores de atributos com base nas sequências definidas na cadeia de código de idiomas atual. Para fazer com que o localizador HTML atualize o HTML DOM, chame o método update() do objeto Localizer :

air.Localizer.localizer.update();

Para atualizar apenas um elemento DOM especificado, passe-o como parâmetro para o método update() . O método update() só tem um parâmetro, parentNode , que é opcional. Quando especificado, o parâmetro parentNode define o elemento DOM para ser localizado. Chamar o método update() e especificar o parâmetro parentNode define os valores localizados de todos os elementos filhos que especificam atributos de localização.

Por exemplo, considere o seguinte elemento 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>

Para atualizar esse elemento para usar as sequências localizadas definidas na cadeia de código de idiomas atual, use o seguinte código JavaScript:

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

Se o valor chave não for encontrado na cadeia de código de idiomas, a estrutura de localização definirá o valor de atributo como o valor do atributo "local_" . Por exemplo, no exemplo anterior, suponhamos que a estrutura de localização não possa encontrar o valor da chave lblColors (em qualquer um dos arquivos default.properties na cadeia de código de idiomas). Nesse caso, ela usará "default.lblColors" como valor innerHTML . Usar esse valor indica (para o desenvolvedor) ausência de recursos.

O método update() despacha o evento resourceNotFound quando não consegue encontrar um recurso na cadeia de código de idiomas. A constante air.Localizer.RESOURCE_NOT_FOUND define a sequência "resourceNotFound" . O evento tem três propriedades: bundleName , resourceName e locale . A propriedade bundleName é o nome do grupo em que o recurso não foi encontrado. A propriedade resourceName é o nome do grupo em que o recurso não foi encontrado. A propriedade locale é o nome do código de idiomas em que o recurso não foi encontrado.

O método update() despacha o evento bundleNotFound quando não consegue encontrar o grupo especificado. A constante air.Localizer.BUNDLE_NOT_FOUND define a sequência "bundleNotFound" . O evento tem duas propriedades: bundleName e locale . A propriedade bundleName é o nome do grupo em que o recurso não foi encontrado. A propriedade locale é o nome do código de idiomas em que o recurso não foi encontrado.

O método update() funciona de forma assíncrona (e despacha os eventos resourceNotFound e bundleNotFound de forma assíncrona). O código a seguir define ouvintes de evento dos eventos resourceNotFound e 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); 
}

O método setBundlesDirectory() do objeto Localizer permite personalizar o caminho do diretório de compactações. O método setLocalAttributePrefix() do objeto Localizer permite personalizar o caminho do diretório de compactações e personalizar o valor de atributo usado pelo Localizer.

O diretório de compactações padrão é definido como o subdiretório código de idiomas do diretório do aplicativo. Você pode especificar outro diretório chamando o método setBundlesDirectory() do objeto Localizer. Esse método usa o parâmetro path , que é o caminho para o diretório de compactações desejado, como uma sequência. O valor do parâmetro path pode ser algum dos seguintes:

Por exemplo, o código a seguir define o diretório de compactações como subdiretório de idiomas do diretório de armazenamento do aplicativo (não o diretório de aplicativo):

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

Passe um caminho válido como o parâmetro path . Do contrário, o método emitirá uma exceção BundlePathNotFoundError. Esse erro tem "BundlePathNotFoundError" como sua propriedade name e a respectiva propriedade message especifica o caminho inválido.

Por padrão, o HTML Localizer do AIR usa "local_" como o prefixo de atributos que definem as configurações de localização do elemento. Por exemplo, o atributo local_innerHTML define o nome do grupo e recurso usado no valor innerHTML do seguinte elemento input :

<p local_innerHTML="default.greeting" />

O método setLocalAttributePrefix() do objeto Localizer permite usar outro prefixo de atributo que não seja "local_" . Esse método estático usa um parâmetro, que é a sequência que você deseja usar como prefixo de atributo. Por exemplo, o código a seguir define que a estrutura de localização use "loc_" como o prefixo de atributo:

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

Você pode personalizar o prefixo de atributo que a estrutura de localização utiliza. Talvez você deseje personalizar o prefixo, caso o valor padrão ( "local_" ) entre em conflito com o nome de outro atributo usado por seu código. Certifique-se de usar caracteres válidos em atributos HTML quando chamar esse método. (Por exemplo, o valor não pode conter um caractere de espaço em branco).

Para obter mais informações sobre como usar os atributos de localização em elementos HTML, consulte Atualização de elementos DOM com conteúdo localizado .

As configurações do diretório de compactações e prefixo de atributo não persistem entre sessões de aplicativos diferentes. Se você usar uma configuração personalizada de diretório de compactações ou de prefixo de atributo, certifique-se de defini-las sempre que iniciar o aplicativo.

Por padrão, quando você carrega o código AIRLocalizer.js, ele define a cadeia de código de idiomas padrão. Os códigos de idiomas disponíveis nas configurações de diretório de compactações e de idioma do sistema operacional definem essa cadeia de código de idiomas. (Para obter detalhes, consulte Gerenciamento de cadeias de códigos de idiomas .)

Você pode modificar a cadeia de código de idiomas chamando o método estático setLocaleChain( ) do objeto Localizer. Por exemplo, talvez você deseje chamar esse método se o usuário indicar a preferência por um idioma específico. O método setLocaleChain( ) usa um parâmetro, chain , que é uma matriz de códigos de idiomas, como ["fr_FR","fr","fr_CA"] . A ordem dos códigos de idiomas na matriz define a ordem em que a estrutura pesquisa recursos (em operações subsequentes). Se o recurso não for encontrado para o primeiro código de idiomas na cadeia, ele continua pesquisando em outros recursos de códigos de idiomas. Se o argumento chain estiver ausente, se não for uma matriz ou for uma matriz vazia, a função falhará e emitirá uma exceção IllegalArgumentsError.

O método estático getLocaleChain() do objeto Localizer retorna uma matriz que lista os códigos de idiomas na cadeia de código de idiomas atual.

O código a seguir faz a leitura da cadeia de código de idiomas atual e adiciona dois códigos de idiomas franceses ao cabeçalho da cadeia:

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

O método setLocaleChain() despacha o evento "change" quando atualiza a cadeia de código de idiomas. A constante air.Localizer.LOCALE_CHANGE define a sequência "change" . O evento tem uma propriedade, localeChain , uma matriz de códigos de idiomas na nova cadeia de código de idiomas. O código a seguir define um ouvinte de evento para esse evento:

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

A propriedade estática air.Localizer.ultimateFallbackLocale representa o código de idiomas usado quando o aplicativo não oferece suporte a nenhuma preferência do usuário. O valor padrão é "en" . Você pode defini-lo como outro código de idiomas, como mostrado no código a seguir:

air.Localizer.ultimateFallbackLocale = "fr";

bundleName

resourceName

templateArgs

locale

A estrutura de localização pode atualizar atributos HTML DOM marcados. No entanto, você pode usar sequências localizadas de outras maneiras. Por exemplo, você pode usar uma sequência em HTMLs gerados dinamicamente ou como valor de parâmetro em uma chamada de função. Por exemplo, o código a seguir chama a função alert() com a sequência definida no recurso error114 no arquivo de propriedades padrão do código de idiomas fr_FR:

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

O método getString() despacha o evento resourceNotFound quando não consegue encontrar o recurso no grupo especificado. A constante air.Localizer.RESOURCE_NOT_FOUND define a sequência "resourceNotFound" . O evento tem três propriedades: bundleName , resourceName e locale . A propriedade bundleName é o nome do grupo em que o recurso não foi encontrado. A propriedade resourceName é o nome do grupo em que o recurso não foi encontrado. A propriedade locale é o nome do código de idiomas em que o recurso não foi encontrado.

O método getString() despacha o evento bundleNotFound quando não consegue encontrar o grupo especificado. A constante air.Localizer.BUNDLE_NOT_FOUND define a sequência "bundleNotFound" . O evento tem duas propriedades: bundleName e locale . A propriedade bundleName é o nome do grupo em que o recurso não foi encontrado. A propriedade locale é o nome do código de idiomas em que o recurso não foi encontrado.

O método getString() opera de forma assíncrona (e despacha os eventos resourceNotFound e bundleNotFound de forma assíncrona). O código a seguir define ouvintes de evento dos eventos resourceNotFound e 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); 
}

O método getResourceBundle() do objeto Localizador retorna um grupo especificado para um determinado local. O valor de retorno do método é um objeto com propriedades correspondentes às chaves do grupo. (Se o aplicativo não puder localizar o grupo especificado, o método retornará 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/>");

O método getResourceBundle() despacha o evento bundleNotFound quando não consegue encontrar o grupo especificado. A constante air.Localizer.BUNDLE_NOT_FOUND define a sequência "bundleNotFound" . O evento tem duas propriedades: bundleName e locale . A propriedade bundleName é o nome do grupo em que o recurso não foi encontrado. A propriedade locale é o nome do código de idiomas em que o recurso não foi encontrado.

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

Por exemplo, o código a seguir chama o método document.write() usando o conteúdo do arquivo about.html do código de idiomas fr:

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

O método getFile() despacha o evento fileNotFound quando não consegue encontrar um recurso na cadeia de código de idiomas. A constante air.Localizer.FILE_NOT_FOUND define a sequência "resourceNotFound" . O método getFile() funciona de forma assíncrona (e despacha o evento fileNotFound de forma assíncrona). O evento tem duas propriedades: fileName e locale . A propriedade fileName é o nome do arquivo não encontrado. A propriedade locale é o nome do código de idiomas em que o recurso não foi encontrado. O código a seguir define um ouvinte de evento para esse evento:

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