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. Sempre que você adiciona uma nova localidade, você adiciona um arquivo de mensagens em um diretório chamado /_locales/_localeCode_, em que localeCode é um código como en para inglês.

Confira a hierarquia de arquivos de uma extensão internacionalizada compatível com inglês (en), 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 essa extensão, nomeie cada string visível ao usuário e coloque-a em um arquivo de mensagens. O manifesto, os arquivos CSS e o código JavaScript da extensão usam o nome de cada string para receber a versão localizada.

Veja como a extensão fica quando é internacionalizada. Observe que ela ainda tem apenas strings em inglês:

<img "__msg_extname__",="" "default_locale"="" "en".="" "extname"."="" "hello="" _locates="" a="" alt="No arquivo manifest.json, " and="" been="" changed="" chrome.i18n.getmessage("extname").="" "extname"." en="" file="" file,="" new en="" file/" javascript/extensions/" new en="" file="gif/

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 maneira:

    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 ver detalhes.

  • Algumas mensagens, como @@bidi_dir e @@ui_locale, são fornecidas pelo sistema de internacionalização. 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, um item de "mensagem" e um item de "descrição" opcional. O nome é uma chave como "extName" ou "search_string" que identifica a string. A "message" especifica o valor da string nessa localidade. A "descrição" opcional fornece ajuda aos tradutores, que podem não conseguir ver como a string é usada na extensão. 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, traduz e coloca a cópia em um novo diretório em /_locates. Por exemplo, para oferecer compatibilidade com o espanhol, basta colocar uma cópia traduzida de messages.json em /_locates/es. A figura a seguir mostra a extensão anterior com uma nova tradução para o 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. Eles 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 na API de gadgets BIDI (bidirecional).

A mensagem especial @@extension_id pode ser usada nos arquivos CSS e JavaScript, independentemente de a extensão ou o app estar localizado ou não. Essa mensagem não funciona em arquivos de manifesto.

A tabela a seguir descreve cada mensagem predefinida.

Nome da mensagemDescrição
@@extension_idA extensão ou o ID do aplicativo. Você pode usar essa string para criar 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 criar 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 o 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 a @@bidi_dir for "ltr", o valor será "left". Caso contrário, será "right".
@@bidi_end_edgeSe a @@bidi_dir for "ltr", o valor será "right". Caso contrário, será "left".

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 snippet de código anterior ficará:

  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
he Hebraico
hi Hindi
h Croata
hu Húngaro
id Indonésio
para recebê-los. 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 o arquivo messages.json da localidade padrão tenha um valor para cada string, sua extensão ou app será executado, independente da escassez de tradução. 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 a localidade do Google Chrome está definida como inglês britânico (en_GB), o sistema primeiro procura a mensagem em /_locates/en_GB/messages.json. Se esse arquivo existir e a mensagem estiver lá, o sistema não procurará mais.
  2. Se a localidade preferida do usuário tiver uma região (ou seja, se 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 tiver a mensagem, o sistema vai procurar no arquivo de mensagens en. Se esse arquivo existir e a mensagem estiver lá, o sistema não procurará mais.
  3. Pesquise a localidade padrão no arquivo de mensagens. Por exemplo, se "default_locale" da extensão estiver definido como "es", e nem /_locates/en_GB/messages.json nem /_locates/en/messages.json contiverem a mensagem, a extensão usará a mensagem de /_locates/es/messages.json.

Na figura a seguir, a mensagem chamada "colores" está em todas as três localidades compatíveis com a extensão, mas "extName" está em apenas duas delas. Sempre que um usuário executando o Google Chrome em inglês encontra o marcador "Colors", um usuário de inglês britânico vê "Cores". Tanto usuários de inglês americano quanto usuários de inglês britânico verão o nome da extensão "Hello World". Como o idioma padrão é o espanhol, os usuários que executam o Google Chrome em qualquer idioma diferente do inglês veem o marcador "Colores" e o nome da extensão "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. Esta seção informa como definir a localidade no 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 abordagem de atalho é 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. Mude as propriedades do atalho para que o campo "Destino" especifique as flags --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 tenha 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. 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 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, defina a variável de ambiente IDIOMA e inicie o Google Chrome em uma só linha. 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 ver um exemplo completo, consulte examples/extensions/news. Para outros exemplos e para receber ajuda com a 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. Ele 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 como chamar 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, separando cada idioma aceito 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 mostra 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 versão mais recente

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+
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

        boolean

        O CLD detectou confiabilidade da linguagem

      • linguagens

        objeto[]

        matriz de detectLanguage

        • language

          string

        • porcentagem

          number

          A porcentagem do idioma detectado

Retorna

  • Promise<object>

    Chrome 99 ou versões mais recentes

    O Manifesto V3 e versões mais recentes oferecem suporte a promessas, mas callbacks são fornecidos para 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 para o callback.

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<LanguageCode[]>

    Chrome 99 ou versões mais recentes

    O Manifesto V3 e versões mais recentes oferecem suporte a promessas, mas callbacks são fornecidos para 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 para o callback.

getMessage()

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

Extrai a string localizada para a mensagem especificada. Se a mensagem estiver ausente, este 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 overrides tiver mais de nove elementos, esse 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.

  • do modelo.

    objeto opcional

    Chrome 79 ou versão mais recente
    • 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.