Localização

O SDK suporta localização de strings que aparecem no:

Ele, ainda, não suporta localização de conteúdo CSS ou Scripts.

Strings de Localização

Strings traduzidas são mantidas em um diretório chamado "locale" no diretório principal do seu add-on, um arquivo para cada locale. Os arquivos:

  • use o formato .properties
  • são chamados "xx-YY.properties", onde "xx-YY" é o nome da localidade em questão
  • contém uma entrada para cada string que você quer localizar, consistindo de um identificador para a string e sua tradução para aquela localidade, no formado identificador=tradução.
  • precisa usar UTF-8 sem codificação BOM

Suponha que seu add-on contém uma única string localizável, representada em Inglês como "Hello!", e você quer suprir com localizações US English e Francês.

Você adiciona dois arquivos ao diretório "locale":

my-addon/
         data
         lib
         locale/
                en-US.properties
                fr-FR.properties

"en-US.properties" contém isto:

hello_id= Hello!

"fr-FR.properties" contém isto:

hello_id= Bonjour !

Agora que sempre que em seu código JavaScript ou HTML pedir  ao sistema de localização pela tradução do identificador hello_id, ele pegará a tradução correta para a localidade atual.

Usando Strings de Localização no HTML

Este exemplo usa a API action button, que está disponível somente do Firefox 29 em diante.

Para referenciar uma string localizada do HTML, adicione um atributo data-l10n-id à tag HTML onde você quiser que a string localizada apareça, e atribua o identificador a ele:

<html>
  <body>
    <h1 data-l10n-id="hello_id"></h1>
  </body>
</html>

Então você pode usar o arquivo HTML para construir sua interface, por exemplo dentro de um painel:

var button = require("sdk/ui/button/action").ActionButton({
  id: "localized-hello",
  label: "Localized hello",
  icon: "./icon-16.png",
  onClick: function() {
    hello.show();
  }
});

var hello = require("sdk/panel").Panel({
  height: 75,
  width: 150,
  contentURL: require("sdk/self").data.url("my-panel.html")
});

Dados os arquivos locale para "en-US" e "fr-FR" que fornece uma tradução para o hello_id, o painel agora mostrará o "Hello!" ou "Bonjour !", de acordo com a localidade atual:

A tradução é inserida dentro do nó que tem o atributo data-l10n-id. Qualquer conteúdo anteriormente existente é substituído.

A string é inserida como texto, então você não pode inserir HTML usando declarações como:

hello_id= <blink>Hello!</blink>

Localizando Atributos de Elementos

Esta característica é nova no Firefox 39


Você pode localizar certos atributos de elementos com um l10n-id configurando seu valor com o l10-id.attributeName no arquivo da propriedade como isto:

hello_id.accesskey= H

Os seguintes atributos são suportados:

  • accesskey
  • alt
  • label
  • title
  • placeholder

Além disso, a localização dos atributos ARIA aria-label, aria-valuetext e aria-moz-dica são suportados com os mesmos apelidos que no Firefox OS:

  • ariaLabel
  • ariaValueText
  • ariaMozHint

Usando Strings de Localização no JavaScript

Para referenciar Strings de Localização do código principal do seu add-on, você faz isso:

var _ = require("sdk/l10n").get;
console.log(_("hello_id!"));

A atribuição de "_" em particular não é requerida, mas é uma convenção da ferramente gettext e torna possível trabalhar com ferramentas existentes que esperam "_" para indicar Strings de Localização.

  1. Importe o módulo l10n, atribua sua função get o "_" (underscore).
  2. Envolva todas as referências a Strings de Localização com uma função _().

Se você executar ela você verá a saída esperada para a localidade atual:

info: Hello!
info: Bonjour !

Observe que você não pode require() módulos nos scripts de conteúdo, você ainda não pode referenciar strings de localização nos scripts de conteúdo.

Plurais

O módulo l10n suporta formas plurais. Diferentes línguas tem diferentes regras para formação de plurais. Por exemplo, Inglês tem duas formas: uma forma singular para "one", e uma forma plural para "everything else, including zero":

one tomato
no tomatoes
two tomatoes

Mas a Russa tem diferentes formas para números terminados em 1 (exceto 11), números terminados em 2-4 (exceto 12-14) e outros números:

один помидор     // one tomato
два помидора     // two tomatoes
пять помидоров   // five tomatoes

O SDK usa dados do Unicode CLDR para descrever as diferentes formas de plural usadas pelas diferentes línguas.

Formas Plurais do Unicode CLDR

O projeto Unicode CLDR define um esquema que descreve a regras de plural de uma língua em particular. Neste esquema uma  língua mapeia cada abrangência distinta de números para um ou mais formas, identificado pelas categorias: zero, one, two, few, many, e other.

Inglês tem duas formas, que podem ser descritas pelo mapeamento "1" para "one" e "everything else" para "other":

one   → n is 1;
other → everything else

A Russa usa quatro formas, que podem ser descritas como se segue:

one   → n mod 10 is 1 and n mod 100 is not 11;
few   → n mod 10 in 2..4 and n mod 100 not in 12..14;
many  → n mod 10 is 0 or n mod 10 in 5..9 or n mod 100 in 11..14;
other → everything else

As regras de plural para todas as línguas podem ser encontrada na página de Regras para Plural das Línguas do CLDR (embora esta tabela esteja desatualizada se comparada com a CLDR XML source).

Formas Plurais no SDK

No código, você fornece uma parâmetro extra ao lado do identificador, descrevendo quantos itens há:

var _ = require("sdk/l10n").get;
console.log(_("tomato_id"));
console.log(_("tomato_id", 1));
console.log(_("tomato_id", 2));
console.log(_("tomato_id", 5));
console.log(_("tomato_id", .5));

No arquivo .properties para cada língua você pode definir uma localização diferente para cada forma de plural possível naquela língua, usando palavras reservadas do CLDR. Então no Inglês nós teríamos duas localizações de plural (observe que a categoria "other" não leva palavra reservada do CLDR:

# en-US translations
tomato_id[one]= %d tomato
tomato_id= %d tomatoes

Na Russa nós teríamos quatro localizações de plural:

# ru-RU translations
tomato_id[one]= %d помидор
tomato_id[few]= %d помидора
tomato_id[many]= %d помидоров
tomato_id= %d помидоры

O módulo de localização por si só entende as definições CLDR para cada língua, permitindo a ele mapear, por exemplo, "2" no código e "few" no arquivo ru-RU.properties. Então ele pega e retorna a localização apropriada para a contagem fornecida.

Placeholders

O módulo l10n suporta placeholders, permitindo a você inserir uma string que não deveria ser localizada em uma que é. Os seguintes arquivos "en-US" e "fr-FR" ".properties" estão incluídos placeholders:

# en-US translations
hello_id= Hello %s!
# fr-FR translations
hello_id= Bonjour %s !

Para usar placeholders, forneça uma string placeholder depois do identificador:

var _ = require("sdk/l10n").get;
console.log(_("hello_id", "Bob"));
console.log(_("hello_id", "Alice"));

Na localidade Inglês "en-US", isto nos é dado:

info: Hello Bob!
info: Hello Alice!

No "fr-FR" nós conseguimos:

info: Bonjour Bob !
info: Bonjour Alice !

Ordenando Placeholders

Quando strings localizáveis podem levar dois ou mais placeholders, tradutores podem definir a ordem em que placeholders são inseridos, sem afetar o código.

Primeiramente, isto é importante porque diferentes línguas tem regras diferentes para ordernar palavras. Mesmo dentro de uma mesma língua, embora traduzida, tradutores deve ter liberdade para definir a ordem.

Por exemplo, suponha que nós queremos incluir uma string de localização designando a cidade de uma pessoa. Há dois placeholders: o nome da pessoa e o nome da cidade em que ela reside:

var _ = require("sdk/l10n").get;
console.log(_("home_town_id", "Bob", "London"));

An English translator might want to choose between the following:

"<town_name> is <person_name>'s home town."
"<person_name>'s home town is <town_name>"

Para escolher a primeira opção, o arquivo .properties pode ordenar o placeholders como:

home_town_id= %2s is %1s's home town.

Isso nos dá a seguinte saída:

info: London is Bob's home town.

Usando Strings de localização em Preferências

Pela inclusão de uma estrutura "preferences" no arquivo "package.json" do seu add-on, você pode definir preferências para seu add-on que o usuário pode ver e editar usando o gerenciador de add-ons do Firefox.

Preferências tem um campo title obrigatório e um campo description opcional. Há strings que aparecem ao lado da preferência no gerenciador de Add-on, para ajudar a explicar ao usuário o que a preferência significa.

  • Para fornecer formas localizadas do title da preferência, inclua uma entrada no arquivo "properties" cujo identificador seja o nome da preferência seguido por  _title, e cujo valor é o título da localidade.

  • Para fornecer forma localizada da descrição da preferência, inclui uma entrada em seu arquivo "properties" cujo identificador é o nome da preferência seguido por _description, e cujo valor é a descrição da localidade.

Por exemplo, suponha que seu "package.json" defina uma única preferência:

{
    "preferences": [
        {
            "type": "string", 
            "name": "monster_name", 
            "value": "Gerald",
            "title": "Name"
        }
    ], 
    "name": "monster-builder", 
    "license": "MPL 2.0", 
    "author": "me", 
    "version": "0.1", 
    "fullName": "Monster Builder", 
    "id": "monster-builder@me.org", 
    "description": "Build your own monster"
}

Em seu arquivo "en-US.properties", inclua estes dois itens:

monster_name_title= Name
monster_name_description= What is the monster's name?

Em seu arquivo "fr-FR.properties", inclui a tradução francesa:

monster_name_title= Nom
monster_name_description= Quel est le nom du monstre ?

Agora quando o local do navegador estiver configurado para "en-US", os usuários verão este Gerenciador de Add-on:

Quando o local do navegador estiver configurado para "fr-FR", eles verão isto:

Os tipos de preferência de menulist e radio tem opções. O atributo label de cada opção é mostrado para o usuário. Se o arquivo de local tem uma entrada com o valor do atributo label prefixado com "{name}_options." como sua chave, onde {name} é o nome da preferência, seu valor é usado como rótulo por localização.

Usando identificadores

Se o sistema de localização não pode encontrar uma entrada para um identificador em particular usando a localidade atual, então ele apenas retorna o identificador por si mesmo.

Isto tem a bonita propriedade que você pode escrever add-on localizável, inteiramente funcional sem ter que escrever qualquer arquivo local. Você pode usar somente a linguagem padrão como seu identificador, e subsequentemente fornecer arquivos .properties para todos os locais adicionais que você quiser suportar.

Por exemplo, no caso acima você poderia usar "Hello!" como o identificador, e apenas ter um arquivo .properties para a localidade "fr-FR":

Hello!= Bonjour !

Então quando a localidade é "en-US", o sistema falharia ao encontrar o arquivo  .properties file, e retornaria "Hello!".

Porém, essa técnica torna difícil manter um add-on que tem muitas localizações, porque você estará usando a língua padrão tanto para strings de interface quanto chaves de tradução. Isto significa que se você quiser mudar o nome de uma string na língua padrão, ou consertar a digitação, então você quebrará todos os seus arquivos de tradução.

Locale Updater

O addon locale updater torna fácil atualizar arquivos de localidade. Uma vez que você o instalou, abra o Gerenciador de Add-on, e você verá um novo botão rotulado "Update l10n" próximo a cada add-on que você instalou:

Clique no botão e você será instado a enviar um arquivo .properties para aquele add-on. Se você fornecer um novo arquivo, o locale do add-on será atualizado com o novo arquivo.

Limitações

A localização atual suportada é o primeiro passo  ao inteiro suporte, e contem uma série de limitações.

  • Não há suporte para scripts de conteúdo ou arquivos CSS: no momento, você pode localizar strings que aparecem nos arquivos JavaScript que podem require() módulos SDK e em HTML.

  • A configuração dos arquivos de localidade é global por um add-on. Isto significa que um módulo não pode sobreescrever uma tradução mais geral: então um módulo informal.js não pode especificar que "hello_id" ocorrendo em seu código deveria ser traduzida para "Hi!".

  • A ferramenta SDK compila os arquivos de localidade em um formato JSON quando produzindo um XPI. Isso significa que traduções não podem localizar um add-on dando o XPI sozinho, mas deve ser dado acesso ao fonte do add-on.

  • O desenvolvedor deve manualmente montar o conjunto de strings localizáveis compõe os arquivos de localidade.

Veja também - para desenvolvedores que localização em add-on que não são do SDK

Etiquetas do documento e colaboradores

Etiquetas: 
 Colaboradores desta página: Pheanor
 Última atualização por: Pheanor,