Übersetzer

Webfunktionen: Übersetzer

Mit der Translator API können Entwickler clientseitige Textübersetzungen mit integrierten KI-Modellen in Chrome und Edge durchführen. Dadurch sind für flüchtige Inhalte keine cloudbasierten Übersetzungsdienste mehr erforderlich. Das senkt die Kosten und verbessert den Datenschutz, da die Daten auf dem Gerät des Nutzers bleiben.

Voraussetzungen und Anforderungen

API-Oberfläche und globaler Geltungsbereich

  • OBLIGATORISCH: Greifen Sie ausschließlich über die globale Translator-Schnittstelle (window.Translator / self.Translator) auf die Translator API zu.
  • Verwenden oder prüfen Sie den verworfenen Namespace window.ai.translator NICHT.

Unterstützte Browser

  • Chrome: Version 138 oder höher (nur Desktop).
  • Edge: Version 148 oder höher (nur Desktop).
  • Nicht unterstützt: Mobilgeräte (Android/iOS), Firefox, Safari.

Hardware Requirements

Damit Gemini Nano und die zugehörigen Modelle ausgeführt werden können, benötigt das System Folgendes:

  • Betriebssystem: Windows 10/11, macOS 13 oder höher, Linux oder ChromeOS (Chromebook Plus).
  • Speicherplatz: Mindestens 22 GB freier Speicherplatz auf dem Profilvolume.
  • Arbeitsspeicher/CPU: Mindestens 16 GB RAM und mindestens 4 CPU-Kerne.
  • GPU: Mindestens 4 GB VRAM (erforderlich für die Prompt API mit Audio).
  • Netzwerk: Nur für den ersten Download von Sprachpaketen/-modellen erforderlich.

Implementierung und Codebeispiele

1. Verfügbarkeit prüfen und Modelle verwalten

Obligatorische Übergabe von Optionen: Sie müssen das identische Konfigurationsobjekt mit sourceLanguage und targetLanguage sowohl an Translator.availability(options) als auch an Translator.create(options) übergeben.

Empfohlene Fortschrittsüberwachung: Sie sollten eine Überwachung für den Fortschritt des Modelldownloads implementieren, indem Sie einen monitor(m)-Callback für Translator.create() bereitstellen und einen Listener für das downloadprogress-Ereignis hinzufügen, damit der Nutzer den Fortschritt des Modelldownloads sehen kann.

Anforderung an Nutzergesten: Wenn der Aufruf von availability(options) den Wert 'downloadable' oder 'downloading' zurückgibt, wird durch den Aufruf von Translator.create() der Download des Sprachpakets ausgelöst. Dafür ist unbedingt eine Nutzergeste erforderlich (z. B. ein Klick auf einen Button), um einen NotAllowedError zu verhindern.

Translator.availability(options) gibt einen von vier Stringstatus zurück:

  • 'available': Das Sprachpaar-Modell ist bereits auf das Gerät heruntergeladen und kann sofort für Übersetzungen verwendet werden.
  • 'downloadable': Das Sprachpaar wird unterstützt, aber das Modell muss heruntergeladen werden. Zum Initiieren von Translator.create() ist eine Nutzergeste erforderlich.
  • 'downloading': Das Sprachpaket wird gerade heruntergeladen. Wenn Sie Translator.create() mit einer Nutzergeste aufrufen, wird der Download angehängt.
  • 'unavailable': Das Sprachpaar oder das Gerät wird nicht unterstützt. Führen Sie Ihre Fallback-Strategie aus.
// 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. Übersetzungen ausführen

Die API unterstützt sowohl statische als auch Streaming-Antworten. Fügen Sie beim Instanziieren des Übersetzers immer eine Überwachung des Downloadfortschritts hinzu.

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

Streaming-Übersetzung (für langen Text):

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

Unterstützte Sprachen

Die API unterstützt eine Vielzahl von BCP 47-Sprachcodes. Hier sind die Sprachen, die von der Chrome-Implementierung der Translator API unterstützt werden:

  • ar: Arabisch
  • bg: Bulgarisch
  • bn: Bengali
  • cs: Tschechisch
  • da: Dänisch
  • de: Deutsch
  • el: Griechisch
  • en: Englisch
  • es: Spanisch
  • fi: Finnisch
  • fr: Französisch
  • hi: Hindi
  • hr: Kroatisch
  • hu: Ungarisch
  • id: Indonesian
  • it: Italian
  • he: Hebräisch
  • ja: Japanisch
  • kn: Kannada
  • ko: Koreanisch
  • lt: Litauisch
  • mr: Marathi
  • nl: Dutch
  • no: Norwegisch
  • pl: Polish
  • pt: Portugiesisch
  • ro: Romanian
  • ru: Russian
  • sk: Slovak
  • sl: Slowenisch
  • sv: Schwedisch
  • ta: Tamil
  • te: Telugu
  • th: Thai
  • tr: Türkisch
  • uk: Ukrainisch
  • vi: Vietnamesisch
  • zh: Chinesisch
  • zh-Hant: traditionelles Chinesisch

Sicherheit und Leistung

  • Berechtigungsrichtlinie: Für ursprungsübergreifende iFrames ist eine explizite Berechtigung erforderlich.

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

  • Web-Worker: Aufgrund der Komplexität der Berechtigungsrichtlinie derzeit nicht unterstützt.

  • Datenschutz: Nach dem Herunterladen des Modells werden während des Übersetzungsprozesses keine Daten an Google-Server gesendet.

Fallback-Strategie

Prüfen Sie vor der Verwendung, ob das Translator-Objekt im globalen Bereich verfügbar ist:

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

Wenn die Translator API nicht unterstützt wird oder die Verfügbarkeitsprüfung 'unavailable' zurückgibt, musst du einen ordnungsgemäßen Fallback durchführen.

Empfohlene Optionen:

  1. Remote-API-Fallback: Die Übersetzungsanfrage wird an einen Serverendpunkt oder eine Remote-API in der Cloud (z. B. die Vertex AI Gemini API) weitergeleitet, um die Übersetzungsfunktion bereitzustellen.
  2. Graduelle Fehlertoleranz: Deaktivieren Sie visuell die Steuerelemente oder Schaltflächen für die Übersetzung und zeigen Sie einen nutzerfreundlichen Hinweis an (z.B. "Client-side translation is currently unsupported in this browser"). Lassen Sie keine unbehandelten Ausnahmen zu.
  3. Polyfill-Fallback: Sie können von der Community verwaltete Polyfills wie built-in-ai-task-apis-polyfills oder prompt-api-polyfill verwenden, um die API-Oberfläche mithilfe von Remote-Diensten zu emulieren.

Datenschutz und Kosten: Diese Polyfills leiten Anfragen möglicherweise an Remote-Server weiter (z. B. Gemini API über die Cloud), obwohl auch eine lokale Verarbeitung möglich ist. Bei der Remote-Verarbeitung werden die Datenschutzgarantien der nativen integrierten KI-APIs auf dem Gerät vollständig aufgehoben und es fallen häufig serverseitige API-Nutzungskosten an.