path: root/files/pt-br/mozilla/add-ons/sdk/tutorials/l10n/index.html

---
title: Localização
slug: Mozilla/Add-ons/SDK/Tutorials/l10n
tags:
  - Add-on SDK
  - Localização
translation_of: Archive/Add-ons/Add-on_SDK/Tutorials/l10n
---
<p>O SDK suporta localização de strings que aparecem no:</p>

<ul>
 <li><a href="/en-US/Add-ons/SDK/Tutorials/l10n#Using_Localized_Strings_in_JavaScript">o código JavaScript principal do seu add-on</a></li>
 <li><a href="/en-US/Add-ons/SDK/Tutorials/l10n#Using_Localized_Strings_in_HTML">arquivos HTML empacotados com seu add-on</a></li>
 <li><a href="/en-US/Add-ons/SDK/Tutorials/l10n#Using_Localized_Strings_in_Preferences">os campos <code>title</code> e <code>description</code> das preferências do seu add-on's</a>.</li>
</ul>

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

<h2 id="Strings_de_Localização">Strings de Localização</h2>

<p>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:</p>

<ul>
 <li>use o formato <a href="http://en.wikipedia.org/wiki/.properties"><code>.properties</code></a></li>
 <li>são chamados "xx-YY.properties", onde "xx-YY" é o nome da<a href="https://wiki.mozilla.org/L10n:Locale_Codes"> localidade</a> em questão</li>
 <li>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 <code>identificador=tradução</code>.</li>
 <li>precisa usar UTF-8 sem codificação BOM</li>
</ul>

<p>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.</p>

<p>Você adiciona dois arquivos ao diretório "locale":</p>

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

<p>"en-US.properties" contém isto:</p>

<pre>hello_id= Hello!
</pre>

<p>"fr-FR.properties" contém isto:</p>

<pre>hello_id= Bonjour !
</pre>

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

<h2 id="Usando_Strings_de_Localização_no_HTML">Usando Strings de Localização no HTML</h2>

<div class="note">
<p>Este exemplo usa a API <a href="https://developer.mozilla.org/en-US/Add-ons/SDK/Low-Level_APIs/ui_button_action">action button</a>, que está disponível somente do Firefox 29 em diante.</p>
</div>

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

<pre class="brush: html">&lt;html&gt;
  &lt;body&gt;
    &lt;h1 data-l10n-id="hello_id"&gt;&lt;/h1&gt;
  &lt;/body&gt;
&lt;/html&gt;
</pre>

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

<pre class="brush: js">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")
});</pre>

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

<p><img alt="" src="https://mdn.mozillademos.org/files/7663/bonjour.png" style="height: 160px; width: 255px;"><img alt="" src="https://mdn.mozillademos.org/files/7665/hello.png" style="height: 160px; width: 255px;"></p>

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

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

<pre>hello_id= &lt;blink&gt;Hello!&lt;/blink&gt;
</pre>

<h3 id="Localizando_Atributos_de_Elementos">Localizando Atributos de Elementos</h3>

<div class="geckoVersionNote">Esta característica é nova no Firefox 39</div>

<p><br>
 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:</p>

<pre>hello_id.accesskey= H</pre>

<p>Os seguintes atributos são suportados:</p>

<ul>
 <li><strong>accesskey</strong></li>
 <li><strong>alt</strong></li>
 <li><strong>label</strong></li>
 <li><strong>title</strong></li>
 <li><strong>placeholder</strong></li>
</ul>

<p><span id="result_box" lang="pt"><span class="hps">Além disso, a</span> <span class="hps">localização do</span>s atributos <span class="hps">ARIA</span> <span class="hps">aria</span><span>-label,</span> <span class="hps">aria</span><span class="atn">-</span><span>valuetext</span> <span class="hps">e</span> <span class="hps">aria</span><span class="atn">-</span><span>moz</span><span class="atn">-</span><span>dica</span> <span class="hps">são suportados</span> <span class="hps">com os mesmos</span> apelidos que <span class="hps">no</span> <span class="hps">Firefox</span> <span class="hps">OS</span><span>:</span></span></p>

<ul>
 <li><strong>ariaLabel</strong></li>
 <li><strong>ariaValueText</strong></li>
 <li><strong>ariaMozHint</strong></li>
</ul>

<h2 id="Usando_Strings_de_Localização_no_JavaScript">Usando Strings de Localização no JavaScript</h2>

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

<pre class="brush: js">var _ = require("sdk/l10n").get;
console.log(_("hello_id!"));</pre>

<p><span>A atribuição de "_" em particular não é requerida, mas é uma convenção da ferramente <a href="https://www.gnu.org/software/gettext/gettext.html">gettext </a>e torna possível trabalhar com ferramentas existentes que esperam "_" para indicar Strings de Localização.</span></p>

<ol>
 <li>Importe o módulo <code>l10n</code>, atribua sua função <code>get</code> o "<code>_</code>" (underscore).</li>
 <li>Envolva todas as referências a Strings de Localização com uma função <code>_()</code>.</li>
</ol>

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

<pre>info: Hello!
</pre>

<pre>info: Bonjour !
</pre>

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

<h3 id="Plurais">Plurais</h3>

<p>O módulo <code>l10n</code> 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":</p>

<pre>one tomato
no tomatoes
two tomatoes
</pre>

<p>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:</p>

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

<p>O SDK usa dados do <a href="http://cldr.unicode.org/index">Unicode CLDR</a> para descrever as diferentes formas de plural usadas pelas diferentes línguas.</p>

<h4 id="Formas_Plurais_do_Unicode_CLDR">Formas Plurais do Unicode CLDR</h4>

<p>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: <em>zero, one, two, few, many, </em>e <em>other</em>.</p>

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

<pre>one   → n is 1;
other → everything else
</pre>

<p>A Russa usa quatro formas, que podem ser descritas como se segue:</p>

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

<p>As regras de plural para todas as línguas podem ser encontrada na página de <a href="http://unicode.org/repos/cldr-tmp/trunk/diff/supplemental/language_plural_rules.html">Regras para Plural das Línguas</a> do CLDR (embora esta tabela esteja desatualizada se comparada com a <a href="http://unicode.org/repos/cldr/trunk/common/supplemental/plurals.xml">CLDR XML source</a>).</p>

<h4 id="Formas_Plurais_no_SDK">Formas Plurais no SDK</h4>

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

<pre class="brush: js">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));</pre>

<p>No arquivo <code>.properties</code> 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" <strong>não</strong> leva palavra reservada do CLDR:</p>

<pre># en-US translations
tomato_id[one]= %d tomato
tomato_id= %d tomatoes
</pre>

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

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

<p>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 <code>ru-RU.properties</code>. Então ele pega e retorna a localização apropriada para a contagem fornecida.</p>

<h3 id="Placeholders">Placeholders</h3>

<p>O módulo <code>l10n</code> 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:</p>

<pre># en-US translations
hello_id= Hello <strong>%s</strong>!
</pre>

<pre># fr-FR translations
hello_id= Bonjour <strong>%s</strong> !
</pre>

<p>Para usar placeholders, forneça uma string placeholder depois do identificador:</p>

<pre class="brush: js">var _ = require("sdk/l10n").get;
console.log(_("hello_id", "Bob"));
console.log(_("hello_id", "Alice"));</pre>

<p>Na localidade Inglês "en-US", isto nos é dado:</p>

<pre>info: Hello Bob!
info: Hello Alice!
</pre>

<p>No "fr-FR" nós conseguimos:</p>

<pre>info: Bonjour Bob !
info: Bonjour Alice !
</pre>

<h3 id="Ordenando_Placeholders">Ordenando Placeholders</h3>

<p>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.</p>

<p>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.</p>

<p>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:</p>

<pre class="brush: js">var _ = require("sdk/l10n").get;
console.log(_("home_town_id", "Bob", "London"));</pre>

<p>An English translator might want to choose between the following:</p>

<pre>"&lt;town_name&gt; is &lt;person_name&gt;'s home town."
</pre>

<pre>"&lt;person_name&gt;'s home town is &lt;town_name&gt;"
</pre>

<p>Para escolher a primeira opção, o arquivo<code> .properties</code> pode ordenar o placeholders como:</p>

<pre>home_town_id= %2s is %1s's home town.
</pre>

<p>Isso nos dá a seguinte saída:</p>

<pre>info: London is Bob's home town.
</pre>

<h2 id="Usando_Strings_de_localização_em_Preferências">Usando Strings de localização em Preferências</h2>

<p>Pela inclusão de uma estrutura <a href="/en-US/Add-ons/SDK/High-Level_APIs/simple-prefs"><code>"preferences"</code> no arquivo "package.json" do seu add-on</a>, você pode definir preferências para seu add-on que o usuário pode ver e editar usando o <a href="https://support.mozilla.org/en-US/kb/Using%20extensions%20with%20Firefox#w_how-to-change-extension-settings">gerenciador de add-ons </a>do Firefox.</p>

<p>Preferências tem um campo <code>title</code> obrigatório e um campo <code>description</code> 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.</p>

<ul>
 <li>
  <p>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  <code>_title</code>, e cujo valor é o título da localidade.</p>
 </li>
 <li>
  <p>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 <code>_description</code>, e cujo valor é a descrição da localidade.</p>
 </li>
</ul>

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

<pre>{
    "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"
}
</pre>

<p>Em seu arquivo "en-US.properties", inclua estes dois itens:</p>

<pre>monster_name_title= Name
monster_name_description= What is the monster's name?
</pre>

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

<pre>monster_name_title= Nom
monster_name_description= Quel est le nom du monstre ?
</pre>

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

<p><img alt="" src="https://mdn.mozillademos.org/files/6525/preference-us.png" style="height: 77px; width: 571px;"></p>

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

<p><img alt="" src="https://mdn.mozillademos.org/files/6523/preference-french.png"></p>

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

<h2 id="Usando_identificadores">Usando identificadores</h2>

<p>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.</p>

<p>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 <code>.properties</code> para todos os locais adicionais que você quiser suportar.</p>

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

<pre>Hello!= Bonjour !
</pre>

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

<p>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.</p>

<h2 id="Locale_Updater">Locale Updater</h2>

<p>O addon <a href="https://github.com/downloads/ochameau/locale-updater/locale-updater.xpi">locale updater</a> 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:</p>

<p><img alt="" src="https://mdn.mozillademos.org/files/6515/locale-updater.png"></p>

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

<h2 id="Limitações">Limitações</h2>

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

<ul>
 <li>
  <p>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 <code>require()</code> módulos SDK e em HTML.</p>
 </li>
 <li>
  <p>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 <code>informal.js</code> não pode especificar que "hello_id" ocorrendo em seu código deveria ser traduzida para "Hi!".</p>
 </li>
 <li>
  <p>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.</p>
 </li>
 <li>
  <p>O desenvolvedor deve manualmente montar o conjunto de strings localizáveis compõe os arquivos de localidade.</p>
 </li>
</ul>

<h2 id="Veja_também_-_para_desenvolvedores_que_localização_em_add-on_que_não_são_do_SDK">Veja também - para desenvolvedores que localização em add-on que não são do SDK</h2>

<ul>
 <li>Como colocar localização em páginas html, arquivos xul, e arquivos js/jsm do add-on bootstrapped: <a href="/en-US/Add-ons/Bootstrapped_extensions#Localization_%28L10n%29">Bootstrapped Extensions :: Localization (L10n)</a></li>
 <li>XUL School Localization Tutorial: <a href="/en-US/docs/Mozilla/Tech/XUL/Tutorial/Localization">DTD/Entities method</a> and <a href="/en-US/docs/Mozilla/Tech/XUL/Tutorial/Property_Files">Properties method</a></li>
 <li><a href="/en-US/docs/Mozilla/Localization/Localizing_an_extension">Localizing an extension</a></li>
</ul>