Traductor

Funciones web: Traductor

La API de Translator permite que los desarrolladores realicen traducciones de texto del cliente con modelos de IA integrados en Chrome y Edge. Este enfoque elimina la necesidad de usar servicios de traducción basados en la nube para el contenido efímero, lo que reduce los costos y mejora la privacidad, ya que los datos se mantienen en el dispositivo del usuario.

Requisitos previos y requisitos

Superficie de la API y alcance global

  • OBLIGATORIO: Accede a la API de Translator exclusivamente a través de la interfaz global de Translator (window.Translator/self.Translator).
  • NO uses ni verifiques el espacio de nombres window.ai.translator obsoleto.

Navegadores compatibles

  • Chrome: Versión 138 y posteriores (solo para computadoras)
  • Edge: Versión 148 o posterior (solo para computadoras)
  • No compatible: Dispositivos móviles (Android/iOS), Firefox y Safari.

Requisitos de hardware

Para ejecutar Gemini Nano y los modelos asociados, el sistema necesita lo siguiente:

  • Sistema operativo: Windows 10/11, macOS 13 o versiones posteriores, Linux o ChromeOS (Chromebook Plus)
  • Almacenamiento: Al menos 22 GB libres en el volumen del perfil.
  • Memoria/CPU: Más de 16 GB de RAM y más de 4 núcleos de CPU.
  • GPU: Más de 4 GB de VRAM (obligatorio para la API de Prompt con audio).
  • Red: Solo se requiere para la descarga inicial de paquetes de idioma o modelos.

Implementación y muestras de código

1. Comprobación de la disponibilidad y administración de modelos

Paso de opciones obligatorio: Debes pasar el objeto de opciones de configuración idéntico que contiene sourceLanguage y targetLanguage a Translator.availability(options) y Translator.create(options).

Supervisión del progreso recomendada: Debes implementar un supervisor para el progreso de la descarga del modelo. Para ello, proporciona una devolución de llamada de monitor(m) a Translator.create() y agrega un objeto de escucha para el evento downloadprogress, de modo que el usuario pueda ver el progreso de la descarga del modelo.

Requisito de gesto del usuario: Cuando la llamada a availability(options) devuelve 'downloadable' o 'downloading', la llamada a Translator.create() activa la descarga del paquete de idioma y requiere estrictamente un gesto del usuario (como un clic en un botón) para evitar un NotAllowedError.

Translator.availability(options) devuelve uno de los cuatro estados de cadena:

  • 'available': El modelo de par de idiomas ya se descargó en el dispositivo y está listo para la traducción inmediata.
  • 'downloadable': Se admite el par de idiomas, pero se debe descargar el modelo. Se requiere un gesto del usuario para iniciar Translator.create().
  • 'downloading': El paquete de idioma se está descargando. Si se llama a Translator.create() con un gesto del usuario, se adjunta a la descarga.
  • 'unavailable': El par de idiomas o el dispositivo no son compatibles. Ejecuta tu estrategia de resguardo.
// 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. Ejecución de traducciones

La API admite respuestas estáticas y de transmisión. Incluye siempre la supervisión del progreso de la descarga cuando crees una instancia del traductor.

Traducción estándar:

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

Traducción de transmisión (para texto largo):

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

Idiomas compatibles

La API admite una amplia variedad de códigos de idioma BCP 47. Estos son los idiomas que admite la implementación de la API de Translator en Chrome:

  • ar: árabe
  • bg: búlgaro
  • bn: bengalí
  • cs: checo
  • da: danés
  • de: Alemán
  • el: griego
  • en: inglés
  • es: Español
  • fi: finés
  • fr: francés
  • hi: Hindi
  • hr: croata
  • hu: húngaro
  • id: indonesio
  • it: italiano
  • he: hebreo
  • ja: japonés
  • kn: canarés
  • ko: Coreano
  • lt: lituano
  • mr: maratí
  • nl: Neerlandés
  • no: noruego
  • pl:
  • pt: portugués
  • ro: rumano
  • ru: ruso
  • sk: eslovaco
  • sl: esloveno
  • sv: sueco
  • ta: Tamil
  • te: Telugu
  • th: tailandés
  • tr: turco
  • uk: ucraniano
  • vi: vietnamita
  • zh: Chino
  • zh-Hant: chino (tradicional)

Seguridad y rendimiento

  • Política de permisos: Los iframes de origen cruzado requieren un permiso explícito.

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

  • Web Workers: Actualmente, no se admiten debido a las complejidades de la política de permisos.

  • Privacidad: No se envían datos a los servidores de Google durante el proceso de traducción una vez que se descarga el modelo.

Estrategia de resguardo

Antes de usarlo, verifica si el objeto Translator está disponible en el alcance global:

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

Si la API de Translator no es compatible o las verificaciones de disponibilidad devuelven 'unavailable', debes recurrir a una alternativa de forma correcta.

Opciones recomendadas:

  1. Resguardo de la API remota: Redirige la solicitud de traducción a un extremo del servidor o a una API remota en la nube (como la API de Vertex AI Gemini) para ofrecer la funcionalidad de traducción.
  2. Degradación elegante: Inhabilita visualmente los elementos o botones de control de traducción mientras se muestra una nota fácil de usar para el usuario final (p.ej., "Client-side translation is currently unsupported in this browser"). No permitas excepciones no controladas.
  3. Resguardo de polyfill: Puedes usar polyfills mantenidos por la comunidad, como built-in-ai-task-apis-polyfills o prompt-api-polyfill, para emular la plataforma de la API con servicios remotos.

Implicaciones de privacidad y costos: Estos polyfills posiblemente envíen solicitudes de proxy a servidores remotos (como la API de Gemini en la nube), aunque el procesamiento local también es una opción. El procesamiento remoto anula por completo las garantías de privacidad integrada en el dispositivo de las APIs de IA integradas nativas y, a menudo, generará costos de uso de la API del servidor.