Traduttore

Funzionalità web: Traduttore

L'API Translator consente agli sviluppatori di eseguire la traduzione del testo lato client utilizzando modelli di AI integrati in Chrome ed Edge. Questo approccio elimina la necessità di servizi di traduzione basati su cloud per i contenuti temporanei, riducendo i costi e migliorando la privacy, poiché i dati vengono conservati sul dispositivo dell'utente.

Prerequisiti e requisiti

Piattaforma API e ambito globale

  • OBBLIGATORIO: accedi all'API Translator esclusivamente tramite l'interfaccia Translator globale (window.Translator/self.Translator).
  • NON utilizzare o controllare lo spazio dei nomi window.ai.translator deprecato.

Supporto del browser

  • Chrome: versione 138 e successive (solo computer).
  • Edge: versione 148 e successive (solo computer).
  • Non supportati: dispositivi mobili (Android/iOS), Firefox, Safari.

Requisiti hardware

Per eseguire Gemini Nano e i modelli associati, il sistema richiede:

  • Sistema operativo: Windows 10/11, macOS 13 o versioni successive, Linux o ChromeOS (Chromebook Plus).
  • Spazio di archiviazione: almeno 22 GB liberi sul volume del profilo.
  • Memoria/CPU: almeno 16 GB di RAM e almeno 4 core della CPU.
  • GPU: almeno 4 GB di VRAM (obbligatorio per l'API Prompt con audio).
  • Rete: necessaria solo per il download iniziale dei language pack/modelli.

Implementazione ed esempi di codice

1. Verifica della disponibilità e gestione dei modelli

Passaggio obbligatorio delle opzioni: devi passare l'oggetto delle opzioni di configurazione identico contenente sourceLanguage e targetLanguage sia a Translator.availability(options) che a Translator.create(options).

Monitoraggio dei progressi consigliato: devi implementare un monitor per l'avanzamento del download del modello fornendo un callback monitor(m) a Translator.create() e aggiungendo un listener per l'evento downloadprogress, in modo che l'utente possa vedere l'avanzamento del download del modello.

Requisito di attivazione dall'utente: quando la chiamata a availability(options) restituisce 'downloadable' o 'downloading', la chiamata a Translator.create() attiva il download del language pack e richiede rigorosamente un'attivazione dall'utente (ad esempio un clic su un pulsante) per impedire un NotAllowedError.

Translator.availability(options) restituisce uno dei quattro stati della stringa:

  • 'available': il modello di coppia di lingue è già stato scaricato sul dispositivo ed è pronto per la traduzione immediata.
  • 'downloadable': la coppia di lingue è supportata, ma è necessario scaricare il modello. Per avviare Translator.create() è necessaria un'attivazione dall'utente.
  • 'downloading': il language pack è in fase di download. La chiamata di Translator.create() con un'attivazione dall'utente si collega al download.
  • 'unavailable': la coppia di lingue o il dispositivo non sono supportati. Esegui la strategia di riserva.
// 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. Esecuzione delle traduzioni

L'API supporta risposte sia statiche che in streaming. Includi sempre il monitoraggio dell'avanzamento del download quando crei un'istanza del traduttore.

Traduzione standard:

// 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 ?"

Traduzione in streaming (per testi lunghi):

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

Lingue supportate

L'API supporta un'ampia gamma di codici lingua BCP 47. Di seguito sono riportate le lingue supportate dall'implementazione dell'API Translator di Chrome:

  • ar: Arabic
  • bg: Bulgarian
  • bn: bengalese
  • cs: Czech
  • da: danese
  • de: tedesco
  • el: Greek
  • en: inglese
  • es: Spanish
  • fi: finlandese
  • fr: French
  • hi: hindi
  • hr: Croatian
  • hu: ungherese
  • id: Indonesian
  • it: Italian
  • he: ebraico
  • ja: Japanese
  • kn: Kannada
  • ko: Korean
  • lt: Lithuanian
  • mr: Marathi
  • nl: Dutch
  • no: norvegese
  • pl: Polish
  • pt: Portuguese
  • ro: rumeno
  • ru: Russian
  • sk: Slovak
  • sl: sloveno
  • sv: svedese
  • ta: Tamil
  • te: Telugu
  • th: Thai
  • tr: Turkish
  • uk: ucraino
  • vi: Vietnamese
  • zh: Chinese
  • zh-Hant: cinese (tradizionale)

Sicurezza e prestazioni

  • Policy relativa alle autorizzazioni: gli iframe multiorigine richiedono un'autorizzazione esplicita.

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

  • Web worker: al momento non supportati a causa delle complessità delle policy relative alle autorizzazioni.

  • Privacy: una volta scaricato il modello, non vengono inviati dati ai server di Google durante il processo di traduzione.

Strategia di riserva

Prima dell'uso, verifica se l'oggetto Translator è disponibile nell'ambito globale:

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

Se l'API Translator non è supportata o i controlli di disponibilità restituiscono 'unavailable', devi eseguire un graceful fallback.

Opzioni consigliate:

  1. Fallback API remota: reindirizza la richiesta di traduzione a un endpoint server o a un'API remota cloud (come l'API Vertex AI Gemini) per fornire la funzionalità di traduzione.
  2. Riduzione controllata: disattiva visivamente gli elementi o i pulsanti di controllo della traduzione mostrando una nota di facile comprensione per l'utente finale (ad es. "Client-side translation is currently unsupported in this browser"). Non consentire eccezioni non gestite.
  3. Polyfill di riserva: puoi utilizzare polyfill gestiti dalla community come built-in-ai-task-apis-polyfills o prompt-api-polyfill per emulare la superficie dell'API utilizzando servizi remoti.

Implicazioni relative alla privacy e ai costi: questi polyfill potrebbero inviare richieste proxy a server remoti (come l'API Gemini sul cloud), anche se l'elaborazione locale è un'opzione. L'elaborazione remota annulla completamente le garanzie di privacy on-device delle API AI integrate native e spesso comporta costi di utilizzo delle API lato server.