Descrição
Use a infraestrutura chrome.i18n
para implementar a internacionalização em todo o app ou extensão.
É necessário colocar todas as strings visíveis ao usuário em um arquivo chamado messages.json
. Sempre que
você adiciona uma nova localidade, é necessário incluir um arquivo de mensagens em um diretório chamado _locales/_localeCode_
, em que
localeCode é um código como en
para inglês.
Esta é a hierarquia de arquivos de uma extensão internacionalizada que oferece suporte a inglês (en
), espanhol
(es
) e coreano (ko
):
Como 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 ao 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 receber a versão localizada.
Esta é a aparência da extensão quando é internacionalizada. Observe que ela ainda tem apenas strings em inglês:
e
Algumas observações sobre internacionalização:
- É possível usar qualquer uma das localidades aceitas. Se você usar uma localidade sem suporte, o Google Chrome a ignorará.
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 aplicativo, faça referência a uma string chamada messagename, desta forma:
chrome.i18n.getMessage("messagename")
Em cada chamada para
getMessage()
, você pode fornecer até nove strings a serem incluídas na mensagem. Consulte Exemplos: getMessage para ver 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 uma lista completa de nomes de mensagens predefinidas.Em
messages.json
, cada string visível para o 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 "mensagem" especifica o valor da string nessa localidade. A "descrição" opcional oferece ajuda aos tradutores, que podem não 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 ou um app é internacionalizado, a tradução é muito simples. Você copia messages.json
,
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 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 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 ou não. Esta mensagem não funciona em arquivos de manifesto.
A tabela a seguir descreve cada mensagem predefinida.
Nome da mensagem | Descrição |
---|---|
@@extension_id | A extensão ou o ID do app. Use essa string para criar URLs para os recursos dentro da extensão. Mesmo as 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 da localidade. |
@@bidi_dir | A direção do texto da 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 japonês. |
@@bidi_reversed_dir | Se @@bidi_dir for "ltr", será "rtl". Caso contrário, será "ltr". |
@@bidi_start_edge | Se @@bidi_dir for "ltr", será "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 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');
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 escritos da esquerda para a direita, como o inglês, as linhas em negrito ficam:
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
seja compatível com diversas variações de um idioma (como en_GB
e en_US
).
Localidades suportadas
Você pode usar qualquer uma das localidades compatíveis com a Chrome Web Store.
Como pesquisar mensagens
Não é necessário 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 vai ser executada, independentemente
do quão esparsa seja uma tradução. Veja como o sistema de extensões procura uma mensagem:
- Pesquise a localidade 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_locales/en_GB/messages.json
. Se esse arquivo existir e a mensagem estiver lá, o sistema não procurará mais. - Se a localidade de preferência do usuário tiver uma região (ou seja, se ela 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 mensagensen
. Se esse arquivo existir e a mensagem estiver lá, o sistema não vai procurar mais. - Pesquise a localidade padrão no arquivo de mensagens. Por exemplo, se a "default_locale" da extensão for definida como "es" e não
_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 (EUA) vê o rótulo "Cores", um usuário de inglês britânico vê "Cores". Tanto os usuários de inglês (EUA) quanto inglês britânico 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 diferente do inglês veem o rótulo "Colores" e o nome da extensão "Hola mundo".
Como definir a localidade do navegador
Para testar traduções, defina a localidade do navegador. Esta seção ensina como definir a localidade no Windows, Mac OS X, Linux e ChromeOS.
Windows
Você pode mudar a localidade usando um atalho específico da localidade ou a interface do Google Chrome. A abordagem dos atalhos é mais rápida depois da configuração 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:
- Faça uma cópia do atalho do Google Chrome que já está na sua área de trabalho.
- Renomeie o novo atalho para corresponder à nova localidade.
Mude as propriedades do atalho para que o campo "Destino" especifique as sinalizações
--lang
e--user-data-dir
. O destino deve ser parecido com este:path_to_chrome.exe --lang=locale --user-data-dir=c:\locale_profile_dir
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
É possível criar quantos atalhos você quiser para facilitar 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
Como usar a IU
Veja como alterar a localidade usando a IU no Google Chrome para Windows:
- Ícone do app > Opções
- Selecione a guia Configurações avançadas.
- Role para baixo até Conteúdo da Web.
- Clique em Mudar as configurações de fonte e idioma.
- Selecione a guia Idiomas.
- Use o menu suspenso para definir o idioma do Google Chrome
- Reiniciar o Chrome
Mac OS X
Para mudar a localidade no Mac, use as preferências do sistema.
- No menu Apple, escolha System Preferences
- Na seção Pessoal, escolha Internacional.
- Escolha seu idioma e local
- Reiniciar o Chrome
Linux
Para mudar a localidade no Linux, saia do Google Chrome. Depois, em uma só linha, defina a variável de ambiente LANGUAGE e inicie o Google Chrome. Exemplo:
LANGUAGE=es ./chrome
ChromeOS
Para mudar a localidade no ChromeOS, faça o seguinte:
- Na bandeja do sistema, selecione Configurações.
- Na seção Idiomas e entrada, selecione o menu suspenso Idioma.
- Caso seu idioma não esteja listado, clique em Adicionar idiomas e adicione-o.
- Depois de adicionar, clique no item de menu de três pontos Mais ações ao lado do seu idioma e selecione Exibir ChromeOS neste idioma.
- 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 ver um exemplo completo, consulte examples/extensions/news. Para ver outros exemplos e receber ajuda na visualização do código-fonte, consulte Amostras.
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 dentro da 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. Se quiser detalhes sobre como chamar getMessage()
, consulte a referência da API.
Exemplo: getAcceptLanguage
O código a seguir recebe Accept-languages do navegador e os mostra 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 ver detalhes sobre como chamar getAcceptLanguages()
, consulte a referência da API.
Exemplo: 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
Um código de idioma ISO, como en
ou fr
. Para uma lista completa de idiomas suportados por esse método, consulte kLanguageInfoTable. Para um idioma desconhecido, será retornado und
, o que significa que [porcentagem] do texto é desconhecida para o CLD.
Tipo
string
Métodos
detectLanguage()
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 optional
O parâmetro
callback
tem esta aparência:(result: object) => void
-
resultado
objeto
Objeto LanguageDetectionResult que contém a confiabilidade do idioma detectado e a matriz de DetectedLanguage
-
isReliable
boolean
O CLD detectou a confiabilidade do idioma
-
linguagens
objeto[]
matriz de detectedLanguage
-
language
string
-
porcentagem
number
A porcentagem do idioma detectado
-
-
-
Retorna
-
Promise<object>
Chrome 99 ou mais recentePromessas são compatíveis apenas com o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.
getAcceptLanguages()
chrome.i18n.getAcceptLanguages(
callback?: function,
)
Recebe os Accept-languages do navegador. Ela é diferente da localidade usada pelo navegador. Para conferir a localidade, use i18n.getUILanguage
.
Parâmetros
-
callback
função optional
O parâmetro
callback
tem esta aparência:(languages: string[]) => void
-
linguagens
string[]
Matriz de LanguageCode
-
Retorna
-
Promise<LanguageCode[]>
Chrome 99 ou mais recentePromessas são compatíveis apenas com o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.
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 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 opção opcional
Até nove strings de substituição, se a mensagem exigir alguma.
-
opções
objeto opcional
Chrome 79 ou mais recente-
escapeLt
booleano opcional
Escape de
<
ao traduzir para<
. Isso se aplica somente à mensagem em si, e não aos marcadores de posição. Os desenvolvedores podem querer usar isso se a tradução for usada em um contexto HTML. Os modelos de fechamento usados com o closure Compiler geram essas informações automaticamente.
-
Retorna
-
string
Mensagem localizada para a localidade atual.
getUILanguage()
chrome.i18n.getUILanguage()
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.