Base de conhecimentoCentro de Exames
PT · PTPortuguês (Portugal)
Escolher idioma13

CKTIS / HTML

onlanguagechange — tratar alterações nos idiomas preferidos

O atributo `onlanguagechange` do elemento `body` define a função de tratamento do evento `languagechange` do objeto `Window`. O evento assinala uma alteração nas preferências linguísticas do utilizador reconhecidas pelo navegador, e não uma alteração ao atributo `lang` do documento.

Versão: WHATWG HTML Living Standard; index snapshot date recorded separately

Sintaxe

<body onlanguagechange="JavaScript statements">

onlanguagechange é um atributo HTML de tratamento de eventos usado no elemento body. O seu valor contém código JavaScript que é executado quando ocorre o evento languagechange do objeto Window; não se trata de um evento comum que tenha body como alvo.

O navegador desencadeia este evento quando muda a lista de idiomas que reconhece como preferidos pelo utilizador. Na função de tratamento do evento, podes consultar navigator.languages para obter a lista de idiomas por ordem de preferência ou navigator.language para obter o primeiro idioma dessa lista. Alterar o atributo lang não significa que estas preferências tenham mudado, e o evento, por si só, não traduz a página.

Em JavaScript, podes definir a mesma função de tratamento através de window.onlanguagechange. Uma nova atribuição a essa propriedade substitui a função anterior; window.addEventListener('languagechange', handler) permite, em alternativa, registar funções de escuta independentes. A política de segurança da página pode bloquear a execução de código em atributos de tratamento de eventos.

O exemplo envia deliberadamente um evento sintético para window, para que o resultado não dependa das definições de idioma do dispositivo. Isto permite verificar se a função de tratamento é chamada, mas não altera as preferências nem testa se o navegador deteta uma alteração real dessas preferências.

Exemplos

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>onlanguagechange demo</title>
</head>
<body onlanguagechange="document.getElementById('status').textContent = 'languagechange received'">
  <p id="status">Waiting</p>
  <button type="button" id="test">Test</button>
  <script>
    document.getElementById('test').addEventListener('click', () => {
      window.dispatchEvent(new Event('languagechange'));
    });
  </script>
</body>
</html>

Resultado

languagechange received

O código apresentado e o resultado declarado foram verificados num ambiente isolado pelo método registado na prova de verificação desta versão exata.

Fontes