chrome.i18n

Descrição

Manifesto

Se uma extensão tiver um diretório /_locales, o manifesto precisará definir "default_locale".

Conceitos e uso

Você precisa colocar todas as strings visíveis para o usuário em um arquivo chamado messages.json. Cada vez adicionar uma nova localidade, você vai adicionar um arquivo de mensagens no diretório /_locales/_localeCode_, em que localeCode é um código como en para inglês.

Veja a hierarquia de arquivos de uma extensão internacionalizada compatível com inglês (en) e espanhol (es) e coreano (ko):

Compatibilidade com vários idiomas

Digamos que você tenha uma extensão com os arquivos mostrados na figura a seguir:

Para internacionalizar esta extensão, nomeie cada string visível ao usuário e coloque-a em uma mensagem . O manifesto, os arquivos CSS e o código JavaScript da extensão usam o nome de cada string para receber o versão localizada.

Veja como a extensão aparece quando é internacionalizada (observe que ela ainda tem apenas Strings em inglês):

<img "__msg_extname__",="" "default_locale"="" "pt-BR".="" "nome_da_extensão"."="" "hello="" _locates=&quot;&quot; a=&quot;&quot; alt="No arquivo manifest.json, " and=&quot;&quot; estado="" changed=&quot;&quot; chrome.i18n.getmessage("extname").="" defines=&quot;&quot; en=&quot;&quot; file=&quot;&quot; file,=&quot;&quot; has=&quot;&quot; hello=&quot;&quot; in=&quot;&quot; item=&quot;&quot; javascript=&quot;&quot; messages.json=&quot;&quot; named=&quot;&quot; new="" src=&quot;/static/docs/extensions/mv2/reference/i18n/images/i18n-after-1.gif&quot; the=&quot;&quot; to=&quot;&quot; valor="" mundo"="" />

Algumas observações sobre internacionalização:

• Use qualquer uma das localidades compatíveis. Se você usar uma localidade sem suporte, o Google Chrome a ignorar.

• Em arquivos manifest.json e CSS, consulte uma string chamada messagename desta forma:

  __MSG_messagename__
  

• No código JavaScript da sua extensão ou aplicativo, consulte uma string chamada messagename desta forma:

  chrome.i18n.getMessage("messagename")
  

• Em cada chamada para getMessage(), você pode informar até nove strings a serem incluídas na mensagem. Consulte Exemplos: getMessage para mais detalhes.

• Algumas mensagens, como @@bidi_dir e @@ui_locale, são fornecidas pela internacionalização sistema. Consulte a seção Mensagens predefinidas para ver uma lista completa de nomes de mensagens predefinidos.

• Em messages.json, cada string visível ao usuário tem um nome, uma "mensagem". e um item opcional, &quot;description&quot; do item de linha. O nome é uma chave, como "extName" ou "string_de_pesquisa" que identifica fio. A "mensagem" especifica o valor da string nessa localidade. A "descrição" opcional oferece ajuda aos tradutores, que podem não conseguir ver como a string é usada no . Exemplo:

  {
    "search_string": {
      "message": "hello%20world",
      "description": "The string we search for. Put %20 between words that go together."
    },
    ...
  }
  

Para mais informações, consulte Formatos: mensagens específicas de localidade.

Depois que uma extensão é internacionalizada, a tradução é simples. Você copia messages.json, traduza-o e coloque a cópia em um novo diretório em /_locates. Por exemplo, para dar suporte Espanhol, coloque uma cópia traduzida de messages.json no nome de /_locates/es. A figura a seguir mostra a extensão anterior com uma nova tradução em espanhol.

Mensagens predefinidas

O sistema de internacionalização fornece algumas mensagens predefinidas para ajudar na localização. Esses incluem @@ui_locale, para que você possa detectar a localidade atual da interface e algumas mensagens @@bidi_... que permitem detectar a direção do texto. As últimas mensagens têm nomes semelhantes às constantes no API de gadgets BIDI (bidirecional).

A mensagem especial @@extension_id pode ser usada nos arquivos CSS e JavaScript, independentemente de o ou o aplicativo está localizado. Essa mensagem não funciona em arquivos de manifesto.

A tabela a seguir descreve cada mensagem predefinida.

Este é um exemplo de como usar @@extension_id em um arquivo CSS para criar um URL:

body {
  background-image:url('chrome-extension://__MSG_@@extension_id__/background.png');
}

Se o ID da extensão for abcdefghijklmnopqrstuvwxyzabcdef, a linha em negrito no código anterior o snippet passa a ser:

  background-image:url('chrome-extension://abcdefghijklmnopqrstuvwxyzabcdef/background.png');

Confira um exemplo de como usar mensagens @@bidi_* em um arquivo CSS:

body {
  direction: __MSG_@@bidi_dir__;
}

div#header {
  margin-bottom: 1.05em;
  overflow: hidden;
  padding-bottom: 1.5em;
  padding-__MSG_@@bidi_start_edge__: 0;
  padding-__MSG_@@bidi_end_edge__: 1.5em;
  position: relative;
}

Para idiomas com escrita da esquerda para a direita, como o inglês, as linhas em negrito se tornam:

  dir: ltr;
  padding-left: 0;
  padding-right: 1.5em;

Localidades

É possível escolher entre muitas localidades, incluindo algumas (como en) que permitem que uma única tradução seja compatível com diversas variações de um idioma (como en_GB e en_US).

Você pode localizar sua extensão para qualquer localidade suportada pela Chrome Web Store. Caso sua localidade não esteja listada aqui, escolha a alternativa mais próxima. Por exemplo, se a localidade padrão da sua extensão for "de_CH", escolha "de" na Chrome Web Store.

Pesquisar mensagens

Você não precisa definir todas as strings para cada localidade compatível. Contanto que a configuração O arquivo messages.json tem um valor para cada string. Sua extensão ou app será executado de qualquer maneira uma tradução esparsa. Confira como o sistema de extensões pesquisa uma mensagem:

1. Pesquise o local de preferência do usuário no arquivo de mensagens (se houver). Por exemplo, quando o Google A localidade do Chrome está definida como inglês britânico (en_GB). O sistema primeiro procura a mensagem em /_locates/en_GB/messages.json. Se o arquivo existir e a mensagem estiver lá, o sistema procurará não mais.
2. Se a localidade de preferência do usuário tiver uma região (ou seja, se a localidade tiver um sublinhado: _), pesquise a localidade sem essa região. Por exemplo, se o arquivo de mensagens en_GB não existir ou não contiver a mensagem, o sistema procurará no arquivo de mensagens en. Se esse arquivo existir e a mensagem está lá, o sistema não busca mais nada.
3. Pesquise a localidade padrão no arquivo de mensagens. Por exemplo, se o código de acesso "default_locale" é definido como "es", e nem /_locates/en_GB/messages.json nem /_locates/en/messages.json contém a mensagem, a extensão usa a mensagem de /_locates/es/messages.json

Na figura a seguir, a mensagem chamada “colores” está nas três localidades em que a extensão suporta, mas "extName" está em apenas duas localidades. Sempre que um usuário executar o Google Chrome nos EUA O inglês tem o rótulo "Colors", e um usuário do inglês britânico vê "Colors". Tanto o inglês americano quanto o Usuários de inglês britânico veem o nome da extensão "Hello World". Como o idioma padrão é o espanhol, usuários que executam o Google Chrome em qualquer idioma diferente do inglês veem o marcador "Colores" e a extensão com o nome "Hola mundo".

Definir a localidade do navegador

Para testar traduções, convém definir a localidade do navegador. Nesta seção, explicamos como definir a localidade Windows, Mac OS X, Linux e ChromeOS.

Windows

É possível mudar a localidade usando um atalho específico dela ou a interface do Google Chrome. A mais rápida, depois de configurada, e permite usar vários idiomas ao mesmo tempo.

Usar um atalho específico da localidade

Para criar e usar um atalho que inicie o Google Chrome com uma localidade específica:

1. Faça uma cópia do atalho do Google Chrome que já está na sua área de trabalho.
2. Renomeie o novo atalho para corresponder à nova localidade.

3. Altere as propriedades do atalho para que o campo "Destino" especifique --lang e --user-data-dir. O destino será parecido com este:

   path_to_chrome.exe --lang=locale --user-data-dir=c:\locale_profile_dir
   

4. Inicie o Google Chrome clicando duas vezes no atalho.

Por exemplo, para criar um atalho que inicie o Google Chrome em espanhol (es), você pode criar um atalho chamado chrome-es que tem o seguinte destino:

path_to_chrome.exe --lang=es --user-data-dir=c:\chrome-profile-es

Você pode criar quantos atalhos quiser, o que facilita o teste em vários idiomas. Por exemplo:

path_to_chrome.exe --lang=en --user-data-dir=c:\chrome-profile-en
path_to_chrome.exe --lang=en_GB --user-data-dir=c:\chrome-profile-en_GB
path_to_chrome.exe --lang=ko --user-data-dir=c:\chrome-profile-ko

Usar a interface

Veja como alterar a localidade usando a interface do usuário no Google Chrome para Windows:

1. Ícone do app > Opções
2. Selecione a guia Configurações avançadas.
3. Role para baixo até Conteúdo da Web.
4. Clique em Alterar configurações de fonte e idioma.
5. Escolha a guia Idiomas.
6. Use o menu suspenso para definir o idioma do Google Chrome
7. Reiniciar o Chrome

Mac OS X

Para alterar a localidade no Mac, use as preferências do sistema.

1. No menu Apple, escolha Preferências do Sistema.
2. Na seção Pessoal, selecione Internacional.
3. Escolha o idioma e o local
4. Reiniciar o Chrome

Linux

Para alterar a localidade no Linux, saia do Google Chrome primeiro. Depois, tudo em uma única linha, defina LANGUAGE variável de ambiente e iniciar o Google Chrome. Exemplo:

LANGUAGE=es ./chrome

ChromeOS

Para mudar a localidade no ChromeOS:

1. Na bandeja do sistema, selecione Configurações.
2. Na seção Idiomas e entrada, selecione o menu suspenso Idioma.
3. Se o idioma não estiver na lista, clique em Adicionar idiomas e adicione-o.
4. Depois de adicionar, clique no item de menu de três pontos Mais ações ao lado do seu idioma e escolha Exibir o ChromeOS neste idioma.
5. Clique no botão Reiniciar que aparece ao lado do idioma definido para reiniciar o ChromeOS.

Exemplos

Veja exemplos simples de internacionalização no diretório examples/api/i18n. Para um exemplo completo, consulte examples/extensions/news. Para outros exemplos e para obter ajuda na visualização do código-fonte, consulte Amostras.

getMessage()

O código a seguir recebe uma mensagem localizada do navegador e a exibe como uma string. Ela substitui dois marcadores de posição na mensagem pelas strings "string1" e "string2".

function getMessage() {
  var message = chrome.i18n.getMessage("click_here", ["string1", "string2"]);
  document.getElementById("languageSpan").innerHTML = message;
}

Confira como fornecer e usar uma única string:

  // In JavaScript code
  status.innerText = chrome.i18n.getMessage("error", errorDetails);

"error": {
  "message": "Error: $details$",
  "description": "Generic error template. Expects error parameter to be passed in.",
  "placeholders": {
    "details": {
      "content": "$1",
      "example": "Failed to fetch RSS feed."
    }
  }
}

Para mais informações sobre marcadores de posição, consulte a página Mensagens específicas de localidade. Para detalhes sobre chamando getMessage(), consulte a referência da API.

getAcceptLanguages()

O código a seguir recebe os idiomas de aceitação do navegador e os exibe como uma string pelo separando cada aceita-idioma com ",".

function getAcceptLanguages() {
  chrome.i18n.getAcceptLanguages(function(languageList) {
    var languages = languageList.join(",");
    document.getElementById("languageSpan").innerHTML = languages;
  })
}

Para detalhes sobre como chamar getAcceptLanguages(), consulte a Referência da API.

detectLanguage()

O código a seguir detecta até três idiomas da string fornecida e exibe o resultado como strings separadas por novas linhas.

function detectLanguage(inputText) {
  chrome.i18n.detectLanguage(inputText, function(result) {
    var outputLang = "Detected Language: ";
    var outputPercent = "Language Percentage: ";
    for(i = 0; i < result.languages.length; i++) {
      outputLang += result.languages[i].language + " ";
      outputPercent +=result.languages[i].percentage + " ";
    }
    document.getElementById("languageSpan").innerHTML = outputLang + "\n" + outputPercent + "\nReliable: " + result.isReliable;
  });
}

Para mais detalhes sobre como chamar detectLanguage(inputText), consulte a referência da API.

chrome.i18n.detectLanguage(
  text: string,
  callback?: function,
)

chrome.i18n.getAcceptLanguages(
  callback?: function,
)

chrome.i18n.getMessage(
  messageName: string,
  substitutions?: any,
  options?: object,
)

chrome.i18n.getUILanguage()