Tradutor e intérprete

Recursos da Web: Tradutor

A API Translator permite que os desenvolvedores realizem traduções de texto do lado do cliente usando modelos de IA integrados no Chrome e no Edge. Essa abordagem elimina a necessidade de serviços de tradução baseados na nuvem para conteúdo efêmero, reduzindo custos e melhorando a privacidade ao manter os dados no dispositivo do usuário.

Pré-requisitos e requisitos

Superfície da API e escopo global

  • OBRIGATÓRIO: acesse a API Translator exclusivamente pela interface global Translator (window.Translator / self.Translator).
  • NÃO use nem verifique o namespace window.ai.translator descontinuado.

Compatibilidade com navegadores

  • Chrome: versão 138 ou mais recente (somente para computador).
  • Edge: versão 148 ou mais recente (somente para computador).
  • Não compatível: dispositivos móveis (Android/iOS), Firefox, Safari.

Requisitos de hardware

Para executar o Gemini Nano e os modelos associados, o sistema precisa de:

  • Sistema operacional: Windows 10/11, macOS 13+, Linux ou ChromeOS (Chromebook Plus).
  • Armazenamento: pelo menos 22 GB livres no volume do perfil.
  • Memória/CPU: mais de 16 GB de RAM e mais de 4 núcleos de CPU.
  • GPU: VRAM de 4 GB ou mais (obrigatório para a API Prompt com áudio).
  • Rede: necessária apenas para o download inicial de pacotes de idiomas/modelos.

Implementação e exemplos de código

1. Como verificar a disponibilidade e o gerenciamento de modelos

Transmissão de opções obrigatórias: é necessário transmitir o objeto de opções de configuração idêntico que contém sourceLanguage e targetLanguage para Translator.availability(options) e Translator.create(options).

Monitoramento de progresso recomendado: implemente um monitor para o progresso do download do modelo fornecendo um callback monitor(m) para Translator.create() e adicionando um listener para o evento downloadprogress, para que o usuário possa ver o progresso do download do modelo.

Requisito de interação do usuário: quando a chamada de availability(options) retorna 'downloadable' ou 'downloading', a chamada de Translator.create() aciona o download do pacote de idioma e exige estritamente uma interação do usuário (como um clique em um botão) para evitar um NotAllowedError.

Translator.availability(options) retorna um dos quatro status de string:

  • 'available': o modelo de par de idiomas já foi baixado no dispositivo e está pronto para tradução imediata.
  • 'downloadable': o par de idiomas é aceito, mas o modelo precisa ser baixado. É necessária uma interação do usuário para iniciar Translator.create().
  • 'downloading': o pacote de idioma está sendo baixado. Chamar Translator.create() com uma interação inicial é anexado ao download.
  • 'unavailable': o par de idiomas ou o dispositivo não é compatível. Execute sua estratégia de fallback.
// Language pair options passed to both availability() and create()
const options = {
  sourceLanguage: 'es', // Example BCP 47 language code
  targetLanguage: 'fr', // Example BCP 47 language code
};

// 1. Check availability for the language pair
const availability = await Translator.availability(options);

if (availability === 'available') {
  // Model is ready immediately on device
  const translator = await Translator.create(options);
} else if (availability === 'downloadable' || availability === 'downloading') {
  // User gesture is strictly required before create() triggers or attaches to download
  document.getElementById('start-translation-btn').addEventListener('click', async () => {
    const translator = await Translator.create({
      ...options,
      monitor(m) {
        m.addEventListener('downloadprogress', (e) => {
          console.log(`Downloaded ${Math.round(e.loaded * 100)}%`);
        });
      },
    });
  });
} else if (availability === 'unavailable') {
  // Language pair or hardware unsupported; execute fallback
  console.warn('Translation model is unavailable on this device.');
}

2. Como executar traduções

A API aceita respostas estáticas e de streaming. Sempre inclua o monitoramento do progresso do download ao instanciar o tradutor.

Standard Translation:

// Default to including a progress monitor when creating translator
const translator = await Translator.create({
  sourceLanguage: 'en',
  targetLanguage: 'fr',
  monitor(m) {
    m.addEventListener('downloadprogress', (e) => {
      console.log(`Downloaded ${Math.round(e.loaded * 100)}%`);
    });
  },
});

const result = await translator.translate(
  'Where is the next bus stop, please?',
);
console.log(result);
// Output: "Où est le prochain arrêt de bus, s'il vous plaît ?"

Tradução de streaming (para textos longos):

const stream = translator.translateStreaming(longText);
for await (const chunk of stream) {
  console.log(chunk);
}

Idiomas compatíveis

A API é compatível com uma ampla variedade de códigos de idioma BCP 47. Confira os idiomas aceitos pela implementação da API Translator no Chrome:

  • ar: árabe
  • bg: búlgaro
  • bn: bengali
  • cs: tcheco
  • da: dinamarquês
  • de: alemão
  • el: grego
  • en: inglês
  • es: espanhol
  • fi: finlandês
  • fr: francês
  • hi: hindi
  • hr: croata
  • hu: húngaro
  • id: indonésio
  • it: italiano
  • he: hebraico
  • ja: japonês
  • kn: canarês
  • ko: coreano
  • lt: lituano
  • mr: marati
  • nl: holandês
  • no: norueguês
  • pl: polonês
  • pt: português
  • ro: romeno
  • ru: russo
  • sk: eslovaco
  • sl: esloveno
  • sv: sueco
  • ta: tâmil
  • te: telugu
  • th: tailandês
  • tr: turco
  • uk: ucraniano
  • vi: vietnamita
  • zh: chinês
  • zh-Hant: chinês (tradicional)

Segurança e desempenho

  • Política de permissões: iframes entre origens exigem permissão explícita.

    <iframe src="https://example.com/" allow="translator"></iframe>

  • Web Workers: no momento, não há suporte devido a complexidades da política de permissões.

  • Privacidade: nenhum dado é enviado aos servidores do Google durante o processo de tradução depois que o modelo é baixado.

Estratégia de fallback

Antes de usar, verifique se o objeto Translator está disponível no escopo global:

if ('Translator' in self) {
  // The Translator API is supported.
} else {
  // Execute fallback strategy (do not fall back to window.ai.translator).
}

Se a API Translator não for compatível ou as verificações de disponibilidade retornarem 'unavailable', você precisará fazer um fallback de maneira adequada.

Opções recomendadas:

  1. Fallback da API remota: redireciona a solicitação de tradução para um endpoint de servidor ou uma API remota na nuvem (como a API Gemini da Vertex AI) para oferecer a funcionalidade de tradução.
  2. Degradação suave: desative visualmente os elementos ou botões de controle de tradução enquanto mostra uma observação amigável para o usuário final (por exemplo, "Client-side translation is currently unsupported in this browser"). Não permita exceções não processadas.
  3. Polyfill de fallback: use polyfills mantidos pela comunidade, como built-in-ai-task-apis-polyfills ou prompt-api-polyfill, para emular a superfície da API usando serviços remotos.

Implicações de privacidade e custo: esses polyfills podem encaminhar solicitações para servidores remotos (como a API Gemini na nuvem), mas o processamento local também é uma opção. O processamento remoto anula completamente as garantias de privacidade no dispositivo das APIs de IA integradas nativas e, muitas vezes, gera custos de uso da API do lado do servidor.