chrome.i18n

Descrição

Use a infraestrutura chrome.i18n para implementar a internacionalização em todo o app ou extensã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):

No diretório de extensão: manifest.json, *.html, *.js, /_locates. No diretório /_locates: os diretórios en, es e ko, cada um com um arquivo messages.json.

Compatibilidade com vários idiomas

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

Um arquivo manifest.json e um arquivo com JavaScript. O arquivo .json tem

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.

É o mesmo da figura anterior, mas com um novo arquivo em /_locates/es/messages.json que contém uma tradução das mensagens 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.

Nome da mensagemDescrição
@@extension_idO ID da extensão ou do app. você pode usar essa string para construir URLs para recursos dentro da extensão. Até mesmo extensões não localizadas podem usar essa mensagem.
Observação:não é possível usar essa mensagem em um arquivo de manifesto.
@@ui_localeA localidade atual. você pode usar essa string para construir URLs específicos da localidade.
@@bidi_dirA direção do texto para a localidade atual, "ltr" para idiomas escritos da esquerda para a direita, como inglês ou "rtl" para idiomas escritos da direita para a esquerda, como o árabe.
@@bidi_reversed_dirSe @@bidi_dir for "ltr", o valor será "rtl". caso contrário, será "ltr".
@@bidi_start_edgeSe @@bidi_dir for "ltr", ele será "left"; caso contrário, está "certo".
@@bidi_end_edgeSe @@bidi_dir for "ltr", esse valor será "right"; caso contrário, é "esquerda".

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.

Código da localidade Idioma (região)
ar Árabe
sou Amárico
bg Búlgaro
bn Bengali
ca Catalão
cs Tcheco
da Dinamarquês
de Alemão
el Grego
en Inglês
en_AU Inglês (Austrália)
en_GB Inglês (Reino Unido)
en_US Inglês (EUA)
es Espanhol
es_419 Espanhol (América Latina e Caribe)
et Estoniano
fa Persa
fi Finlandês
fil Filipino
fr Francês
gu Guzerate
ele Hebraico
hi Hindi
h Croata
hu Húngaro
id Indonésio
it Italiano
ja Japonês
kn Canarês
ko Coreano
lt Lituano
lv Letão
ml Malaiala
mr Marati
ms Malaio
nl Holandês
não Norueguês
pl Polonês
pt_BR Português (Brasil)
pt_PT Português (Portugal)
ro Romeno
ru Russo
sk Eslovaco
sl Esloveno
sr Sérvio
sv Sueco
sw Suaíli
ta Tâmil
te Télugo
th Tailandês
tr Turco
uk Ucraniano
vi Vietnamita
zh_CN Chinês (China)
zh_TW Chinês (Taiwan)

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".

Quatro arquivos: manifest.json e três arquivos messages.json (para es, en e en_GB). Os arquivos &quot;es&quot; e &quot;en&quot; mostram entradas para mensagens chamadas

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.

Tipos

LanguageCode

Chrome 47 ou superior

Um código de idioma ISO, como en ou fr. Para uma lista completa dos idiomas compatíveis com esse método, consulte kLanguageInfoTable. Para um idioma desconhecido, será retornado und, o que significa que [percentual] do texto é desconhecido para o CLD.

Tipo

string

Métodos

detectLanguage()

Promessa Chrome 47 ou superior 
chrome.i18n.detectLanguage(
  text: string,
  callback?: function,
)

Detecta o idioma do texto fornecido usando CLD.

Parâmetros

  • texto

    string

    String de entrada do usuário a ser traduzida.

  • callback

    função opcional

    O parâmetro callback tem esta aparência: 

    (result: object) => void

    • resultado

      objeto

      Objeto LanguageDetectionResult que contém a confiabilidade da linguagem detectada e a matriz de DetectedLanguage

      • isReliable

        booleano

        O CLD detectou confiabilidade da linguagem

      • linguagens

        object[]

        matriz de detectLanguage

        • language

          string

        • porcentagem

          number

          A porcentagem do idioma detectado

Retorna

  • Promise&lt;object&gt;

    Chrome 99 ou versão mais recente

    O Manifesto V3 e versões mais recentes oferecem suporte a promessas, mas callbacks são fornecidos para a compatibilidade com versões anteriores. Não é possível usar ambos na mesma chamada de função. A promessa é resolvida com o mesmo tipo passado ao retorno de chamada.

getAcceptLanguages()

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

Recebe os idiomas aceitos do navegador. Ela é diferente da localidade usada pelo navegador. Para acessar a localidade, use i18n.getUILanguage.

Parâmetros

  • callback

    função opcional

    O parâmetro callback tem esta aparência: 

    (languages: string[]) => void

    • linguagens

      string[]

      Matriz de LanguageCode

Retorna

  • Promise&lt;LanguageCode[]&gt;

    Chrome 99 ou versão mais recente

    O Manifesto V3 e versões mais recentes oferecem suporte a promessas, mas callbacks são fornecidos para a compatibilidade com versões anteriores. Não é possível usar ambos na mesma chamada de função. A promessa é resolvida com o mesmo tipo passado ao retorno de chamada.

getMessage()

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

Extrai a string localizada para a mensagem especificada. Se a mensagem estiver ausente, esse método retornará uma string vazia (''). Se o formato da chamada getMessage() estiver errado, por exemplo, messageName não for uma string ou a matriz substituis tiver mais de nove elementos, o método retornará undefined.

Parâmetros

  • messageName

    string

    O nome da mensagem, conforme especificado no arquivo messages.json.

  • substitutions

    Qualquer opcional

    Até nove strings de substituição, se a mensagem exigir alguma.

  • opções

    objeto opcional

    Chrome 79 ou superior
    • escapeLt

      booleano opcional

      Escape < na tradução para &lt;. Isso se aplica apenas à mensagem em si, não aos marcadores de posição. Os desenvolvedores podem querer usar esse recurso se a tradução for utilizada em um contexto HTML. Os modelos de fechamento usados com o closure Compiler geram isso automaticamente.

Retorna

  • string

    Mensagem localizada para a localidade atual.

getUILanguage()

chrome.i18n.getUILanguage()

Extrai o idioma da interface do navegador. Ele é diferente de i18n.getAcceptLanguages, que retorna os idiomas preferidos do usuário.

Retorna

  • string

    O código de idioma da interface do navegador, como en-US ou fr-FR.