Translator.measureInputUsage() — Methode · JavaScript-Referenz

Signatur

Translator.prototype.measureInputUsage(input, options)

Beschreibung

Die Methode measureInputUsage() der Schnittstelle Translator gehört zur browserinternen Translator-API. Sie berechnet, wie viel Eingabequote ein Aufruf von translate() oder translateStreaming() für den übergebenen Text verbrauchen würde. Der Text wird dabei nicht übersetzt. Das Ergebnis ist eine abstrakte Zahl, die meist ungefähr der Token-Anzahl des lokalen Übersetzungsmodells entspricht.

Der Wert ist vor allem zusammen mit der Eigenschaft Translator.inputQuota nützlich. Diese gibt die höchste erlaubte Eingabemenge pro Übersetzungsaufruf an. Liegt der gemessene Wert darüber, würde translate() mit einem QuotaExceededError fehlschlagen. Mit measureInputUsage() kannst du das vorher prüfen. Lange Texte teilst du dann in Absätze oder Sätze auf, statt eine Ausnahme abzufangen.

Wie viel Quota ein Text verbraucht, hängt vom Modell, von der Sprache und vom Zeichensatz ab. Zeichenlänge oder Wortzahl sind daher nur grobe Näherungen. Schreibe keine Umrechnungsfaktoren fest in den Code, sondern miss mit dieser Methode.

Parameter

Name	Typ	Default	Beschreibung
$input Pflicht	string		Der Text, dessen Quota-Verbrauch gemessen werden soll.
$options	object	{}	Optionales Objekt mit Einstellungen. Unterstützt wird `signal` (`AbortSignal`): Damit lässt sich die Messung abbrechen. Das Promise wird dann mit einem `AbortError` abgelehnt.

Rückgabewert

Typ

Promise<number>

Beschreibung

Ein Promise, das mit einer Zahl erfüllt wird: der Eingabequote, die eine Übersetzung von input verbrauchen würde. Diese Zahl vergleichst du mit translator.inputQuota.

Beispiele

Quota-Verbrauch messen und mit inputQuota vergleichen

const translator = await Translator.create({
  sourceLanguage: 'en',
  targetLanguage: 'de'
});

const text = 'The quick brown fox jumps over the lazy dog.';
const usage = await translator.measureInputUsage(text);

console.log(`Verbrauch: ${usage} von ${translator.inputQuota}`);

if (usage <= translator.inputQuota) {
  console.log(await translator.translate(text));
} else {
  console.warn('Text zu lang – bitte aufteilen.');
}

Verbrauch: 12 von 1000 Der schnelle braune Fuchs springt über den faulen Hund.

Lange Texte absatzweise übersetzen, wenn die Quota nicht reicht

const translateLongText = async (translator, text) => {
  const total = await translator.measureInputUsage(text);
  if (total <= translator.inputQuota) {
    return translator.translate(text);
  }

  // Absatzweise übersetzen
  const paragraphs = text.split(/\n{2,}/);
  const results = [];
  for (const paragraph of paragraphs) {
    const usage = await translator.measureInputUsage(paragraph);
    if (usage > translator.inputQuota) {
      throw new Error('Einzelner Absatz überschreitet die Quota.');
    }
    results.push(await translator.translate(paragraph));
  }
  return results.join('\n\n');
};

const translator = await Translator.create({ sourceLanguage: 'en', targetLanguage: 'de' });
const article = document.querySelector('article').innerText;
console.log(await translateLongText(translator, article));

Messung per AbortSignal mit Zeitlimit abbrechen

if ('Translator' in self) {
  const translator = await Translator.create({ sourceLanguage: 'en', targetLanguage: 'fr' });

  try {
    const usage = await translator.measureInputUsage('Hello world', {
      signal: AbortSignal.timeout(2000)
    });
    console.log('Benötigte Quota:', usage);
  } catch (err) {
    if (err.name === 'AbortError' || err.name === 'TimeoutError') {
      console.warn('Messung abgebrochen.');
    } else {
      throw err;
    }
  } finally {
    translator.destroy();
  }
} else {
  console.log('Translator-API wird nicht unterstützt.');
}

Benötigte Quota: 3

// Wichtig · Fallstricke

Kompatibilität: Die Translator-API ist experimentell. Sie ist derzeit nur in Chromium-Browsern auf dem Desktop verfügbar (Chrome/Edge ab 138). Firefox und Safari unterstützen sie nicht. Prüfe die Verfügbarkeit immer mit 'Translator' in self und Translator.availability().
Nur in sicheren Kontexten (HTTPS). In iframes muss die Permissions-Policy translator die Nutzung erlauben.
Der Rückgabewert ist keine Zeichen- oder Wortzahl. Er hängt vom Modell ab und kann sich je nach Browserversion ändern.
Wurde der Translator mit destroy() zerstört oder ist das zugehörige Dokument nicht mehr aktiv, wird das Promise abgelehnt (z. B. mit InvalidStateError oder AbortError).
Auch die Messung selbst kostet etwas Rechenzeit. Miss bei vielen kleinen Texten nicht jeden einzeln, wenn sie ohnehin sicher unter inputQuota liegen.
Ist inputQuota gleich Infinity, gibt es kein festes Limit. Die Prüfung ist dann nicht nötig.

Siehe auch

Translator Translator.translate() Translator.create() Translator.availability() Translator.destroy()