DieTranslator- und Language Detector-APIs bieten asynchrone (Promise-basierte) Mechanismen für eine Website, um Sprachen zu erkennen und Text über das interne AI-Modell des Browsers zu übersetzen. Dies ist nützlich und effizient, da der Browser den Dienst übernimmt, anstatt dass Entwickler darauf angewiesen sind, dass der Benutzer AI-Modelle herunterlädt oder einen cloudbasierten Übersetzungsdienst hostet oder bezahlt. Dieser Artikel erklärt, wie Sie diese APIs verwenden.

Eine Sprache erkennen

Die gesamte Funktionalität zur Spracherkennung ist über dasLanguageDetector-Interface zugänglich.

Der erste Schritt, um das AI-Modell eine Sprache erkennen zu lassen, besteht darin, eine Instanz desLanguageDetector-Objekt zu erstellen. Dies geschieht mit der statischen MethodeLanguageDetector.create(), die ein Optionsobjekt als Argument übernimmt:

const detector = await LanguageDetector.create({  expectedInputLanguages: ["en-US", "zh"],});

DieexpectedInputLanguages-Eigenschaft spezifiziert die Sprachen, die Sie dem Detektor geben möchten, um die Genauigkeit der Spracherkennung zu verbessern.

Nachdem Sie eineLanguageDetector-Instanz erstellt haben, können Sie diese verwenden, um eine Sprache zu erkennen, indem Sie die InstanzmethodeLanguageDetector.detect() aufrufen und den zu prüfenden Text als Argument übergeben.

const results = await detector.detect(myTextString);

Diese Methode gibt ein Array von Objekten zurück, die die erkannten potenziellen Sprachübereinstimmungen darstellen. Jedes enthält:

• Einen String mit einemBCP 47 language tag, der die erkannte Sprache repräsentiert.
• Eine Zahl zwischen 0 und 1, die einen Vertrauenswert für diese Übereinstimmung darstellt.

Zum Beispiel:

results.forEach((result) => {  console.log(`${result.detectedLanguage}: ${result.confidence}`);});// Results in logs like this:// la: 0.8359838724136353// es: 0.017705978825688362// sv: 0.012977192178368568// en: 0.011148443445563316// und: 0.0003214875760022551

Eine Übersetzung erstellen

Die Übersetzung folgt einem sehr ähnlichen Muster wie die Spracherkennung. EinTranslator-Objekt wird mit der statischen MethodeTranslator.create() erstellt, die ein Optionsobjekt erwartet, das mindestens einesourceLanguage und einetargetLanguage enthalten muss:

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

Die Übersetzung wird dann durch Aufrufen der InstanzmethodeTranslator.translate() erstellt, der die zu übersetzende Textzeichenkette als Argument übergeben wird:

const translation = await translator.translate(myTextString);

Dies gibt eine Zeichenkette zurück, die die Übersetzung enthält.

Es gibt auch eine Streaming-Version dertranslate()-Methode —Translator.translateStreaming() — die es Ihnen ermöglicht, die Übersetzung alsReadableStream zurückzugeben. Dies kann nützlich sein, wenn sehr große Textmengen übersetzt werden müssen:

const stream = translator.translateStreaming(myTextString);let translation = "";for await (const chunk of stream) {  translation += chunk;}console.log("Stream complete");console.log(translation);

Unterstützungskonfiguration prüfen

Bevor Sie einLanguageDetector- oderTranslator-Objekt erstellen, können Sie prüfen, ob Ihre gewünschte Sprachkonfiguration vom aktuellen Browser unterstützt wird, indem Sie die statischen MethodenLanguageDetector.availability() undTranslator.availability() verwenden. Zum Beispiel:

const detectorAvailability = await LanguageDetector.availability({  expectedInputLanguages: ["en-US", "ja"],});const translatorAvailability = await Translator.availability({  sourceLanguage: "en",  targetLanguage: "ja",});

Diese Methoden geben einen enumerierten Wert zurück, der angibt, ob die Unterstützung für die angegebenen Optionen verfügbar ist oder verfügbar sein wird:

• downloadable bedeutet, dass die Implementierung die angeforderten Optionen unterstützt, aber ein Modell oder einige Feinabstimmungsdaten heruntergeladen werden müssen.
• downloading bedeutet, dass die Implementierung die angeforderten Optionen unterstützt, aber ein laufender Download abgeschlossen werden muss.
• available bedeutet, dass die Implementierung die angeforderten Optionen ohne neue Downloads unterstützt.
• unavailable bedeutet, dass die Implementierung die angeforderten Optionen nicht unterstützt.

Wenn ein Download erforderlich ist, wird er automatisch durch den Browser gestartet, sobald eineLanguageDetector- oderTranslator-Instanz mit der entsprechendencreate()-Methode erstellt wird. Sie können den Download-Fortschritt automatisch mit einemmonitor verfolgen.

Vorgänge abbrechen und Instanzen zerstören

Sie können einen ausstehenden Erkennungs- oder Übersetzungsvorgang mit einemAbortController abbrechen, wobei das zugehörigeAbortSignal innerhalb des Optionsobjekts der Methode alssignal-Eigenschaftswert enthalten ist. Zum Beispiel würde ein Abbruch einesTranslator.create()-Vorgangs so aussehen:

const controller = new AbortController();const translator = await Translator.create({  sourceLanguage: detectedLanguage,  targetLanguage: formData.get("translateLanguage"),  signal: controller.signal,});// ...controller.abort();

Nachdem eineLanguageDetector- oderTranslator-Instanz erstellt wurde, können Sie ihre zugewiesenen Ressourcen freigeben und jegliche weitere Aktivität stoppen, indem Sie ihre MethodeLanguageDetector.destroy()/Translator.destroy() aufrufen. Es wird empfohlen, dies zu tun, nachdem Sie das Objekt nicht mehr benötigen, da es viele Ressourcen verbrauchen kann.

translator.destroy();detector.destroy();

Wenn eincreate()-Aufruf einen zugehörigenAbortController hat und Sie dessen MethodeAbortController.abort() nach dem erfolgreichencreate()-Aufruf aufrufen, hat dies den gleichen Effekt wie ein Aufruf vondestroy() auf das resultierendeLanguageDetector- oderTranslator-Objekt.

Download-Fortschritt überwachen

Wenn das AI-Modell für eine bestimmte Erkennung oder Übersetzung herunterlädt (availability() gibtdownloadable unddownloading zurück), ist es hilfreich, dem Benutzer Feedback zu geben, um ihm mitzuteilen, wie lange es dauert, bis der Vorgang abgeschlossen ist.

DieTranslator- undLanguageDetector-Methodencreate() können einemonitor-Eigenschaft akzeptieren, deren Wert eine Callback-Funktion ist, die eineCreateMonitor-Instanz als Argument nimmt.CreateMonitor hat eindownloadprogress-Ereignis, das bei Fortschritten im Download des AI-Modells ausgelöst wird.

Sie können dieses Ereignis verwenden, um Ladefortschrittsdaten anzuzeigen:

translator = await Translator.create({  sourceLanguage: "en",  targetLanguage: "ja",  monitor(monitor) {    monitor.addEventListener("downloadprogress", (e) => {      console.log(`Downloaded ${Math.floor(e.loaded * 100)}%`);    });  },});

Wenn die angegebenen Sprachen nicht unterstützt werden, wird kein Download gestartet und einNotSupportedErrorDOMException wird ausgelöst.

Nutzungsquoten

Einige Implementierungen haben eine Eingabequote, die regelt, wie viele Vorgänge eine Website in einem bestimmten Zeitraum anfordern kann. Die gesamte Quote kann über die EigenschaftenTranslator.inputQuota/LanguageDetector.inputQuota abgerufen werden, während die Quotenverwendung für eine bestimmte Übersetzung oder Spracherkennung mit den MethodenTranslator.measureInputUsage()/LanguageDetector.measureInputUsage() zurückgegeben werden kann:

Zum Beispiel gibt das untenstehende Snippet die gesamte Eingabequote überTranslator.inputQuota und die Eingabequote für die Übersetzung eines bestimmten Texts überTranslator.measureInputUsage() zurück.

Wir prüfen dann, ob die individuelle Quotenverwendung für diesen String größer ist als die insgesamt verfügbare Quote. Wenn ja, werfen wir einen entsprechenden Fehler; wenn nicht, beginnen wir mit der Übersetzung des Strings mittranslate().

const translator = await Translator.create({  sourceLanguage: "en",  targetLanguage: "ja",});const totalInputQuota = translator.inputQuota;const inputUsage = await translator.measureInputUsage(myTextString);if (inputUsage > totalInputQuota) {  throw new Error("Insufficient quota to translate.");} else {  console.log("Quota available to translate.");  const translation = await translator.translate(myTextString);  // ...}

Wenn Sie versuchen, eine Spracherkennungs- oder Übersetzungsaktion auszuführen, die das verfügbare Kontingent überschreitet, wird einQuotaExceededErrorDOMException ausgelöst.

Komplettes Beispiel

Schauen wir uns ein vollständiges Beispiel an, das die Translator- und Language Detector-APIs in Aktion zeigt.

HTML

In unserem Markup definieren wir zuerst ein Eingabe-<form>, das es dem Benutzer ermöglicht, den zu übersetzenden Text und die zu übersetzende Sprache festzulegen. Dies beinhaltet ein<textarea> zum Eingeben des Textes selbst, ein<output>-Element zur Anzeige der erkannten Sprache und ein<select>-Element zum Auswählen einer Übersetzungssprache.

<h2>Input</h2><form>  <div>    <label for="translate-text">Enter text to translate:</label>    <textarea name="translateText" rows="6"></textarea>    <output>Detected language: </output>  </div>  <div>    <label for="translate-language">Choose translation language:</label>    <select name="translateLanguage">      <option value="en" selected>English (en)</option>      <option value="fr">French (fr)</option>      <option value="de">German (de)</option>      <option value="it">Italian (it)</option>      <option value="zh">Mandarin Chinese (zh)</option>      <option value="zh-Hant">Taiwanese Mandarin (zh-Hant)</option>      <option value="ja">Japanese (ja)</option>      <option value="pt">Portuguese (pt)</option>      <option value="ru">Russian (ru)</option>      <option value="es">Spanish (es)</option>      <option value="tr">Turkish (tr)</option>      <option value="hi">Hindi (hi)</option>      <option value="vi">Vietnamese (vi)</option>      <option value="bn">Bengali (bn)</option>    </select>  </div>  <button type="submit">Translate</button></form>

Die zweite Hälfte unseres Markups beinhaltet ein<p>-Element zur Anzeige der erzeugten Übersetzung.

<h2>Translation output</h2><p></p>

* {  box-sizing: border-box;}html {  font-family: "Helvetica", "Arial", sans-serif;}body {  max-width: 600px;  margin: 0 auto;}form div {  display: flex;  flex-direction: column;  gap: 10px;  margin-bottom: 20px;}select,textarea,.translate-output {  padding: 5px;}.translate-output {  min-height: 150px;  border: 1px solid black;  width: 100%;  display: block;}.error {  color: red;}

Beachten Sie, dass wir das CSS für dieses Beispiel nicht zeigen, da keiner davon relevant ist, um die Translator- und Language Detector-APIs zu verstehen.

JavaScript

In unserem Skript beginnen wir mit der Erfassung von Referenzen auf das<form>,<textarea>, Submit-<button>, Übersetzungsausgabe-<p> und Spracherkennungs-<output>-Elemente. Wir deklarieren auch eine Variable namensdetectedLanguage zur Aufnahme der Ergebnisse von Spracherkennungsaktionen.

const form = document.querySelector("form");const textarea = document.querySelector("textarea");const submitBtn = document.querySelector("button");const translateOutput = document.querySelector(".translate-output");const detectedLanguageOutput = document.querySelector(".detected-language");let detectedLanguage = "";

Als nächstes verwenden wir die MethodeEventTarget.addEventListener(), um zwei Ereignisse abzuhören:

• submit-Ereignisse auf dem<form>-Element; bei Einreichung des Formulars wird die FunktionhandleTranslation() aufgerufen.
• input-Ereignisse auf dem<textarea>-Element; wenn der aktuelle<textarea>-Wert geändert wird, wird die FunktiondetectLanguage() aufgerufen.

form.addEventListener("submit", handleTranslation);textarea.addEventListener("input", detectLanguage);

Die nächste definierte FunktiondetectLanguage() prüft zuerst, ob der Wert des<textarea>-Elements länger als 20 Zeichen ist. Wenn ja, führen wir die Spracherkennung fort. Wenn nicht, deaktivieren wir die Schaltfläche zum Absenden und zeigen eine Nachricht imtextContent des<output>-Elements an, die besagt, dass der Text zu kurz ist, um die Sprache zu erkennen. Wir tun dies, weil die Spracherkennung normalerweise nicht gut mit einzelnen Wörtern und sehr kurzen Phrasen funktioniert. Wenn Sie häufig mit kurzem Text arbeiten, testen Sie sorgfältig mit Ihren Prioritätssprachen und geben Sie das Ergebnis als unbekannt zurück, wenn das Vertrauen zu gering ist.

Beim Erkennen der Sprache des eingegebenen Textes erstellen wir eineLanguageDetector-Instanz mit der Methodecreate(), die einenmonitor enthält, um den Download-Fortschritt zu protokollieren, falls das Modell eine Weile zum Herunterladen benötigt. Wir erkennen dann die Sprache mit der Methodedetect(), indem wir ihr den<textarea>-Wert übergeben. Wenn die Ergebnisse zurückgegeben werden, schreiben wir die Sprache und das Vertrauen des besten Ergebnisses in das<output>-Element. In komplexeren Apps möchten Sie möglicherweise mehrere Ergebnisse berichten und dem Benutzer möglicherweise die Wahl der Sprache lassen, aber das wird für die Demo genügen.

Schließlich setzen wir die Schaltfläche zum Absenden so, dass sie nicht deaktiviert ist, damit das Formular eingereicht werden kann, um die Übersetzung zu starten.

async function detectLanguage() {  if (textarea.value.length > 20) {    const detector = await LanguageDetector.create({      monitor(monitor) {        monitor.addEventListener("downloadprogress", (e) => {          console.log(`Downloaded ${e.loaded * 100}%`);        });      },    });    const results = await detector.detect(textarea.value);    detectedLanguageOutput.textContent = `Detected language: ${      results[0].detectedLanguage    }. Confidence: ${results[0].confidence.toFixed(4)}`;    detectedLanguage = results[0].detectedLanguage;    submitBtn.disabled = false;  } else {    detectedLanguageOutput.textContent = `Text too short to accurately detect language.`;    detectedLanguage = "";    submitBtn.disabled = true;  }}

Nun definieren wir diehandleTranslation()-Funktion. Nachdem wir die Standardübermittlung des Formulars verhindert haben, erstellen wir eine neueFormData-Objektinstanz, die unsere<form>-Datenname/Wert-Paare enthält. Dann führen wir einen Datengültigkeitstest durch, um zu überprüfen, ob die erkannte<textarea>-Inhaltssprache dieselbe ist wie die gewählte Übersetzungssprache (translateLanguage). Wenn ja, drucken wir eine Fehlermeldung in das<p> mit der Klassetranslate-output.

async function handleTranslation(e) {  e.preventDefault();  const formData = new FormData(form);  if (formData.get("translateLanguage") === detectedLanguage) {    translateOutput.innerHTML = `<span>Input language and translation language are the same.</span>`;    return;  }  translateOutput.innerHTML = "";

Wenn der Test erfolgreich ist, öffnen wir einentry { ... }-Block. Wir beginnen mit der Überprüfung der Verfügbarkeit des Modells für die Übersetzung zwischen der erkannten Eingabe- und gewählten Ausgabesprache mithilfe der Methodeavailability():

• Wenn esunavailable zurückgibt, drucken wir eine passende Fehlermeldung in das<p> mit der Klassetranslate-output.
• Wenn esavailable zurückgibt, erstellen wir einen Übersetzer mit der Methodecreate(), indem wir ihm die erkannte Eingabe und gewählte Ausgabesprache übergeben. Das benötigte AI-Modell ist verfügbar, also können wir es sofort verwenden.
• Wenn es einen anderen Wert zurückgibt (das heißt,downloadable oderdownloading), führen wir denselbencreate()-Methodenaufruf aus, aber diesmal fügen wir einenmonitor hinzu, der den Prozentsatz des heruntergeladenen Modells in dastranslate-output-<p> druckt, jedes Mal, wenn dasdownloadprogress-Ereignis ausgelöst wird.

  try {    const availability = await Translator.availability({      sourceLanguage: detectedLanguage,      targetLanguage: formData.get("translateLanguage"),    });    let translator;    if (availability === "unavailable") {      translateOutput.innerHTML = `<span>Translation not available; try a different language combination.</span>`;      return;    } else if (availability === "available") {      translator = await Translator.create({        sourceLanguage: detectedLanguage,        targetLanguage: formData.get("translateLanguage"),      });    } else {      translator = await Translator.create({        sourceLanguage: detectedLanguage,        targetLanguage: formData.get("translateLanguage"),        monitor(monitor) {          monitor.addEventListener("downloadprogress", (e) => {            translateOutput.textContent = `Downloaded ${Math.floor(              e.loaded * 100            )}%`;          });        },      });    }

Als nächstes setzen wir den Inhalt des<p> auf eine ausstehende Nachricht und deaktivieren die Schaltfläche zum Absenden, bevor wirTranslator.translate() aufrufen, um die eigentliche Übersetzung durchzuführen, indem wir ihr den<textarea>-Wert übergeben. Sobald die Übersetzung abgeschlossen ist, zeigen wir sie im Ausgabe-<p> an, bevor die Schaltfläche zum Absenden wieder aktiviert wird.

translateOutput.textContent = "...generating translation...";submitBtn.disabled = true;const translation = await translator.translate(formData.get("translateText"));translateOutput.textContent = translation;submitBtn.disabled = false;

Schließlich fügen wir den Gegenpartcatch() { ... } destry-Blocks hinzu. Wenn der Inhalt vontry eine Ausnahme auslöst, zeigen wir sie im Ausgabe-<p> an.

  } catch (e) {    translateOutput.innerHTML = `<span>${e}</span>`;  }}

Ergebnis

Das gerenderte Beispiel sieht so aus:

Versuchen Sie, einen Textkörper in das<textarea> einzugeben, und beachten Sie, wie die erkannte Sprache und das Vertrauen nur gemeldet werden, wenn die Anzahl der Zeichen größer als 20 wird. Wählen Sie eine andere Übersetzungssprache als Ihren Eingabetext und drücken Sie die Abschicken-Schaltfläche, um eine AI-generierte Übersetzung zu erzeugen.

Einige der Übersetzungssprachoptionen stehen möglicherweise nicht in Ihrem Browser zur Verfügung, selbst wenn er die APIs unterstützt.