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 ao usuário em um arquivo chamado messages.json. Cada vez que você adiciona uma nova localidade, um arquivo de mensagens é adicionado em um diretório chamado /_locales/_localeCode_, em que localeCode é um código, como en para o inglês.

Confira a hierarquia de arquivos de uma extensão internacionalizada que oferece suporte ao inglês (en), espanhol (es) e coreano (ko):

Oferecer suporte a vários idiomas

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

Para internacionalizar essa extensão, nomeie cada string visível para o usuário e coloque-a em um arquivo de mensagens. O manifesto da extensão, os arquivos CSS e o código JavaScript usam o nome de cada string para acessar a versão localizada.

Confira como a extensão fica quando é internacionalizada (ela ainda tem apenas strings em inglês):

Algumas observações sobre a internacionalização:

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

• Nos arquivos manifest.json e CSS, consulte uma string chamada messagename, como esta:

  __MSG_messagename__
  

• No código JavaScript da sua extensão ou app, consulte uma string chamada messagename, como esta:

  chrome.i18n.getMessage("messagename")
  

• Em cada chamada para getMessage(), é possível fornecer até nove strings para serem incluídas na mensagem. Consulte Exemplos: getMessage para mais 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 predefinidas.

• Em messages.json, cada string visível para o usuário tem um nome, um item "mensagem" e um item "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 "description" opcional ajuda os tradutores, que podem não conseguir ver como a string é usada na sua 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 dela é simples. Você copia messages.json, o traduz e coloca a cópia em um novo diretório em /_locales. Por exemplo, para oferecer suporte ao espanhol, basta colocar uma cópia traduzida de messages.json em /_locales/es. A figura a seguir mostra a extensão anterior com uma nova tradução em espanhol.

Mensagens predefinidas

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

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

A tabela a seguir descreve cada mensagem predefinida.

Nome da mensagem	Descrição
@@extension_id	O ID da extensão ou do app. Você pode usar essa string para criar URLs de 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_locale	A localidade atual. Você pode usar essa string para criar URLs específicos à localidade.
@@bidi_dir	A direção do texto para a localidade atual: "ltr" para idiomas da esquerda para a direita, como o inglês, ou "rtl" para idiomas da direita para a esquerda, como o árabe.
@@bidi_reversed_dir	Se o @@bidi_dir for "ltr", será "rtl". Caso contrário, será "ltr".
@@bidi_start_edge	Se @@bidi_dir for "ltr", isso significa "esquerda". Caso contrário, será "direita".
@@bidi_end_edge	Se @@bidi_dir for "ltr", será "direita". Caso contrário, será "esquerda".

Confira um exemplo de uso de @@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 vai ficar assim:

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

Confira um exemplo de uso de 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 da esquerda para a direita, como o inglês, as linhas em negrito ficam assim:

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

Localidades

Você pode escolher entre muitas localidades, incluindo algumas (como en) que permitem que uma única tradução ofereça suporte a várias variações de um idioma (como en_GB e en_US).

É possível localizar sua extensão para qualquer localidade com suporte da Chrome Web Store. Se sua localidade não estiver 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 de 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

Não é necessário definir todas as strings para todas as localidades com suporte. Contanto que o arquivo messages.json da localidade padrão tenha um valor para cada string, a extensão ou o app vão ser executado, não importa quão escassa seja a tradução. Confira como o sistema de extensão procura uma mensagem:

1. Pesquise o arquivo de mensagens (se houver) para encontrar a localidade de preferência do usuário. Por exemplo, quando a localidade do Google Chrome está definida como inglês britânico (en_GB), o sistema procura primeiro a mensagem em /_locales/en_GB/messages.json. Se esse arquivo existir e a mensagem estiver presente, o sistema não vai procurar mais nada.
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 vai procurar no arquivo de mensagens en. Se esse arquivo existir e a mensagem estiver lá, o sistema não vai procurar mais.
3. Pesquise a localidade padrão no arquivo de mensagens. Por exemplo, se o "default_locale" da extensão estiver definido como "es" e nem /_locales/en_GB/messages.json nem /_locales/en/messages.json contiverem a mensagem, a extensão vai usar a mensagem de /_locales/es/messages.json.

Na figura a seguir, a mensagem "colores" está em todas as três localidades que a extensão oferece suporte, mas "extName" está em apenas duas delas. Quando um usuário que usa o Google Chrome em inglês dos EUA vê o rótulo "Colors", um usuário que usa o inglês britânico vê "Colours". Os usuários do inglês americano e do inglês britânico veem o nome da extensão "Hello World". Como o idioma padrão é o espanhol, os usuários que usam o Google Chrome em qualquer idioma que não seja o inglês veem o rótulo "Colores" e o nome da extensão "Hola mundo".

Definir a localidade do navegador

Para testar as traduções, defina a localidade do navegador. Esta seção explica como definir a localidade no Windows, Mac OS, Linux e ChromeOS.

Windows

É possível mudar a localidade usando um atalho específico ou a interface do Google Chrome. A abordagem de atalho é mais rápida, depois de configurada, e permite usar vários idiomas de uma só vez.

Usar um atalho específico da localidade

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

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

3. Mude as propriedades do atalho para que o campo "Target" especifique as flags --lang e --user-data-dir. O alvo deve 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 abra o Google Chrome em espanhol (es), crie um com o nome chrome-es e a seguinte meta:

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

Você pode criar quantos atalhos quiser, facilitando os testes 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

Observação:especificar --user-data-dir é opcional, mas útil. Ter um diretório de dados por localidade permite executar o navegador em vários idiomas ao mesmo tempo. Uma desvantagem é que, como os dados das localidades não são compartilhados, você precisa instalar a extensão várias vezes, uma por localidade, o que pode ser desafiador quando você não fala o idioma. Para mais informações, consulte Criar e usar perfis.

Usar a interface

Veja como mudar a localidade usando a interface do Google Chrome para Windows:

1. Ícone do app > Opções
2. Escolha a guia Under the Hood.
3. Role até Conteúdo da Web.
4. Clique em Mudar as configurações de idioma e fonte.
5. Escolha a guia Idiomas.
6. Use o menu suspenso para definir o idioma do Google Chrome.
7. Reinicie o Chrome.

Mac OS

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

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

Linux

Para mudar a localidade no Linux, primeiro saia do Google Chrome. Em seguida, em uma linha, defina a variável de ambiente LANGUAGE e inicie o Google Chrome. Exemplo:

LANGUAGE=es ./chrome

ChromeOS

Para mudar a localidade no ChromeOS:

1. Na bandeja do sistema, escolha Configurações.
2. Na seção Idiomas e entrada, escolha o menu suspenso Idioma.
3. Se o idioma não estiver na lista, clique em Adicionar idiomas e adicione.
4. Depois de adicionar, clique no item de menu de três pontos Mais ações ao lado do 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

Confira exemplos de internacionalização no diretório examples/api/i18n. Para conferir um exemplo completo, consulte examples/extensions/news. Para conferir outros exemplos e receber ajuda para visualizar o código-fonte, consulte Exemplos.

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 accept-languages do navegador e os exibe como uma string, separando cada accept-language com ','.

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

Para saber mais sobre como chamar getAcceptLanguages(), consulte a referência da API.

detectLanguage()

O código a seguir detecta até três idiomas da string especificada 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 e versões mais recentes

Um código de idioma ISO, como en ou fr. Para conferir uma lista completa de idiomas aceitos por esse método, consulte kLanguageInfoTable. Para um idioma desconhecido, und será retornado, o que significa que [porcentagem] do texto é desconhecido para a CLD.

Tipo

string

Métodos

detectLanguage()

Promessa Chrome 47 e versões mais recentes

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

Detecta o idioma do texto fornecido usando o CLD.

Parâmetros

• texto

  string

  String de entrada do usuário a ser traduzida.

• callback

  função opcional

  O parâmetro callback tem este formato:

  (result: object) => void

  • resultado

    objeto

    Objeto LanguageDetectionResult que contém a confiabilidade do idioma detectado e a matriz de DetectedLanguage

    • isReliable

      booleano

      Confiabilidade do idioma detectado pelo CLD

    • linguagens

      object[]

      matriz de detectedLanguage

      • language

        string

      • porcentagem

        number

        A porcentagem do idioma detectado

Retorna

• Promise<object>

  Chrome 99 e versões mais recentes

  As promessas têm suporte no Manifest V3 e versões mais recentes, mas os callbacks são fornecidos para compatibilidade com versões anteriores. Não é possível usar os dois na mesma chamada de função. A promessa é resolvida com o mesmo tipo transmitido para o callback.

getAcceptLanguages()

Promessa

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

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

Parâmetros

• callback

  função opcional

  O parâmetro callback tem este formato:

  (languages: string[]) => void

  • linguagens

    string[]

    Matriz de LanguageCode

Retorna

• Promise<LanguageCode[]>

  Chrome 99 e versões mais recentes

  As promessas têm suporte no Manifest V3 e versões mais recentes, mas os callbacks são fornecidos para compatibilidade com versões anteriores. Não é possível usar os dois na mesma chamada de função. A promessa é resolvida com o mesmo tipo transmitido para o callback.

getMessage()

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

Recebe a string localizada para a mensagem especificada. Se a mensagem estiver ausente, esse método vai retornar uma string vazia ("''). Se o formato da chamada getMessage() estiver incorreto, por exemplo, messageName não for uma string ou a matriz substitutions tiver mais de 9 elementos, esse método vai 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.

• opções

  objeto opcional

  Chrome 79 e versões mais recentes
  • escapeLt

    booleano opcional

    Escape < na tradução para <. Isso se aplica apenas à mensagem, não aos marcadores de posição. Os desenvolvedores podem usar esse recurso se a tradução for usada 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. Isso é 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.