chrome.i18n

refresh date: 2026-09-25 robots: noindex

Descrição

Use a infraestrutura chrome.i18n para implementar a internacionalização em todo o app ou extensão.

Você precisa colocar todas as strings visíveis ao usuário em um arquivo chamado messages.json. Sempre que você adicionar uma nova localidade, adicione 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 que oferece suporte a inglês (en), espanhol (es) e coreano (ko):

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

Como oferecer suporte a 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 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.

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

<img "__msg_extname__",="" "default_locale"="" "en".="" "extname"."="" "hello="" _locales="" a="" alt="No arquivo manifest.json, " and="" been="" changed="" chrome.i18n.getmessage("extname").="" defines="" en="" file="" file,="" has="" hello="" in="" item="" javascript="" messages.json="" named="" new="" src="/static/images/i18n-after-1.gif" the="" to="" value="" world"="" />

Algumas observações sobre internacionalização:

  • É possível usar qualquer uma das localidades compatíveis. Se você usar uma localidade não compatível, o Google Chrome vai ignorá-la.

  • Em arquivos manifest.json e CSS, faça referência a uma string chamada messagename desta forma:

    __MSG_messagename__

  • No código JavaScript da extensão ou do app, faça referência a uma string chamada messagename desta forma:

    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.

  • No messages.json, cada string visível para o usuário tem um nome, um item "message" e um item "description" opcional. O nome é uma chave, como "extName" ou "search_string", que identifica a string. A "mensagem" especifica o valor da string nessa localidade. A "descrição" opcional ajuda os tradutores, que talvez não consigam 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 ou um app é internacionalizado, a tradução é simples. Copie messages.json, traduza-o e coloque 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.

A imagem é igual à anterior, mas com um novo arquivo em _locales/es/messages.json que contém uma tradução em espanhol das mensagens.

Mensagens predefinidas

O sistema de internacionalização oferece algumas mensagens predefinidas para ajudar você a localizar. Eles incluem @@ui_locale, para que você possa detectar a localidade atual da IU, e algumas mensagens @@bidi_... que permitem detectar a direção do texto. As últimas mensagens 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 estar 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 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 de localidade.
@@bidi_dirA direção do texto para a localidade atual, que pode ser "ltr" para idiomas da esquerda para a direita, como o inglês, ou "rtl" para idiomas da direita para a esquerda, como o japonês.
@@bidi_reversed_dirSe @@bidi_dir for "ltr", o valor será "rtl". Caso contrário, será "ltr".
@@bidi_start_edgeSe @@bidi_dir for "ltr", o valor será "left". Caso contrário, será "right".
@@bidi_end_edgeSe @@bidi_dir for "ltr", o valor será "right". Caso contrário, será "left".

Veja 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 vai ficar assim:

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

Veja 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 orientação da esquerda para a direita, como o português, as linhas em negrito se tornam:

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

Localidades

Você pode escolher entre várias 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).

Locais suportados

É possível usar qualquer uma das localidades aceitas pela Chrome Web Store.

Como pesquisar mensagens

Não é necessário definir todas as strings para todas as localidades compatíveis. Desde que o arquivo messages.json da localidade padrão tenha um valor para cada string, a extensão ou o app será executado, não importa o quão esparsa seja uma tradução. Veja como o sistema de extensões pesquisa uma mensagem:

  1. Pesquise no arquivo de mensagens (se houver) 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 primeiro procura a mensagem em _locales/en_GB/messages.json. Se esse arquivo existir e a mensagem estiver lá, o sistema não vai procurar mais.
  2. Se a localidade preferida do usuário tiver uma região (ou seja, 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 o arquivo de mensagens para encontrar a localidade padrão. 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 usará a mensagem de _locales/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 do Google Chrome em inglês dos EUA vê o rótulo "Colors", um usuário do inglês britânico vê "Colours". Os usuários de inglês dos EUA e do Reino Unido veem 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 que não seja o inglês veem o rótulo "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 es e en mostram entradas para mensagens chamadas

Como definir a localidade do navegador

Para testar as traduções, defina a localidade do navegador. Esta seção mostra como definir a localidade no Windows, Mac OS X, 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 ao mesmo tempo.

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 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. Abra o Google Chrome clicando duas vezes no atalho.

Por exemplo, para criar um atalho que inicie o Google Chrome em espanhol (es), crie um atalho chamado chrome-es com 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
Como usar a IU

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 para baixo até Conteúdo da Web.
  4. Clique em Mudar as configurações de fonte e idioma.
  5. Selecione a guia Idiomas.
  6. Use o menu suspenso para definir o idioma do Google Chrome.
  7. Reiniciar o Chrome

Mac OS X

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. Escolher o idioma e o local
  4. Reiniciar o Chrome

Linux

Para mudar a localidade no Linux, primeiro saia do Google Chrome. Em seguida, em uma única 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 entradas, escolha o menu suspenso Idioma.
  3. Se o idioma não estiver na lista, clique em Adicionar idiomas e inclua-o.
  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 simples de internacionalização no diretório examples/api/i18n. Para um exemplo completo, consulte examples/extensions/news. Para ver outros exemplos e receber ajuda para visualizar o código-fonte, consulte Exemplos.

Exemplos: 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;
}

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

Exemplo: getAcceptLanguages

O código a seguir recebe os idiomas aceitos do navegador e os exibe como uma string, separando cada 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.

Exemplo: detectLanguage

O código a seguir detecta até três idiomas na 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+

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

Tipo

string

Métodos

detectLanguage()

Promise Chrome 47+ 
chrome.i18n.detectLanguage(
  text: string,
  callback?: function,
): Promise<object>

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 optional

    O parâmetro callback é semelhante a: 

    (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 pela CLD

      • idiomas

        object[]

        matriz de detectedLanguage

        • language

          string

        • porcentagem

          número

          A porcentagem do idioma detectado

Retorna

  • Promise<object>

    Chrome 99+

    As promessas só são compatíveis com o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.

getAcceptLanguages()

Promessa 
chrome.i18n.getAcceptLanguages(
  callback?: function,
): Promise<LanguageCode[]>

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

Parâmetros

  • callback

    função optional

    O parâmetro callback é semelhante a: 

    (languages: string[]) => void

    • idiomas

      string[]

      Matriz de LanguageCode

Retorna

  • Promise<LanguageCode[]>

    Chrome 99+

    As promessas só são compatíveis com o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.

getMessage()

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

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, se messageName não for uma string ou se a matriz substitutions tiver mais de nove elementos, esse método vai retornar undefined.

Parâmetros

  • messageName

    string

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

  • substitutions

    any optional

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

  • opções

    objeto optional

    Chrome 79+
    • escapeLt

      booleano opcional

      Escape < na tradução para &lt;. Isso se aplica apenas à mensagem, não aos marcadores de posição. Os desenvolvedores podem usar essa opção se a tradução for usada em um contexto HTML. Os modelos do Closure usados com o Closure Compiler geram isso automaticamente.

Retorna

  • string

    Mensagem localizada para a localidade atual.

getUILanguage()

chrome.i18n.getUILanguage(): string

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